Payment Orchestrator
Shopping Loan

Shopping Loan — Payment

With paymentMethod: "SHOPPING_LOAN" the buyer pays the purchase amount with a shopping loan from their bank. The buyer chooses their bank on your screen, is redirected to the bank's page and applies for and approves the loan there. The bank pays the loan amount into your provider account; the buyer repays the bank in installments.

The payment runs through a REDIRECT action: you do not ask the buyer for a code and you do not call confirm. The final result is verified with the provider and reported with the payment.captured or payment.failed webhook. The bank's new-customer process can take several days; during that time the payment stays pending → Applications pending at the bank.

All amounts are canonical minor-unit strings: "amount": "4500000" = ₺45,000.00. The request, response and error rules shared by all methods are on Payment.

How it works

Send the basket

Basket items (basketItems) are required for a shopping loan. Add the product category (productCategory) to every item; the bank sets the number of installments according to the products in the basket. See Basket and product category.

Let the buyer choose the bank

Show the buyer the banks in the method row's banks list; the buyer chooses the bank they will take the loan from. See Bank selection.

Start the payment and redirect the buyer

Start the payment with the Checkout Form or from your server with the Direct API. The response (202) carries a REDIRECT action; send the buyer's browser to action.redirect.url. In the Checkout Form the form does this step.

The buyer approves the loan at their bank

On the bank's page the buyer applies for the loan, chooses the term and approves the contract. If the buyer is not a customer of the bank, the bank may require extra verification (video call, courier); the payment is then put on hold.

Receive the result

When the loan is disbursed the payment becomes CAPTURED and payment.captured is sent. Ship the order on this event only.

Prerequisites

  • Connect your shopping loan provider in the panel under POS Center → Discover; the connection details and settings are on Shopping Loan Providers.
  • Enable the Shopping Loan method in the panel under Payment → Form Settings and select the provider. A method disabled in the panel is disabled on every channel; a Direct API request gets 422 payment.method.disabled.
  • Set which banks are open in your contract in the Agreement Permissions section of your provider connection; see Bank permissions.
  • The currency is TRY. The bank sets the installments in the loan: do not send installment in the request. There is no pre-authorization; with preauth: true the request gets 422 payment.preauth.unsupported_for_method before the payment starts.
  • Shopping Loan cannot be used as a leg of a split payment.

Basket and product category

The bank grants the loan according to the products in the basket. That is why a basket is required for a shopping loan and the items' product category affects the term.

  • The basket is required. If basketItems is missing or empty, the payment is rejected before the buyer is redirected to the bank.
  • A basket may contain at most 100 items. A payment with more items is rejected before the buyer is redirected to the bank.
  • The price values of the items must add up to amount (the rule for all methods). For a shopping loan every item's price must be greater than zero.
  • Send productCategory on every item. An item without it is treated as OTHER and falls into the other-products class. You are responsible for sending the correct category.
  • If the basket contains a gold (GOLD) item, banks do not grant a loan: the payment is rejected before the buyer is redirected to the bank. Offer the buyer another method for orders that include gold.

Banks apply the legal installment limits by product class and, when the basket contains more than one class, use the most restrictive one:

The item's productCategoryClass in the loan
GOLDGold: no loan is granted
MOBILE_PHONEMobile phone. An item priced above TRY 40,000.00 and an item priced at TRY 40,000.00 or below are separate classes
TABLETTablet
COMPUTERComputer
All other codes and items without a categoryOther products
  • Items have no quantity field; price is the line total. Because the mobile-phone class depends on the line's price, send each phone as a separate item.
  • The bank sets the maximum number of installments it offers the buyer; the classes and limits may change with regulation.

Example basket:

"basketItems": [
  {
    "id": "phone-1",
    "name": "Smartphone",
    "price": "4200000",
    "category1": "electronics",
    "itemType": "PHYSICAL",
    "productCategory": "MOBILE_PHONE"
  },
  {
    "id": "case-1",
    "name": "Phone case",
    "price": "300000",
    "category1": "accessories",
    "itemType": "PHYSICAL",
    "productCategory": "ELECTRONICS_ACCESSORY"
  }
]

Method row

The SHOPPING_LOAN row of the GET /payments/methods response carries the banks you can show the buyer in the banks field. The same banks are also the bankCode options in the provider's inputFields definition. The output below is abridged:

