Multiple Payment Methods

Paying with multiple payment methods splits one order across one or more cards and non-card methods: wallets, mobile billing (Faturana Yansıt) and promissory notes (Senetle Öde). For example, a ₺1,000 order = Card A ₺300 + Card B ₺250 + Wallet ₺200 + mobile billing ₺250. When a credit provider is connected to your account, credit can also be a part.

This page covers what is specific to non-card methods. What both ways of splitting share is on the Split Payments page:

• Switch and shared settings (maximum parts, minimum amount per part, total time): Enabling. Both the Checkout Form and the API need the Split Payment with Non-Card Methods switch.
• Amount, currency and part count rules: Rules.
• Total time and when the clock stops: Time limit.
• Statuses, events, refunds, listing and errors: Statuses, Events, Refunds, Listing and detail, Errors.

The rules for card parts (installments, 3D Secure display, continuation page) are on Multiple Cards and apply to the card parts here too.

Order of the steps

The platform sets the order; neither you nor the buyer can change it. Parts are arranged into four phases according to the method's split payment behaviour (splitBehavior). The last column shows what happens in each phase for a ₺1,000 order split as Card A ₺300 + Card B ₺250 + Wallet ₺200 + mobile billing ₺250:

• Within a phase the provider's priority decides the order; on a tie the larger part goes first.
• A method's behaviour comes from the provider's declaration; it is shown in splitBehavior on the GET /payments/methods row.
• What happens when every part has succeeded: Order of the steps.

Example splits

Card parts

Several cards can be used in one order together with non-card methods.

• The number of cards follows the limit of the Pay with Multiple Cards switch. When the switch is off, at most 1 card can be used → Enabling.
• Each card part goes through its own 3D Secure verification. The Checkout Form opens the cards' verifications one after another → 3D Secure display. In the API, force3D is set on each card part separately and each one gets its own THREE_DS step → 3D Secure step.
• Each card part can choose its own installments; the quote is taken with the part's amount → Installments on a card part. In a payment with insurance and in a payment with a credit approval, card parts are charged in a single payment.
• Card parts are always taken as holds before the non-card charges; money is taken from the cards when every part has succeeded.

Non-reversible part

A non-reversible part is a method that cannot be refunded once charged (CAPTURE_IRREVERSIBLE), e.g. mobile billing and promissory notes.

• An order has at most one. A second non-reversible part gets 422 split_pay.validation.multiple_irreversible_legs.
• It is always charged last; the card holds and the reversible parts complete before it.
• Once it starts, the total time stops → Time limit.
• The rule that applies when its result is uncertain, or when a card capture fails after it was charged: Failure and compensation.
• It is never part of a refund distribution → Distribution rule.

Method and provider choice

Each non-card part comes with a method and a provider.

• The method must be one you enabled for split payments in Form Settings.
• The provider must be connected to your account and eligible for split payments: splitEligible: true on the GET /payments/methods row.
• A provider can be used in only one part of an order.
• On the Checkout Form path a provider turned off for the form cannot be used; on the API path it can.
• In the Checkout Form the buyer chooses the provider; the picker is the same as in a single-method payment in the form → Provider choice.
• In the API, offer the buyer only providers with splitEligible: true, and always send the chosen provider's code as providerCode in the method block.
• A non-card part carries no installments. A promissory-note part has no due-date schedule; you give the number of notes with noteCount and the notes are issued over the part's amount.

Credit part

This section applies when a credit or BNPL provider is connected to your account.

• Credit is always the first step. No part starts and no amount is held before the credit is approved.
• In a split payment with a credit approval, card parts cannot have installments; they are charged in a single payment.
• If the approval arrives within a few minutes, the buyer continues in the same session.
• If the approval is delayed, the split payment moves to waiting for credit approval (AWAITING_CREDIT_APPROVAL) and waits up to 1 hour. The buyer can leave the page.
• If the approval arrives after the buyer left, a continuation link is sent to the buyer by email. Send buyer.email on the intent for this. No link is sent in the test environment.
• The buyer pays the remaining parts within the provider's approval validity period. Card parts are started while the buyer is in the form.
• If the period runs out, the approval is cancelled. No money was charged, so no refund is needed.

Insurance

