Pre-authorization, Capture & Void

With a pre-authorization the payment is not charged immediately: the buyer's bank holds the amount and the payment waits in AUTHORIZED. When you are ready to fulfil the order you capture all or part of the amount; if you will not fulfil it you void the hold.

Typical uses: charging when the order ships, deposits and reservations, partially fulfilled orders, payments held until a review finishes. The same hold, capture and void model is also used for the card parts of a split payment.

You request a pre-authorization with the preauth field of the payment request. This page describes every pre-authorization rule in one place; the payment pages show the field in their own requests and link here.

How it works

Requesting a pre-authorization

There is no separate pre-authorization endpoint. You send the preauth field in the request that starts the payment:

The field behaves the same in both requests:

A pre-authorization instruction is never silently turned into an immediate charge. The payment is never sent to a provider that cannot honour it; it is either routed to another suitable provider or rejected with an explicit error (see Which methods support it).

{
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORD-84722",
  "callbackUrl": "https://shop.example.com/payment/result",
  "preauth": true
}

Which methods support it

The provider that processes the payment must support pre-authorization.

Card

• 2D: Providers that do not support pre-authorization are removed from the candidates and the payment is routed to one that does. If no suitable provider remains, the payment becomes FAILED with decline code PREAUTH_NOT_SUPPORTED.
• 3D Secure: 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.
• In the 3D Secure flow no money is charged when the buyer completes the bank verification; the payment becomes AUTHORIZED.

Non-card methods

• Whether a method and a provider support pre-authorization is shown by the preauth field of the GET /payments/methods response (on the method row and on each provider).
• If you send preauth: true with a method that does not support it, the request is rejected with 422 payment.preauth.unsupported_for_method. The payment is not started and nothing is charged.
• For a pre-authorization intent the Checkout Form only shows methods and providers that support pre-authorization.

Capture

POST /payments/{id}/capture charges the amount of an AUTHORIZED payment. The endpoint requires Step-Up (Bearer token and Ed25519 signature; see Authentication).

• When amount is lower than the authorized amount a partial capture is made and the status becomes PARTIALLY_CAPTURED. You can capture the rest with another capture request; when the total reaches the authorized amount the status becomes CAPTURED.
• The total captured can never exceed the authorized amount; a request that would exceed it is rejected with 400 payment.capture.amount_exceeded.

# See the Authentication page for how the Step-Up signature headers are computed.
curl -X POST https://api-gateway.lunixi.com/api/v1/payments/9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30/capture \
  -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: 3c1d8e2a-7b4f-4e6a-9d0c-5a2b1e8f7c64" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: cap-ORD-84722-1" \
  -d '{
    "paymentIntentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "amount": 7500
  }'

Capture response

{
  "status": "success",
  "code": "PAYMENT_PARTIALLY_CAPTURED",
  "message": "…",
  "data": {
    "id": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "amount": 10050,
    "currency": "TRY",
    "status": "PARTIALLY_CAPTURED"
  },
  "details": {
    "capturedAmount": "7500",
    "refundedAmount": "0",
    "remainingCapturable": "2550",
    "remainingRefundable": "7500"
  },
  "statusCode": 200,
  "requestId": "…"
}

On a full capture code is PAYMENT_CAPTURED and data.status is CAPTURED. The amounts in details are minor-unit strings.

Void

POST /payments/{id}/void removes a hold that has not been captured; no money moves and the payment becomes VOIDED. The endpoint accepts an API-key signature or a panel session; when calling it from the API, send the signature headers described on Authentication.

• Idempotency-Key is required; without it the request is rejected with 400 payment.operation.idempotency_key_required.
• The body is empty ({}).
• The response has code PAYMENT_VOIDED and data.status VOIDED.

# See the Authentication page for how the Step-Up signature headers are computed.
curl -X POST https://api-gateway.lunixi.com/api/v1/payments/9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30/void \
  -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: 6e2a9c41-0d3b-4f7a-8b15-9c4e2d1f7a03" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: void-ORD-84722-1" \
  -d '{}'

Void response

{
  "status": "success",
  "code": "PAYMENT_VOIDED",
  "message": "…",
  "data": {
    "id": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "amount": 10050,
    "currency": "TRY",
    "status": "VOIDED"
  },
  "statusCode": 200,
  "requestId": "…"
}

Expiry

• A pre-authorization that is neither captured nor voided becomes EXPIRED (final status) on the platform 7 days after the payment was created, and payment.expired is sent. The window cannot be changed per account.
• An EXPIRED payment can no longer be captured.
• The hold on the card is not released by this event. No cancellation is sent to the bank; the hold drops off according to the bank's own period. To release the hold early, void it before the window ends.

Statuses

For every status see Listing Payments.

Errors

Error codes

Webhooks

For delivery and signature verification see Webhooks.

Next steps

• Checkout Form — creating the intent and the form
• Card — 2D and Card — 3D Secure — card payments
• Payment — every method from one endpoint
• Refunds — giving back charged money