{
  "paymentMethod": "SHOPPING_LOAN",
  "category": "CREDIT",
  "blockName": "shoppingLoan",
  "displayName": null,
  "providerSelection": "OPTIONAL",
  "providerSelectionMode": "BUYER",
  "actionTypes": ["REDIRECT"],
  "currencies": ["TRY"],
  "preauth": false,
  "providers": [
    {
      "providerCode": "COMPAY",
      "displayName": "Compay",
      "logoUrl": null,
      "actionTypes": ["REDIRECT"],
      "currencies": ["TRY"],
      "preauth": false,
      "inputFields": [
        {
          "key": "bankCode",
          "type": "SELECT",
          "required": true,
          "label": { "tr": "Banka", "en": "Bank" },
          "pii": false,
          "options": [
            { "value": "0015", "label": { "tr": "T. VAKIFLAR BANKASI T.A.O.", "en": "T. VAKIFLAR BANKASI T.A.O." } },
            { "value": "0046", "label": { "tr": "AKBANK T.A.Ş.", "en": "AKBANK T.A.Ş." } },
            { "value": "0062", "label": { "tr": "T. GARANTİ BANKASI A.Ş.", "en": "T. GARANTİ BANKASI A.Ş." } }
          ]
        }
      ],
      "splitEligible": false,
      "splitBehavior": null
    }
  ],
  "banks": [
    { "bankCode": "0046", "bankName": "AKBANK T.A.Ş.", "providerCode": "COMPAY" },
    { "bankCode": "0062", "bankName": "T. GARANTİ BANKASI A.Ş.", "providerCode": "COMPAY" },
    { "bankCode": "0015", "bankName": "T. VAKIFLAR BANKASI T.A.O.", "providerCode": "COMPAY" }
  ],
  "splitEligible": false,
  "splitBehavior": null
}

Always read the provider code and the banks from this response; do not hard-code them in your application. All properties of the field definition: Listing Methods › Method fields.

Bank selection

bankCode is the 4-digit BKM bank code from Lunixi's bank dictionary (e.g. 0062). Show the buyer the bankName of the banks in the banks list and send the chosen bank's bankCode in shoppingLoan.bankCode.

banks[] fieldTypeDescription
bankCodestring4-digit BKM bank code; sent in the request as shoppingLoan.bankCode
bankNamestringBank name you can show the buyer
providerCodestringThe provider the platform would pick for this bank when you do not send providerCode. For information only; you may also choose another connected provider that offers the bank with shoppingLoan.providerCode
  • banks lists the banks open in the Agreement Permissions of your connections, sorted by bank name. A bank open with more than one provider appears once. It differs from the open banking bank list.
  • The bankCode options in the provider's inputFields definition likewise contain only the banks open for that provider. A provider with no open bank is not listed for this method.
  • A code the provider does not support at all gets 400 payment.method.block_invalid at request validation (details.field shoppingLoan.bankCode, details.reason invalid_option).
  • A bank the provider supports but that is not open in any of your connections gets 422 payment.method.bank_not_enabled; the payment does not start and no money moves.
  • The bank is asked only through this selection; the buyer does not choose a bank again on the provider's page.

Banks the provider supports today:

  • Akbank0046
  • Albaraka Türk0203
  • DenizBank0134
  • Fibabanka0103
  • Garanti BBVA0062
  • ING Bank0099
  • Kuveyt Türk0205
  • Türkiye Finans0206
  • Türkiye İş Bankası0064
  • Vakıf Katılım0210
  • VakıfBank0015

Bank permissions

You set which banks are open in your contract with the provider in the panel, in the Agreement Permissions section of your provider connection.

  • Shopping Loan banks have their own list; you turn each bank on or off. On a new connection all banks are on, and at least one bank must stay on.
  • This setting applies on every channel: GET /payments/methods, the Checkout Form and the Direct API accept only open banks.
  • If you have more than one connection for the method, each connection has its own list. A bank can be used when it is open in at least one of your connections.

For the Checkout Form you additionally set the order and visibility of the banks, and which provider each bank goes through, in Form Settings; that setting affects only the form → With the Checkout Form.

Choosing the provider

