Card Payment — 2D

A 2D payment charges the card in a single request, with no bank-side 3D Secure authentication and no redirect. The buyer never leaves the form and the result comes back immediately. The trade-off: without 3D authentication there is no liability shift.

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

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

How it works

The 3D decision: when the form does not call 2D

2D is a request, not a guarantee. The intent's 3D decision determines which endpoint runs. The decision is resolved when the intent is created, from the sources below, and is fixed on the intent:

If the decision is 3D, the SDK uses the 3D Secure endpoint directly. A POST /payments/form/2d call for the same intent is refused with 409 THREE_D_REQUIRED; there is no silent switch to 3D. When the SDK receives this response it sends the same body once to POST /payments/form/3d and the flow continues as 3D Secure.

You set these fields when creating the intent; full description → Checkout Form.

When the provider cannot do 2D: automatic 3D Secure

Even when your policy says 2D, the provider routing the payment may not be permitted to perform 2D (non-secure) sales under its agreement. On the Checkout Form the buyer is at the screen, so the platform does not decline the charge — it upgrades it to 3D Secure:

• POST /payments/form/2d returns a 3D redirect response instead of CAPTURED. The SDK sends the buyer to bank authentication; from there the flow proceeds like the 3D Secure flow.
• The payment is marked with escalationReason: "PROVIDER_2D_UNSUPPORTED", so you can tell that it was requested as 2D but moved to 3D because of provider capability.
• The intent becomes 3D. Sending POST /payments/form/2d again for the same intent is refused with 409 THREE_D_REQUIRED.

Endpoint reference — POST /payments/form/2d

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

Authentication does not use an Authorization header; it has two parts:

• token in the body: the form token from the intent response.
• The session proof: the pg_checkout_session cookie. Where cookies cannot be carried (WebView, third-party cookie blocking), the same proof is sent in the body as checkoutSessionProof.

Fields

POST /payments/form/3d uses the same body.

The card is not saved on a 2D charge. If the buyer ticks "save my card" the payment is not affected; cards are saved only with 3D Secure.

Example body

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

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

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

A successful charge returns 200:

{
  "status": "success",
  "code": "PAYMENT_CAPTURED",
  "message": "Payment processed",
  "data": {
    "id": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "orderId": "ORD-9988",
    "amount": 10050,
    "currency": "TRY",
    "status": "CAPTURED"
  },
  "statusCode": 200,
  "requestId": "…"
}

• On 2D, data.status is normally final: CAPTURED on success, FAILED on decline.
• data.amount is the charged amount: the intent's amount, plus the installment fee the system added for an installment payment.
• If you supplied a callbackUrl, the response also contains the signed form that carries the buyer to your result page. The SDK submits it. The fields are the same as on the 3D Secure return → The signed POST to your result page.
• A charge upgraded to 3D because of provider capability returns the 3D Secure endpoint's response (status: "partial", AWAITING_3D) → Card Payment — 3D Secure › Response.
• A transaction whose outcome is not yet final returns status: "partial" (HTTP 202); the webhook delivers the final state.

Pre-authorization

You do not request a pre-authorization from the form: send "preauth": true when you create the intent with POST /payments/intents. The form charges according to this decision; when the payment succeeds it becomes AUTHORIZED instead of CAPTURED and payment.authorized is sent. Providers that do not support pre-authorization are removed from the candidates; if no suitable provider remains, the payment becomes FAILED with decline code PREAUTH_NOT_SUPPORTED.

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 — 3D Secure: the flow when the 3D decision or provider capability requires 3D
• Checkout Form: creating the intent, force3D and settings.threeD
• Installments & BIN: the displayed amount is the charged amount
• Refunds: returning money after capture