Card — 2D

When you send paymentMethod: "CARD" to POST /payments/direct/payment without force3D (or with false), the card is charged from your own server in a single request. There is no bank-side 3D Secure authentication and no redirect; the result (success or decline) comes back in the same response. Use it for saved-card charges, server-side billing and flows where a redirect is not possible. Without 3D authentication there is no liability shift, so pair 2D charges with your own risk controls.

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.

cardSave is not sent on a 2D request: cards can only be saved with 3D Secure.

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: 0b9a6c52-6d1e-4f0e-9a51-4c3f9e2d7a10" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORD-84722-1" \
  -d '{
    "paymentMethod": "CARD",
    "amount": 10050,
    "currency": "TRY",
    "orderId": "ORD-84722",
    "customerId": "cust_7788",
    "card": {
      "cardHolderName": "Ada Yilmaz",
      "cardNumber": "5400000000000004",
      "expireMonth": "12",
      "expireYear": "30",
      "cvcNumber": "123"
    }
  }'

Response

A successful charge returns HTTP 200:

{
  "status": "success",
  "code": "PAYMENT_CAPTURED",
  "message": "…",
  "data": {
    "paymentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "orderId": "ORD-84722",
    "status": "CAPTURED",
    "paymentMethod": "CARD",
    "providerCode": "<providerCode>"
  },
  "statusCode": 200,
  "requestId": "…"
}

A declined charge returns HTTP 400. The envelope is status: "failure", the payment is data.status: "FAILED" and code carries the decline reason. When present, details.retryability (RETRYABLE, NON_RETRYABLE, UNKNOWN) tells you whether retrying the same request makes sense.

{
  "status": "failure",
  "code": "RISK_BLOCKED",
  "message": "…",
  "data": {
    "paymentId": "5d1e7a0c-2b9f-4c61-8f3e-0a4b6c8d2e91",
    "orderId": "ORD-84722",
    "status": "FAILED",
    "paymentMethod": "CARD"
  },
  "statusCode": 400,
  "requestId": "…"
}

If the request was rejected before it was processed (validation or authentication error), data is empty and code describes the error.

A charge whose outcome is not yet certain returns HTTP 202: envelope status: "partial", code: "PAYMENT_PENDING_RECONCILIATION", data.status: "NEEDS_RECONCILIATION". The platform settles the outcome by querying the provider and sends a payment.captured or payment.failed webhook. In that case do not open a new charge; wait for the webhook or check GET /payments/:id.

Branch on code; the message text may change. For the envelope fields see Error Handling.

When a 2D request becomes 3D

The 3D Secure decision is your force3D choice. The 3D settings defined for the Checkout Form (force3D on the intent, settings.threeD and the panel 3D policy) do not apply to this request.

There are two exceptions. The risk evaluation or a limit rule configured on your account may require the payment to go through 3D Secure. The response is then a 3D response instead of CAPTURED: HTTP 202, envelope status: "partial", code: "AWAITING_3D", data.status: "AWAITING_3D", and data.action is a REDIRECT action.

Handle it exactly like the 3D Secure flow: send the buyer's browser to action.redirect.url; the result arrives at your callbackUrl and your webhook. For the response fields, see Card — 3D Secure › Response; for the fields of the result posted to your callbackUrl and how to handle it, see the signed callback.

When the provider cannot do 2D

If the agreement of the provider routing your payment does not cover 2D (non-secure) sales, the charge cannot complete as 2D. A 2D charge started from your server is treated as customer-not-present (merchant-initiated) and is not upgraded to 3D automatically:

• If no 2D-capable candidate provider remains, the payment becomes FAILED with the decline code NO_2D_CAPABLE_PROVIDER.
• This outcome is permanent. Sending the same request again gives the same result; subscription or billing retries must treat it as a permanent decline.
• Take the payment with 3D Secure while the buyer is present.

Agreement capabilities (supported_operations)

Each provider credential can be limited to the operations its agreement allows. This is a permanent agreement fact on the credential and is managed in the credential form in the panel.

If supported_operations is empty (null) there is no restriction. When a list is set, only the listed operations are performed. The "Disable 2D (non-secure) sales — 3D only" setting in the routing restrictions gives the same result temporarily; the difference is that it is a reversible operational decision.

Charging a saved card

There is no separate saved-card endpoint. In the same request, put the customer key the card is stored under (cardUserKey) and the saved-card reference (cardToken) into the card object instead of the raw card fields:

{
  "paymentMethod": "CARD",
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORD-84723",
  "card": {
    "cardUserKey": "cust_7788",
    "cardToken": "9f3c1a7e-…",
    "cvcNumber": "123"
  }
}

• Cards can only be saved with 3D Secure. Sending card.cardSave: true on a 2D request rejects it with 400 payment.card.save_requires_3ds; save the card with Card — 3D Secure.
• cardToken is the storedCardToken returned to you when the card was saved. The Checkout Form's single-use card token cannot be used here.
• For enabling card storage, getting the token and listing cards, see Stored Cards.

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 payment succeeds data.status is AUTHORIZED instead of CAPTURED and payment.authorized is sent. You later charge the amount with capture or remove the hold with void.

• 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. 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-84722-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 — 3D Secure — charging with bank authentication and saving cards
• Installments & BIN — installment table and binding quote
• Stored Cards — managing saved cards
• Refunds — returning money after capture
• Webhooks — payment events