APG PayAPG Paydocs

Integration

3-D Secure

Send the payer to their bank for a challenge, and finish the payment when they come back.

3-D Secure moves liability for a fraudulent payment from you to the card issuer, in exchange for the payer sometimes being challenged. On some cards and in some regions it is not optional.

The shape is: ask for it, get told a challenge is needed, send the payer, finish the payment.

requestThreeDS asks; the merchant's own policy decides when you do not. returnUrl is required for any card payment that might be challenged, it is where the payer comes back to, and without it there is nowhere to send them.

Request
curl -X POST "https://api.tst.au.apgpay.dev/bezel/transactions" \
  -H "Authorization: Bearer $API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "<useOrderIdFromSeed>",
  "paymentTokenId": "<usePaymentTokenIdFromSeed>",
  "authoriseOnly": null,
  "requestThreeDS": true,
  "returnUrl": "https://bluehillcoffee.example/checkout/complete",
  "offSession": null,
  "cardStatementName": null,
  "cardStatementCity": null,
  "referenceTransactionId": "web-order-10423",
  "type": "TranCmdCreate"
}'
"Authentication required" is its own outcome, not an error. The payment has not failed and must not be retried, it is waiting for the payer. Treating it as a failure is the most common 3DS integration bug and it shows up as customers charged twice.

The continuation is a create, not an update, and that is the platform's shape rather than a choice: it needs the order and the payment token, and a transaction records neither, a token is consumed into a transaction and the link is not kept.

Request
curl -X POST "https://api.tst.au.apgpay.dev/bezel/transactions" \
  -H "Authorization: Bearer $API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orderId": "<useOrderIdFromSeed>",
  "paymentTokenId": "<usePaymentTokenIdFromSeed>",
  "authoriseOnly": null,
  "requestThreeDS": null,
  "returnUrl": "https://bluehillcoffee.example/checkout/complete",
  "offSession": null,
  "cardStatementName": null,
  "cardStatementCity": null,
  "referenceTransactionId": "web-order-10423",
  "type": "TranCmdCreate"
}'
To reach a challenge in sandbox, choose the amount. The last three digits of the minor-unit amount select the authentication outcome, and the testing guide lists them.

See testing.