Split Payments (SplitPay)

A split payment collects one order in several parts: several cards, or cards together with non-card methods such as wallets, mobile billing (Faturana Yansıt) and promissory notes (Senetle Öde). For example, a ₺1,000 order = Card A ₺400 + Card B ₺350 + mobile billing ₺250.

The outcome is all-or-nothing:

• If every part succeeds, the order counts as paid.
• If a part fails, the holds on the cards are released and the parts already charged are refunded. The buyer pays nothing net. The rule for a non-reversible part: Failure and compensation.

In the API each part is a leg (legs[]).

Ways to split

This page covers what both ways share: the two paths, enabling, the order of the steps, rules, time limit, statuses, events, refunds, listing and detail.

Two paths

Both paths use the same rules, the same order of steps and the same events.

Enabling

In the panel, the Payments → Form Settings → Split Payment section has two independent switches. You can turn on either one or both.

The Shared settings apply to split payments that include a non-card method:

• In a split payment with a non-card method, the number of cards follows the Pay with Multiple Cards limit when that switch is on; when it is off, at most 1 card can be used.
• Only methods that are enabled in Form Settings can be part of a split payment.
• Whether a method and a provider can be used in a split payment is shown by splitEligible on the GET /payments/methods row.
• An API split payment made of cards only does not depend on the Pay with Multiple Cards switch; that switch enables multiple cards in the Checkout Form.

Order of the steps

The platform sets the order; neither you nor the buyer can change it. The order the platform sets is the steps[] list in the responses.

• In a split payment made of cards only, the cards are processed in the order you sent them.
• In a split payment with a non-card method, parts are arranged into four phases according to the method's split payment behaviour (splitBehavior): approval, card hold, reversible charge and non-reversible charge. The phases and the order within a phase: Multiple Payment Methods › Order of the steps.

When every part has succeeded, the holds on the cards (and the credit approval, if any) are captured and the order is complete.

Rules

A split payment is validated before it starts. A request that breaks a rule is rejected; no part is charged.

• Currency: every part is in the order's currency, and the chosen provider must support that currency.
• Amount: the parts add up to the order amount. Each part is a positive integer, is not below the Minimum amount per part, and is within the provider's minAmount/maxAmount range.
• Count: a split payment with a non-card method has between 2 and Maximum parts parts. For the number of cards see Enabling.
• Card part: Multiple Cards › Card part.
• Non-card part, method and provider: Multiple Payment Methods › Method and provider choice.
• Non-reversible part: Multiple Payment Methods › Non-reversible part.

The installment rules for a card part are in Multiple Cards › Installments on a card part.

Time limit

A split payment with a non-card method must complete within the Total time (default 20 minutes).

• The end time is in the expiresAt field of the responses. The Checkout Form shows the remaining time to the buyer.
• When the time runs out, the holds on the cards are released, the reversible parts already charged are refunded and the split payment is cancelled.
• Once the non-reversible part starts, the clock stops and expiresAt becomes null. The card holds are kept until that part's result is final.
• The steps' own time limits (e.g. how long a verification code is valid) also apply.
• A split payment made of cards only has no total time; a card part whose 3D Secure is not completed ends with its own time limit.

With the Checkout Form

The states the buyer may see during the payment are in Multiple Payment Methods › States the buyer may see.

Order lock

When a split payment starts, the order is locked:

• While the split payment is in progress, no single-card, non-card or wallet payment can be started for the same order: the request gets 409 payment.checkout.order_locked.
• The reverse also holds: while a single-method payment is in progress for the order, or once the order is closed, no split payment can be started: 409 split_pay.checkout.order_not_open.
• If the split payment fails, its time runs out or the buyer gives up, the lock is released and the order stays open. The buyer can pay the same order with another method.
• Only one split payment runs for an order at a time. If the page is reloaded or the request is sent twice, the existing split payment continues; no new charge is made.

When a credit or BNPL provider is connected, the credit approval rules are in Multiple Payment Methods › Credit part.

How a card part's 3D Secure verification opens in the form is described in Multiple Cards › 3D Secure display.

The page where the payment continues after 3D Secure on a separate page is described in Multiple Cards › Continuation page.

The fields sent from the continuation page to your callbackUrl are in Multiple Cards › The result sent to your callbackUrl.

Endpoint reference

This section is for reference; the Checkout Form SDK calls the endpoints. As with the other form endpoints, authentication is the form token (token) and, when needed, checkoutSessionProof.