If the buyer selected insurance in the Checkout Form:

• The insurance premium is added to the order total and collected from a card part, so the payment must include at least one card part. Without a card part the request gets 422 split_pay.insurance.requires_card_leg.
• Card parts are charged in a single payment. With a card part in installments the request gets 422 payment.insurance.installment_not_supported.
• In an insured split payment made of cards only, card parts are also charged in a single payment.

With the Checkout Form

The buyer selects the Pay with more than one method entry in the method list. They add their cards and the non-card methods you enabled as parts, choose the provider for a non-card part and distribute the amount across the parts. When the payment starts, the form runs the steps in the platform's order: when a non-card part's turn comes, it starts that part and takes the verification code or the requested data from the buyer.

Enabling the form and the steps of the flow: Split Payments › With the Checkout Form.

The requests the form sends

These requests are for reference; the Checkout Form SDK sends them and you do not need to call them.

When the split payment starts, the form sends the parts. The example is the 2 cards + wallet + mobile billing split. Each card part carries its own installments (in a payment without insurance); a non-card part carries only the method, the provider and the amount:

POST https://api-gateway.lunixi.com/api/v1/payments/form/split/init

{
  "token": "<form-token>",
  "legs": [
    { "cardToken": "<card-a-token>", "amount": 30000 },
    { "cardToken": "<card-b-token>", "amount": 25000, "installment": 3, "installmentQuoteToken": "<installment-quote>" },
    { "paymentMethod": "WALLET", "providerCode": "<wallet-providerCode>", "amount": 20000 },
    { "paymentMethod": "MOBILE_BILLING", "providerCode": "<mobile-billing-providerCode>", "amount": 25000 }
  ]
}

The form opens the 3D Secure verifications of Card A and Card B one after another, then starts the wallet and mobile billing parts when their turn comes.

When the non-card part's turn comes (pendingStep.step is START_METHOD), the form starts that part with the data the buyer entered. The body is the form/payment body plus legId:

POST https://api-gateway.lunixi.com/api/v1/payments/form/split/method

{
  "token": "<form-token>",
  "legId": "<pendingStep.legId>",
  "paymentMethod": "MOBILE_BILLING",
  "mobileBilling": { "providerCode": "<providerCode>", "gsmNumber": "<buyer-phone-number>" },
  "browserFingerprint": "…",
  "paymentChannel": "WEB"
}

The other form endpoints: Endpoint reference.

States the buyer may see

With the API

Send the cards and the non-card method blocks together in the POST /api/v1/payments/split request. Authentication, Idempotency-Key, the top-level fields, the response and the step list: Split Payments › With the API.

Request

The example is the 2 cards + mobile billing split. Card A is charged in 3 installments, Card B is taken as a 3D Secure hold; each card part's 3D Secure (force3D) and installments (installment, installmentQuoteToken) are set separately. Mobile billing is the non-reversible part, so it is charged last.

curl https://api-gateway.lunixi.com/api/v1/payments/split \
  -H "Authorization: Bearer <access-token>" \
  -H "X-Key-Id: <kid>" \
  -H "X-Date: <iso-8601>" \
  -H "X-Nonce: <single-use-value>" \
  -H "Digest: SHA-256=<base64>" \
  -H "X-Signature: <ed25519-signature>" \
  -H "Idempotency-Key: split-order-2026-001" \
  -H "Content-Type: application/json" \
  -d '{
    "totalAmount": 100000,
    "currency": "TRY",
    "ownerRef": "cuk_abc123",
    "orderId": "order-2026-001",
    "callbackUrl": "https://shop.example/payment-return",
    "legs": [
      { "cardToken": "ct_cardA", "amount": 40000, "installment": 3, "installmentQuoteToken": "iq_…" },
      { "cardToken": "ct_cardB", "amount": 35000, "force3D": true },
      {
        "paymentMethod": "MOBILE_BILLING",
        "amount": 25000,
        "mobileBilling": { "providerCode": "<providerCode>", "gsmNumber": "<buyer-phone-number>" }
      }
    ]
  }'

While Card B awaits 3D Secure, pendingStep.step in the response is THREE_DS (see 3D Secure step). Once the card holds are taken, the mobile billing part awaits a verification code (pendingStep.step is ACTION); the response at that point is the Split Payments › Response example.

