Checkout Form

The hosted checkout form is the recommended way to accept card payments: your server creates a payment intent with POST /payments/intents, the buyer completes payment on Lunixi's form, and card data never touches your infrastructure. This page is the full reference for the intent create — every field, the per-request policy overrides, the response, and what happens in the browser afterwards.

How it works

<div id="lunixi-checkout-form"></div>
 
<script src="https://cdn.lunixi.com/lunixi-checkout.min.js"></script>
<script>
  const checkout = Lunixi.checkout.create({
    type: 'payment',
    target: 'lunixi-checkout-form',
    options: { token: 'the token from the intent response' },
  });
 
  checkout.mount('#lunixi-checkout-form');
</script>

3D Secure display

In the panel, under Payments → Form Settings → 3D Secure → 3D Secure display, you choose how the bank's verification screen opens:

• Automatic separate page: If the bank does not allow its verification screen to open in a window, 3D Secure is automatically restarted for the same card on a separate page. You do not need to do anything for this.
• The choice applies to card verifications in split payments. For single-card payments, the 3D Secure flow is as described on 3D Form.
• A change affects only payments started afterwards; a payment already in progress completes with the choice it started with.

Continuation page, the fields sent to your callbackUrl and error codes: Split Payments › 3D Secure and the continuation page.

Request

POST /payments/intents — Step-Up auth.

Fields

buyer object

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.

Length limits on the Checkout Form and where buyer details are used: Buyer.

shippingAddress / billingAddress object

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

How the two addresses differ and which one is used when: Addresses.

basketItems[] object

The sum of the items' price must equal amount. Item rules, error field paths such as basketItems.0.price and the optional insurance fields: Basket Items.

Amount and installments

• amount is the single amount field. Send the amount only in amount; the removed amount fields get 400 payment.amount.field_removed.
• The intent has no installment field; sending one gets 400 VALIDATION_ERROR. The buyer picks the installment in the form.
• You do not send the installment fee. The system computes it from the binding installment quote the buyer picked and adds it to the charged amount: charged amount = amount + installment fee.
• Amount fields in responses and webhooks (data.amount, capturedAmountMinor …) show the charged amount; for an installment payment the installment fee is included.

force3D — the top-level override

force3D is the per-payment 3D switch:

• force3D: true → this payment will run 3D Secure — regardless of the panel policy and regardless of anything in settings.threeD.
• force3D: false → this payment will not be forced into 3D by policy.
• Omitted → the effective policy decides (panel settings, optionally overridden per-request by settings.threeD).

An explicit force3D overrides everything — it beats the panel 3D policy and the settings.threeD override, including the amount threshold.

preauth — pre-authorization

Send "preauth": true when you create the form to take this payment as a pre-authorization:

• When the buyer completes the payment on the form, the amount is held on the card, not charged; the payment becomes AUTHORIZED and the payment.authorized webhook fires.
• Whatever charge the form makes (2D, 3D Secure or a non-card method) follows this decision; you send nothing else from the form.
• The form shows only payment methods that support pre-authorization.
• You later capture the amount or void the hold; a hold not captured in time becomes EXPIRED.

{
  "amount": 10050,
  "currency": "TRY",
  "orderId": "ORDER-1001",
  "callbackUrl": "https://merchant.example.com/payment/callback",
  "preauth": true
}

Window, supported methods and errors: Pre-authorization, Capture & Void.

settings — per-request form-settings override

settings applies on top of your merchant-panel form settings for this intent only. The override rules differ per field:

Security-sensitive form settings (identityCheck, cardStorage, installmentTab) cannot be overridden per request — they always come from the panel.

Example request

curl -X POST "https://api-gateway.lunixi.com/api/v1/payments/intents" \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -H "X-Key-Id: key_01JZ8H2M4Q" \
  -H "X-Date: 2026-07-06T12:00:00.000Z" \
  -H "X-Nonce: 9f8d2c4e-1a3b-4c5d-8e7f-0a1b2c3d4e5f" \
  -H "Digest: SHA-256=k6I5cUt...=" \
  -H "X-Signature: MEUCIQDx...==" \
  -H "Idempotency-Key: order-ORD-9988-attempt-1" \
  -d '{
    "amount": 10050,
    "currency": "TRY",
    "orderId": "ORD-9988",
    "callbackUrl": "https://shop.example.com/payment/result",
    "customerId": "c_98765432",
    "description": "Order #9988 payment",
    "buyer": {
      "name": "John", "surname": "Doe",
      "identityNumber": "12345678901",
      "email": "[email protected]", "gsmNumber": "+905350000000",
      "city": "İstanbul", "country": "Turkey",
      "zipCode": "34732", "ip": "85.34.78.112"
    },
    "basketItems": [
      { "id": "BI101", "price": 10050, "name": "Binocular",
        "category1": "Collectibles", "itemType": "PHYSICAL" }
    ],
    "settings": {
      "paymentMethods": ["card"],
      "threeD": { "mode": "auto", "forceAmountMinor": "500000" },
      "buyerProtection": { "enabled": true }
    }
  }'

Response

201 Created:

{
  "status": "success",
  "code": "CHECKOUT_INITIALIZED",
  "data": {
    "paymentId": "9c6f2b1a-4e8d-4a3f-b5e6-2d7c1a9b8e30",
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "checkoutFormContent": "<script>…</script>"
  }
}

The token is origin-bound (to metadata.allowedOrigin / your callbackUrl origin) and expires — 15 minutes by default. Expired token → create a new intent.

Errors

Webhooks

The checkout form flow emits, depending on outcome:

• payment.captured — charge completed, funds captured (2D, or 3D after the challenge)
• payment.authorized — funds reserved, for authorize-then-capture setups
• payment.failed — final decline (includes structured decline detail)
• payment.expired — an authorize-only hold expired before it was captured

Delivery and signature verification: Webhooks.

Adding insurance

You can offer your buyer insurance from the provider you have an agreement with, together with the product, in the Checkout Form. The payment request has no separate insurance parameter:

• You turn insurance on in the panel: in the Insurance menu you turn on insurance and the type you will offer, and under Form Settings > Insurance you choose where it appears in the form. If these settings are off, insurance never appears in the form; steps: Insurance › Setup.
• The optional insurance fields in your basket items determine which insurance is offered; see Basket Items › Insurance fields.
• Your payments without insurance are not affected. If you send no insurance fields, or insurance cannot be offered, the payment proceeds as usual.

How the product works and which path to choose: Insurance.

Next steps

• 3D Form — challenge, redirect and HMAC-signed callback in detail
• 2D Form — the non-3D charge path
• Installments & BIN — quote-binding: displayed amount == charged amount
• Refunds · Pre-authorization, Capture & Void
• Marketplace — the same form flow with sellers[] split
• Basket Items — item fields, error field paths and insurance fields
• Insurance — offer your buyer insurance with the product