• The responses carry the status, steps, pendingStep and expiresAt fields of the API response; splitPaymentId is not given to the browser.
• The responses also carry the 3D Secure display the payment started with in threeDsDisplay (INLINE or REDIRECT).
• The form/split/init and form/split/status responses carry the main payment's paymentId at the top level. This is the id returned to you when you create the intent and sent to your callbackUrl. The parts' ids are in steps[].paymentId and pendingStep.paymentId.
• The continuation page calls its own endpoints (/payments/split/resume/*); you do not need to call them.
• The verification code of a non-card part is confirmed and resent with the action endpoints on Payment, using pendingStep.paymentId.

With the API

With POST /api/v1/payments/split you start a split payment from your own server. The endpoint requires Step-Up authentication (Bearer token and Ed25519 signature headers; see Authentication) and the payment:split-pay permission. The Idempotency-Key header is mandatory.

Request

Example requests: with cards only in Multiple Cards › With the API, with non-card methods in Multiple Payment Methods › With the API.

The fields of a card part are in Multiple Cards › Card part fields.

The fields of a non-card part and its method block are in Multiple Payment Methods › Non-card part fields.

Response

{
  "success": false,
  "code": "AWAITING_ACTION",
  "message": "…",
  "data": {
    "splitPaymentId": "b1e4…",
    "status": "AWAITING_ACTION",
    "duplicate": false,
    "needsReconciliation": false,
    "steps": [
      { "legId": "leg-1", "sequence": 1, "kind": "CARD", "paymentMethod": "CARD", "providerCode": null, "splitBehavior": "HOLD_CAPTURE", "amount": 40000, "status": "AUTHORIZED", "paymentId": null, "replacesLegId": null, "current": false },
      { "legId": "leg-2", "sequence": 2, "kind": "CARD", "paymentMethod": "CARD", "providerCode": null, "splitBehavior": "HOLD_CAPTURE", "amount": 35000, "status": "AUTHORIZED", "paymentId": null, "replacesLegId": null, "current": false },
      { "legId": "leg-3", "sequence": 3, "kind": "METHOD", "paymentMethod": "MOBILE_BILLING", "providerCode": "<providerCode>", "splitBehavior": "CAPTURE_IRREVERSIBLE", "amount": 25000, "status": "AWAITING_ACTION", "paymentId": "7d3a…", "replacesLegId": null, "current": true }
    ],
    "pendingStep": {
      "legId": "leg-3",
      "sequence": 3,
      "step": "ACTION",
      "paymentMethod": "MOBILE_BILLING",
      "providerCode": "<providerCode>",
      "amount": 25000,
      "paymentId": "7d3a…",
      "actionId": "act_5c2e…",
      "redirectPath": null,
      "action": {
        "id": "act_5c2e…",
        "type": "OTP",
        "expiresAt": "2026-10-20T09:03:00.000Z",
        "otp": { "maskedTarget": "53****67" },
        "consent": { "required": true, "url": "https://…" }
      }
    },
    "expiresAt": null,
    "pendingLeg": { /* compatibility field */ },
    "legs": [ /* per-leg states */ ]
  }
}

A steps[] item:

Besides the same legId, sequence, paymentMethod, providerCode, amount and paymentId fields, pendingStep carries step, actionId, redirectPath and action. action is set only for an action started in this request that is still awaited; its shape is the same as in Payment — Actions. Read the action's current state with GET /payments/{paymentId}.

Steps

• When an action completes, the platform advances the split payment by itself. If the next step is again a non-card part (START_METHOD), send the same request with the same Idempotency-Key. When all non-card parts are done, the cards are captured and the result arrives by webhook.
• You can also send the same request with the same Idempotency-Key to get the current step list; the response carries duplicate: true and no money movement is repeated.
• What to do when a non-card part cannot be started: Multiple Payment Methods › Completing a non-card part.
• If the provider declines the payment or the action fails, the part fails and the split payment compensates (see Failure and compensation).
• The Merchant API has no new-card step for a missing amount: if a card capture fails after the non-reversible part, the split payment moves to reconciliation required (see Failure and compensation).
• When the buyer does not complete 3D Secure, and when 3D Secure holds are not enabled on your setup: Multiple Cards › 3D Secure step.

The compensation rules that apply when a part fails or the time runs out are in Multiple Payment Methods › Failure and compensation.

Statuses

Statuses of the split payment:

Statuses of a part (legStatus, steps[].status): PENDING, AUTHORIZING, AWAITING_3DS, AWAITING_ACTION, AUTHORIZED, CAPTURED, VOIDED, REFUNDED, COMPENSATING, FAILED.

A split payment that stays COMPENSATING with needsReconciliation: true is under operations follow-up; money risk is never silently abandoned.

Events

Result of the main payment

The result of a split payment always arrives as a single event: payment.captured or payment.failed, as in a single-method payment. Ship the order on payment.captured.

In the Checkout Form, if the split payment is cancelled (VOIDED), the order stays open and no payment.failed is sent; the buyer can pay the same order with another method. In that case payment.split.voided arrives.

Split payment events

Each of these events is sent at most once per split payment. They are not part events: if your endpoint subscribes to the event type, they arrive regardless of the option below.

Part events

The events of each part's own payment record (payment.authorized, payment.captured, payment.failed, payment.voided, payment.refunded …) and payment.split.leg_refund_pending (compensation refund pending) are not sent by default.