With Shopping Loan the buyer chooses their bank; they do not need to choose a provider. shoppingLoan.providerCode is optional:

  • If you send providerCode, that provider is used. The chosen bank must be open in at least one of that provider's connections; otherwise you get 422 payment.method.bank_not_enabled.
  • If you do not send providerCode, the platform picks the provider among your connected providers that support the chosen bank and have it open in their Agreement Permissions. With a single candidate that provider is used; with several, the platform's selection order applies. In this case 400 payment.provider.required is not returned.
  • If there is no eligible candidate you get 422 payment.method.bank_not_enabled.
  • The chosen provider is pinned to the payment: on an error the payment does not move to another provider, another method or card. The provider that runs the payment is in the providerCode field of the response and the webhook.

Today the provider of this method is Compay (COMPAY).

With the Checkout Form

In the form, the Checkout Form SDK makes the shopping loan calls. The code you write is the same as for card payments: create the intent on your server and mount the form on your page → Checkout Form. The basket items and productCategory are read from the intent; an intent without a basket cannot start a shopping loan payment. The method's form-settings group is shopping_credit; use this name when you narrow the methods with settings.paymentMethods on the intent.

What the buyer sees

Chooses the method

The buyer chooses Shopping Loan among the payment methods.

Chooses their bank

The form lists the banks enabled in your form settings; the buyer chooses the bank they will take the loan from and starts the payment. Your form settings decide which provider each bank goes through.

Approves the loan at their bank

The buyer is redirected to their bank's page, applies for the loan, chooses the term and approves the contract.

Sees the result

When the buyer comes back the result is verified with the provider. If the loan was disbursed the buyer sees the success result. If the application is still in progress at the bank, the buyer is told that the payment is being processed. If you gave a callbackUrl on the intent, the buyer arrives at your page with the signed result form; otherwise they see Lunixi's result page.

Banks in the form

You manage the banks in the panel under Payment → Form Settings, in the Payment options list of Shopping Loan → Checkout Form — Payment › Bank rows.

  • You drag the banks into their order in the form and turn each bank on or off for the form with the Show in the form switch.
  • When a bank is open with more than one connected provider, you choose which provider it goes through.
  • Without a setting, all banks open in your Agreement Permissions are sorted by bank name and go through the first provider in the method's provider order.
  • This setting affects only the Checkout Form. GET /payments/methods and Direct API payments are not affected by it; there only the Agreement Permissions apply.

With the Direct API

POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment
Content-Type: application/json

The request carries Step-Up authentication (Bearer token and Ed25519 signature headers; see Authentication) and a required Idempotency-Key header (at most 200 characters); the rules are the same as in Payment — Idempotency.

Method fields

FieldTypeRequiredDescription
paymentMethodstringYesSHOPPING_LOAN
shoppingLoanobjectYesShopping loan block; its fields are in the rows below
shoppingLoan.bankCodestringYes4-digit code of the bank the buyer chose; one of the banks in the method row's banks list. See Bank selection
shoppingLoan.providerCodestringNoThe provider the bank goes through. Without it the platform picks; see Choosing the provider
basketItemsarrayYesBasket items; productCategory is recommended on every item. See Basket and product category
callbackUrlstringNohttp or https, at most 2048 characters. On return the buyer's browser arrives at this address with the signed result form. Without it the buyer sees Lunixi's result page
  • The body carries only the shoppingLoan block: another method's block or card, force3D, installment, installmentQuoteToken make the request fail with 400 VALIDATION_ERROR.
  • The other order fields (orderId, amount, currency, buyer …) are the same for all methods → Payment — Order fields.
  • When your connection requires the identity number, send buyer.identityNumber; see Turkish identity number.

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-11-12T09:00:00.000Z" \
  -H "X-Nonce: 9a1c3e5b-7d2f-4b6a-8e0c-3f5a7c9e1b4d" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORDER-1006-1" \
  -d '{
    "paymentMethod": "SHOPPING_LOAN",
    "orderId": "ORDER-1006",
    "amount": "4500000",
    "currency": "TRY",
    "callbackUrl": "https://merchant.example.com/payments/result",
    "basketItems": [
      { "id": "phone-1", "name": "Smartphone", "category1": "electronics", "itemType": "PHYSICAL", "price": "4200000", "productCategory": "MOBILE_PHONE" },
      { "id": "case-1", "name": "Phone case", "category1": "accessories", "itemType": "PHYSICAL", "price": "300000", "productCategory": "ELECTRONICS_ACCESSORY" }
    ],
    "shoppingLoan": { "bankCode": "0062" },
    "buyer": { "name": "Ada", "surname": "Yılmaz", "identityNumber": "11111111111", "email": "[email protected]", "gsmNumber": "+905000000000", "city": "Istanbul", "country": "Turkey", "zipCode": "34732", "ip": "203.0.113.10" },
    "billingAddress": { "contactName": "Ada Yılmaz", "address": "Altunizade Mah. Örnek Sok. No: 1", "city": "Istanbul", "country": "Turkey", "zipCode": "34662" },
    "shippingAddress": { "contactName": "Ada Yılmaz", "address": "Altunizade Mah. Örnek Sok. No: 1", "city": "Istanbul", "country": "Turkey", "zipCode": "34662" }
  }'