For the 2 cards + wallet + mobile billing split, legs[] looks like this. The wallet is a reversible part, so it is charged before mobile billing; both non-card parts ask for a verification code when their turn comes:

"legs": [
  { "cardToken": "ct_cardA", "amount": 30000, "force3D": true },
  { "cardToken": "ct_cardB", "amount": 25000, "installment": 3, "installmentQuoteToken": "iq_…" },
  { "paymentMethod": "WALLET", "amount": 20000, "wallet": { "providerCode": "<providerCode>", "gsmNumber": "<buyer-phone-number>" } },
  { "paymentMethod": "MOBILE_BILLING", "amount": 25000, "mobileBilling": { "providerCode": "<providerCode>", "gsmNumber": "<buyer-phone-number>" } }
]

Non-card part fields

• A non-card part cannot carry cardToken, force3D, installment or installmentQuoteToken.
• The promissory-note block cannot carry schedule; give the number of notes with noteCount.
• Methods without a block cannot be used in a split payment.
• The block's fields are not stored; they are passed only to the provider when the part's turn comes. That is why you may need to send the same request again before the part's turn (see Completing a non-card part).

The fields of a card part: Multiple Cards › Card part fields.

Completing a non-card part

pendingStep in the response tells you what is expected from you for a non-card part. The full list of steps: Steps.

1. ACTION: send the code the buyer entered, with pendingStep.paymentId and pendingStep.actionId:

   curl https://api-gateway.lunixi.com/api/v1/payments/<paymentId>/actions/<actionId>/confirm \
     -H "Authorization: Bearer <access-token>" \
     -H "X-Key-Id: <kid>" \
     -H "X-Date: <iso-8601>" \
     -H "X-Nonce: <single-use-value>" \
     -H "Digest: SHA-256=<base64>" \
     -H "X-Signature: <ed25519-signature>" \
     -H "Content-Type: application/json" \
     -d '{ "otp": "<code-entered-by-the-buyer>", "consentAccepted": true }'

   consentAccepted is needed only when action.consent.required is true. Sending the code again and the error responses: Payment — Confirm.

2. Then send the same POST /payments/split request again with the same Idempotency-Key. The response carries the current steps and pendingStep.

3. START_METHOD: the next non-card part is waiting to start; send the same request with the same key. The part starts with the block in this request.

4. RESULT_PENDING: the provider's result is awaited; show the buyer "your payment is being checked". Once the result is final the split payment continues by itself.

If a non-card part cannot be started (e.g. a field in the block does not match the provider's definition), the error is returned to you, no money moves and the split payment waits; the clock keeps running. Fix the field in the method block and send the same request with the same Idempotency-Key again. A part can be tried at most 3 times; once the limit is reached the part fails.

Failure and compensation

If a part fails or the time runs out, the split payment compensates:

• The holds on the cards and the credit approval are released at once.
• The reversible parts already charged are refunded. The refund is retried at growing intervals until it succeeds; it is never given up. While the refund is in progress the part's refundState is REFUND_PENDING, and REFUNDED when done.
• When every refund is done, the split payment becomes VOIDED.

The non-reversible part:

• If its result is uncertain, the clock stops and the card holds are kept until the result is final. You receive payment.split.outcome_pending. If the result is success, the cards are captured; if it is a failure, the cards are released and the other parts are refunded.
• If a card capture fails after it was charged, the capture is retried once. If it still fails:
  • In the Checkout Form the buyer is asked for a new card for the missing amount (AWAITING_REPLACEMENT_CARD, 10 minutes). The new card is taken with a hold and a capture, in a single payment.
  • If the new card also fails, the buyer leaves, the 10 minutes run out, or the payment was started from the API, the split payment moves to reconciliation required (RECONCILIATION_REQUIRED). You receive payment.split.reconciliation_required; the event states the missing amount and the part that could not be collected. You decide about shipping. In this state the order stays locked.

Related pages

• Split Payments — shared rules, statuses, events, refunds and errors
• Multiple Cards — card part, installments and 3D Secure
• Listing Methods — splitEligible, splitBehavior and order
• Payment — method blocks, actions, confirm and resend
• Checkout Form — Payment — single-method non-card payments and provider choice