Card — 3D Secure

When you send paymentMethod: "CARD" and force3D: true to POST /payments/direct/payment, the card is charged from your own server with bank authentication. Before the card is charged, the buyer confirms the transaction with their bank (SMS code, banking app approval, biometrics). Use it when you want liability shift and when you want to save the card. The platform runs the bank round-trip for you; you start the payment, redirect the buyer and receive the result.

How it works

Authentication

The endpoint requires Step-Up: your Authorization: Bearer at_… token and an Ed25519 signature over the request. Every request carries these headers:

How to build the signature is described in Authentication. The endpoint requires the Payment Gateway product to be enabled on your account.

Request

POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment
Content-Type: application/json

Card fields

card, force3D, installment and installmentQuoteToken can only be sent with paymentMethod: "CARD". For card, routing chooses the provider; providerCode is not sent.

Order fields

The amount is sent only in amount; the removed amount fields get 400 payment.amount.field_removed. Sending a field that is not defined here rejects the request with 400 VALIDATION_ERROR.

card

• When sent, expireMonth and expireYear must have two digits.
• For a raw card charge send cardHolderName, cardNumber, expireMonth, expireYear and cvcNumber. For a saved card charge send cardUserKey and cardToken instead of the raw card fields.

buyer

buyer is optional. If you send it, every field marked "Yes" below must be filled. On a Checkout Form intent (POST /payments/intents, POST /payments/marketplace/intents) this rule does not apply: every field is optional, and the fields you send are checked for type and length.

Required-field rule, how it differs from customerId, and error field paths: Buyer.

Address

shippingAddress and billingAddress share the same shape. If you send the object, all five fields are required.

How the two addresses differ and error field paths: Addresses.

basketItems[]

The sum of the items' price must equal amount; otherwise the request is rejected with 400 VALIDATION_ERROR. The installment fee is not added to the items.

Example request

# See the Authentication page for how the Step-Up signature headers are computed.
curl -X POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment \
  -H "Authorization: Bearer at_test_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: mk_test_sk_..." \
  -H "X-Date: 2026-10-11T09:00:00.000Z" \
  -H "X-Nonce: 7d2c4e1a-3b9f-4a6d-8c51-2e0f9b7a6d34" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORD-84721-1" \
  -d '{
    "paymentMethod": "CARD",
    "force3D": true,
    "amount": 10050,
    "currency": "TRY",
    "orderId": "ORD-84721",
    "customerId": "cust_7788",
    "callbackUrl": "https://merchant.example.com/payments/3d-result",
    "card": {
      "cardHolderName": "Ada Yilmaz",
      "cardNumber": "5400000000000004",
      "expireMonth": "12",
      "expireYear": "30",
      "cvcNumber": "123"
    }
  }'

Response

The payment waits in AWAITING_3D until the bank round-trip completes. The response is HTTP 202 with envelope status: "partial" and code: "AWAITING_3D":

{
  "status": "partial",
  "code": "AWAITING_3D",
  "message": "…",
  "data": {
    "paymentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "orderId": "ORD-84721",
    "status": "AWAITING_3D",
    "paymentMethod": "CARD",
    "providerCode": "<providerCode>",
    "action": {
      "id": "3ds_9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
      "type": "REDIRECT",
      "expiresAt": "2026-10-11T09:15:00.000Z",
      "redirect": { "url": "/api/v1/payments/threed/<redirect-token>" }
    }
  },
  "statusCode": 202,
  "requestId": "…"
}

• action.redirect.url is relative; resolve it against https://api-gateway.lunixi.com and send the buyer's browser there promptly (a browser GET).
• The redirect address is single-use. Opening it a second time shows the buyer an error page.
• A payment abandoned in AWAITING_3D is settled by the platform: it asks the provider for the real outcome and binds the payment to its true state (FAILED if nothing was charged, CAPTURED if the charge went through).
• Do not call confirm for the card 3D Secure action; the result is verified on the return and reported by webhook.

If the request is rejected before authentication (limit, risk, invalid installment quote), the response is HTTP 400: envelope status: "failure", data.status: "FAILED", and code carries the reason. Branch on code; the message text may change. For the envelope fields see Error Handling.

The signed callback to your server

After the bank round-trip, the buyer's browser is sent to your callbackUrl with an HTML form POST (application/x-www-form-urlencoded). The body carries these fields:

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

Use the callback to drive the buyer's UI (show a result page, resume the session). The buyer's browser may never reach your callbackUrl (closed tab, lost connection); the webhook is always sent.

Status transitions

Saved cards

Saving a card

A card is saved during a payment made with 3D Secure; there is no separate "save card" call. Send customerId together with force3D: true and add card.cardSave: true together with the raw card; optionally name the card with card.cardName. The card is stored under the customerId key if authentication and the charge succeed; it is not stored if the payment fails.

When the payment response carries a card newly saved in this payment, it is in data.savedCard:

You can always read saved cards with GET /payments/cards. For enabling card storage in the panel and listing cards, see Stored Cards.

3D payment with a saved card

There is no separate endpoint. Put cardUserKey and cardToken into the card object instead of the raw card fields:

{
  "paymentMethod": "CARD",
  "force3D": true,
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORD-84724",
  "callbackUrl": "https://merchant.example.com/payments/3d-result",
  "card": {
    "cardUserKey": "cust_7788",
    "cardToken": "9f3c1a7e-…",
    "cvcNumber": "123"
  }
}

The Checkout Form's single-use card token cannot be used here; cardToken is the permanent saved-card reference.

Installments

If the buyer picked an installment option, send installment together with the installmentQuoteToken you received from the installment quote.

• installmentQuoteToken is required when installment is 2 or more.
• amount stays the basket total; you do not send the installment fee. The system computes the fee from the binding quote and adds it to the charged amount: charged amount = amount + installment fee. What you displayed is exactly what is charged.
• The amount fields in lookups and webhooks show this charged amount.
• If the token is missing, expired or does not match the request, the payment becomes FAILED and the response is 400 INSTALLMENT_QUOTE_REJECTED. Fetch a fresh quote and resubmit with a new Idempotency-Key.

Pre-authorization

To hold the amount before charging it, send "preauth": true in the request. When the buyer completes the bank verification no money is charged: the payment becomes AUTHORIZED instead of CAPTURED and payment.authorized is sent. You later charge the amount with capture or remove the hold with void.

• The provider must also support pre-authorization over 3D Secure. Providers that do not are removed from the candidates; 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 before the payment starts with 422 payment.preauth.three_ds_unsupported. The instruction is never turned into an immediate charge.
• Capture, partial capture, void, expiry and errors: Pre-authorization, Capture & Void.

Idempotency

Idempotency-Key is required (at most 200 characters). Without it the request gets 400 payment.operation.idempotency_key_required and is not processed. Use a value that identifies the attempt, not the payment (for example ORD-84721-1).

Errors

Common codes for method and provider selection: Payment — Error codes.

Webhooks

The data of the events carries paymentMethod: "CARD" and the providerCode of the provider that processed the payment. For delivery and signature verification see Webhooks.

Next steps

• Card — 2D — charging without bank authentication
• Installments & BIN — installment table and binding quote
• Stored Cards — managing saved cards
• Refunds — returning money after capture
• Webhooks — payment events