Response

{
  "status": "partial",
  "code": "CUSTOMER_ACTION_REQUIRED",
  "message": "…",
  "data": {
    "paymentId": "8d4f6b2a-0c1e-4f3a-9b5d-7e9a1c3b5d6f",
    "orderId": "ORDER-1006",
    "status": "PROCESSING",
    "paymentMethod": "SHOPPING_LOAN",
    "providerCode": "COMPAY",
    "action": {
      "id": "act_7c9e1b3d5f7a9c0e2f4a6c8e0b1d3f5a",
      "type": "REDIRECT",
      "expiresAt": "2026-11-12T09:30:00.000Z",
      "redirect": { "url": "https://api-gateway.lunixi.com/api/v1/payments/launch/<redirect-token>" }
    }
  },
  "statusCode": 202,
  "requestId": "…"
}
FieldDescription
data.statusPROCESSING: the payment is waiting for the buyer's loan approval at the bank
action.typeREDIRECT
action.redirect.urlThe address the buyer goes to. See Redirect and return
action.expiresAtLatest time for the buyer to go to the bank and come back (ISO 8601); 30 minutes after the action opens. If the application is put on hold at the bank, this time does not close the payment

If the request fails validation or the payment is rejected before the buyer is redirected (no basket, gold in the basket …), the response returns with HTTP 400; see Errors.

Redirect and return

  • Redirect the buyer's browser to action.redirect.url without delay (a browser GET). The address is Lunixi's interstitial page; it sends the buyer on to the provider and the chosen bank.
  • The address is single-use and can be opened for 10 minutes. On a second opening or after it expires the buyer sees an error page; no new redirect address is issued for the same payment.
  • Do not open the address in an iframe; bank pages do not work inside an iframe.
  • The data the buyer brings back from the bank is not the result: the platform queries the result from the provider and closes the payment accordingly.
  • If you gave a callbackUrl, the buyer's browser arrives at that address with an HTML form POST carrying the result. The fields and signature are the same as for the card 3D Secure return → Card — 3D Secure › Signed callback. The status field is success, failure or pending. If the application was put on hold at the bank, status is pending and code is payment.action.provider_pending.
⚠️

The return form is informational; do not base delivery on it. The buyer's browser may never return to your page. Confirm the order with the payment.captured webhook or GET /payments/:id.

Applications pending at the bank

If the buyer is not a customer of the bank or the bank requires extra verification (video call, contract by courier), the loan is disbursed within a few days. During that time:

  • The payment stays PROCESSING. The buyer's money has not reached your account.
  • The payment.provider_pending webhook is sent once. The body carries deliverable: false, the time the hold started (pendingSince) and the latest time the result is expected (pendingUntil).
  • The platform queries the result from the provider at regular intervals (hourly on the first day, then every 6 hours) and processes the provider's notification as soon as it arrives. You do not need to query the payment.
  • When the loan is disbursed the payment becomes CAPTURED and payment.captured is sent; if the bank declines the application or the process is not completed, the payment becomes FAILED and payment.failed is sent.
  • The result is final at the latest 11 days after the hold started. If the result still cannot be verified at the end of this period, the payment becomes NEEDS_RECONCILIATION; the result is reported by webhook once it is verified.
⚠️

Do not ship the order while the payment is pending. payment.provider_pending is not a payment-received notice. Ship the order on payment.captured only. While the hold lasts, do not start a new payment for the same order and do not redirect the buyer again; the buyer could apply for a loan twice for the same order.

In the panel the payment details show when the hold started and the latest time the result is expected.

Result

