Card Payment — 3D Secure

3D Secure has the buyer confirm the transaction with their own bank before the card is charged (SMS code, banking app approval, biometrics). This flow runs when you want liability shift, when your 3D policy requires it, or when the bank asks for authentication. The platform routes the transaction to a suitable provider and handles the bank round-trip for you.

This page covers the Checkout Form path. The Checkout Form SDK calls POST /payments/form/3d itself from the buyer's browser and also redirects the buyer to the bank; you do not write requests to this endpoint. The code you write is creating the intent on your server, mounting the form on your page and handling the result → Checkout Form.

If you send card data from your own server, this page is not for you → Card — 3D Secure.

How it works

When the form uses 3D Secure

The intent's 3D decision determines which endpoint runs. The decision is resolved when the intent is created, from force3D, settings.threeD and the panel 3D policy, and is fixed on the intent → Card Payment — 2D › The 3D decision.

The form charges with 3D Secure when:

• The intent's 3D decision is 3D. The SDK calls POST /payments/form/3d directly.
• The decision is 2D, but the provider routing the payment cannot perform 2D sales. The platform upgrades the charge to 3D Secure and marks the payment with escalationReason: "PROVIDER_2D_UNSUPPORTED" → Card Payment — 2D › When the provider cannot do 2D.

In both cases the flow proceeds as described on this page.

Endpoint reference — POST /payments/form/3d

This section is for reference: the SDK builds and sends the body.

Authentication does not use an Authorization header; it uses the form token in the body and the session proof (the pg_checkout_session cookie or checkoutSessionProof). The body is the same as for POST /payments/form/2d → field table.

Example body

The body the SDK sends (secure-fields mode, 3 installments):

{
  "token": "<form token from the intent response>",
  "installment": 3,
  "paymentCards": {
    "secureCardToken": "<cardToken from the tokenize response>"
  },
  "paymentChannel": "WEB",
  "browserFingerprint": "<fingerprint>",
  "installmentQuoteToken": "<quote token from the installment table>"
}

installmentQuoteToken is sent for installment payments; the charged amount is bound to the quote shown to the buyer.

The Checkout Form SDK builds this body. The SDK also adds the total it displayed to the buyer as an internal form field; it is not an amount you send. The server computes the charged amount from the intent's amount and, for installments, the installment fee in the binding quote.

Response

The payment waits in AWAITING_3D until the bank round-trip completes. The response returns with status: "partial" (HTTP 202):

{
  "status": "partial",
  "code": "AWAITING_3D",
  "message": "Payment processed",
  "data": {
    "id": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "orderId": "ORD-9988",
    "amount": 10350,
    "currency": "TRY",
    "status": "AWAITING_3D",
    "threeDRedirectUrl": "/api/v1/payments/threed/<single-use token>"
  },
  "statusCode": 202,
  "requestId": "…"
}

data.amount is the charged amount: the intent's amount plus the installment fee the system added from the installment quote. In the example the intent amount is 10050 and the amount charged over 3 installments is 10350.

The SDK performs the redirect itself. A payment abandoned in AWAITING_3D is picked up by a background cleanup job: it asks the provider for the real outcome and binds the payment to its true final state (FAILED if nothing was charged, CAPTURED if the charge landed).

The signed POST to your result page

After the bank round-trip, the buyer's browser is sent to the callbackUrl you supplied on the intent with an HTML form POST (application/x-www-form-urlencoded). The same POST also arrives after a successful 2D charge. The body carries these fields:

The canonical string (canonical) is every field except _signature (including _timestamp), sorted by key, each written as key=value and joined with a newline (\n).

Use this POST to drive the buyer's UI (render the result page, resume the session). The browser may never reach your callbackUrl (closed tab, network loss); the webhook is sent in every case.

Status transitions

Card storage

On the form, a card is saved when the buyer ticks "save my card" and the charge completes successfully with 3D Secure. This requires:

• Card storage enabled in the form settings of your panel.
• The intent created with customerId (or cardUserKey); the card is saved under that key.

Because the payment response goes to the buyer's browser, the permanent card reference is not returned there. After the payment completes, read the cards from your server with GET /payments/cards → Stored Cards.

Pre-authorization

You do not request a pre-authorization from the form: send "preauth": true when you create the intent with POST /payments/intents. When the buyer completes the bank verification no money is charged; the payment becomes AUTHORIZED instead of CAPTURED and payment.authorized is sent.

• The provider must also support pre-authorization over 3D Secure. If no suitable provider remains, the payment becomes FAILED with decline code PREAUTH_3DS_NOT_SUPPORTED.
• If no provider supports pre-authorization over 3D Secure at all, the request is rejected with 422 payment.preauth.three_ds_unsupported. The instruction is never turned into an immediate charge.

Capture, void and the 7-day window: Pre-authorization, Capture & Void.

Errors

Error responses use the common error envelope; branch on code, not on message → Error Handling.

Webhooks

Delivery and signature verification → Webhooks.

Next steps

• Card Payment — 2D: charging without bank authentication, and the sources of the 3D decision
• Checkout Form: creating the intent, callbackUrl, force3D and settings.threeD
• Stored Cards: reading saved cards and showing them on the form
• Installments & BIN: the displayed amount is the charged amount
• Refunds: returning money after capture