• To receive them, add the payment.split.leg_events option to your webhook endpoint's event list. In the panel it is the option that also sends part events for split payments.
• The option is not an event type; you must also subscribe to the part event's type (e.g. payment.captured). A payment.* subscription does not turn this option on.
• A part event's orderId has the form <order>:leg:<sequence>, and the data.splitLeg field carries splitPaymentId, parentPaymentId (the order's payment record in the Checkout Form, null in the API), parentOrderId, legId and legSequence.
• Ship on the main payment's payment.captured, not on part events.

A chargeback (payment.disputed) is always sent regardless of this option and carries the main payment information in data.splitLeg.

Delivery, signatures and subscriptions: Webhooks.

Refunds

You request a refund on the main payment of a split payment; the platform distributes the amount across the parts. Only a completed (COMPLETED) split payment can be refunded.

Distribution rule

• Card parts are refunded first, in order and partially if needed.
• The remaining amount is covered from the reversible non-card parts. A non-card part is refunded only for its full remaining amount.
• A non-reversible part (e.g. mobile billing, promissory notes) is never part of the distribution.
• A part's refund ceiling is the amount captured from it; for a card part with installments the installment fee is included. A full refund also refunds the installment fee.
• The refundable amount and the non-refundable amount are in the refund.refundableAmount and refund.nonRefundableAmount fields of the GET /payments/split/:id response.

If the amount exceeds the refundable total, the request gets 400 split_pay.refund.amount_exceeded; the refundable amount is in details.refundableAmount. If the amount is within the total but cannot be split across the parts (e.g. only non-card parts remain and the amount would split one of them), 422 split_pay.refund.amount_not_distributable is returned.

For a Checkout Form payment

Request the refund on the order's payment record with the existing refund endpoint: POST /payments/:id/refund → Refunds.

• amount is required.
• The per-part result is in the response's meta.details.splitRefund field.
• If some parts could not be refunded, the response fails with the code split_pay.refund.incomplete. If a part's result is not yet known, the response is 202. In both cases retry with the same Idempotency-Key; a part already refunded is not refunded again.

For a split payment started from the API

POST https://api-gateway.lunixi.com/api/v1/payments/split/{splitPaymentId}/refund

The body is { "amount": 15000, "reason": "…" }; reason is optional. The endpoint requires the payment:refund permission and a mandatory Idempotency-Key.

• The response's data carries refundRequestId, splitPaymentId, orderId, currency, status (COMPLETED, PARTIAL, FAILED, PROCESSING), requestedAmount, refundedAmount, refundableAmount, nonRefundableAmount, duplicate and per-part legs[] (legId, sequence, paymentIntentId, paymentMethod, providerCode, amount, status, errorCode).
• When every part was refunded the response has success: true. If some parts could not be refunded, the response carries success: false and code: "split_pay.refund.incomplete"; retry with the same Idempotency-Key.
• A request with the same key but a different amount or reason is rejected.

After the refund

• A single event arrives for the main payment: payment.refunded when no refundable amount is left on the main payment, otherwise payment.partially_refunded. The event carries settlementMode: "SPLIT", refundId, refundAmountMinor, totalRefundedMinor, fullyRefunded and refundedLegs[].
• The main payment's status does not change after the refund. The refunded total is shown by totalRefundedMinor in the event and refund.refundedAmount in the GET /payments/split/:id response.
• You can also refund a single part: POST /payments/:id/refund on the part's payment record. While the split payment is in progress, or while the part's compensation refund is pending, this request gets 409 split_pay.refund.not_allowed.

Listing and detail

Payment list

• In the GET /payments list a Checkout Form split payment is a single row: the order's payment record, with the order amount. The parts are not in the list.
• With includeLegs=true the parts' payment records are listed too.
• Rows related to a split payment carry a split field: splitPaymentId, role (PARENT main payment, LEG part), and on a part parentPaymentId and legSequence.
• The main payment of a split payment started from the API is not a payment record; its parts appear in the list with role: "LEG". Read the main payment with GET /payments/split.

Split payment detail

GET /api/v1/payments/split (list, keyset pagination) and GET /api/v1/payments/split/:id (detail) require a Bearer token and the payment:view permission.

Per part in the detail:

At the top level there are refund (refundableAmount, nonRefundableAmount, refundedAmount) and dispute (hasDispute, disputedAmount, legCount).

Chargebacks

A chargeback is recorded on the part's payment record. The main payment's status does not change; the detail shows the dispute flag and amount. No automatic action is taken on the other parts. The payment.disputed event arrives with data.splitLeg → Chargebacks.

Errors

Every code is described on Error Handling.

Related pages

• Multiple Cards — splitting with cards only
• Multiple Payment Methods — splitting with cards and non-card methods
• Checkout Form — Payment — single-method non-card payments and provider choice
• Listing Methods — splitEligible, splitBehavior and order
• Pre-authorization, Capture & Void — the single-payment version of the hold and capture model
• Installments & BIN — installment quotes
• Webhooks — delivery and signatures