SituationWhat happensWhat to do
The loan was disbursedThe payment is CAPTURED, payment.captured is sentShip the order
The application is in progress at the bankThe payment is PROCESSING, payment.provider_pending is sentDo not ship; wait for the result. See Applications pending at the bank
The buyer gave up, the bank declined, or the process was not completedThe payment is FAILED, payment.failed is sentNo money moved. Offer the buyer another method
The buyer did not go to the bank and come back within 30 minutesThe platform asks the provider for the result; if the application is in progress the payment is put on hold, otherwise it is settled to its real stateDo not start a new payment; wait for the webhook
  • While the payment is PROCESSING or NEEDS_RECONCILIATION, do not start a new payment for the same order.
  • If the payment is FAILED, start a new payment with a new Idempotency-Key to retry.
  • In the panel the payment details show the bank that granted the loan.

Turkish identity number

For some merchant categories (e.g. games of chance, balance top-up) the provider requires the buyer's Turkish identity number (T.C. kimlik numarası). In that case you turn on the identity number required setting on your provider connection.

  • When the setting is on, send the buyer's 11-digit identity number with a valid checksum in buyer.identityNumber on every payment. In the Checkout Form this field is read from the buyer data on the intent.
  • If the number is missing or invalid, the payment is rejected before the buyer is redirected to the bank; no money moves.
  • The number is passed only to the provider; it is not shown in responses, webhooks or the panel.

Refunds

A disbursed (CAPTURED) shopping loan payment supports full and partial refunds. Refunds use the POST /payments/:id/refund endpoint on Refunds: without an amount it is a full refund, with amount a partial refund.

  • Partial refunds are cumulative; the total refunded cannot exceed the loan amount.
  • The refund is passed through the provider to the bank that granted the loan.
  • A pending (PROCESSING) payment cannot be refunded; nothing has been charged yet.
  • If a refund result is not final, do not send a second refund with a new key; retry with the same Idempotency-Key.
  • The payment cannot be voided; pre-authorization is not supported.

Errors

Error responses use the common error envelope; branch on code, not on message → Error Handling.

SituationResponseWhat to do
No shoppingLoan block, bankCode missing or not in the list400 payment.method.block_invalidFix the details.field field; let the buyer choose the bank from the options
The basket total does not equal amount400 VALIDATION_ERRORMake the items' price values add up to amount
The method is disabled in the panel422 payment.method.disabledEnable the method under Payment → Form Settings
The chosen bank is not open in the Agreement Permissions of any of your connections, or is closed for the providerCode you sent422 payment.method.bank_not_enabledThe payment did not start. Let the buyer choose a bank from the banks list, or turn the bank on under Agreement Permissions in the panel
In the Checkout Form, the bank is turned off for the form or set to another provider in the form settings422 payment.provider.disabled_in_form (details.bankCode)The form offers the buyer the banks enabled in the form; see Banks in the form
The selected provider is not connected422 payment.provider.not_availableCheck the provider connection in the panel
preauth: true was sent422 payment.preauth.unsupported_for_methodSend without preauth
No basket or an empty basket, or an item priced at zero400, payment FAILEDThe buyer was not redirected and no money moved. Send the basket and start again with a new Idempotency-Key
The basket contains gold (GOLD)400, payment FAILEDBanks do not lend for gold. Offer the buyer another method
Your connection requires the identity number and buyer.identityNumber is missing or invalid400, payment FAILEDSend the number and start again with a new Idempotency-Key
The buyer gave up or the bank declinedPayment FAILED, payment.failedOffer the buyer another method

Other codes: Payment — Error codes.

Webhooks

EventWhen
payment.provider_pendingThe application was put on hold at the bank; no funds have moved yet. Do not ship the order. Sent once per payment
payment.capturedThe loan was disbursed; the money reached your account. Ship the order on this event
payment.failedThe payment failed; nothing was charged
payment.refunded, payment.partially_refundedA refund completed; see Refunds
{
  "id": "4c6e8a0b-…",
  "type": "payment.provider_pending",
  "data": {
    "intentId": "8d4f6b2a-0c1e-4f3a-9b5d-7e9a1c3b5d6f",
    "merchantId": "m_…",
    "orderId": "ORDER-1006",
    "currency": "TRY",
    "status": "PROCESSING",
    "paymentMethod": "SHOPPING_LOAN",
    "providerCode": "COMPAY",
    "amountMinor": "4500000",
    "pendingSince": "2026-11-12T09:12:00.000Z",
    "pendingUntil": "2026-11-23T09:12:00.000Z",
    "deliverable": false
  }
}

The events carry no personal data. Delivery, signature verification and retry rules → Webhooks.

Next steps