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
422payment.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 sendinstallmentin the request. There is no pre-authorization; withpreauth: truethe request gets422payment.preauth.unsupported_for_methodbefore 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
basketItemsis 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
pricevalues of the items must add up toamount(the rule for all methods). For a shopping loan every item'spricemust be greater than zero. - Send
productCategoryon every item. An item without it is treated asOTHERand 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 productCategory | Class in the loan |
|---|---|
GOLD | Gold: no loan is granted |
MOBILE_PHONE | Mobile phone. An item priced above TRY 40,000.00 and an item priced at TRY 40,000.00 or below are separate classes |
TABLET | Tablet |
COMPUTER | Computer |
| All other codes and items without a category | Other products |
- Items have no quantity field;
priceis 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[] field | Type | Description |
|---|---|---|
bankCode | string | 4-digit BKM bank code; sent in the request as shoppingLoan.bankCode |
bankName | string | Bank name you can show the buyer |
providerCode | string | The 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 |
bankslists 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
bankCodeoptions in the provider'sinputFieldsdefinition 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
400payment.method.block_invalidat request validation (details.fieldshoppingLoan.bankCode,details.reasoninvalid_option). - A bank the provider supports but that is not open in any of your connections gets
422payment.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
Fibabanka0103Garanti BBVA0062
ING Bank0099
Kuveyt Türk0205
Türkiye Finans0206Tü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 get422payment.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 case400payment.provider.requiredis not returned. - If there is no eligible candidate you get
422payment.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
providerCodefield 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/methodsand 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/jsonThe 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
| Field | Type | Required | Description |
|---|---|---|---|
paymentMethod | string | Yes | SHOPPING_LOAN |
shoppingLoan | object | Yes | Shopping loan block; its fields are in the rows below |
shoppingLoan.bankCode | string | Yes | 4-digit code of the bank the buyer chose; one of the banks in the method row's banks list. See Bank selection |
shoppingLoan.providerCode | string | No | The provider the bank goes through. Without it the platform picks; see Choosing the provider |
basketItems | array | Yes | Basket items; productCategory is recommended on every item. See Basket and product category |
callbackUrl | string | No | http 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
shoppingLoanblock: another method's block orcard,force3D,installment,installmentQuoteTokenmake the request fail with400 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": "…"
}| Field | Description |
|---|---|
data.status | PROCESSING: the payment is waiting for the buyer's loan approval at the bank |
action.type | REDIRECT |
action.redirect.url | The address the buyer goes to. See Redirect and return |
action.expiresAt | Latest 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.urlwithout delay (a browserGET). 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. Thestatusfield issuccess,failureorpending. If the application was put on hold at the bank,statusispendingandcodeispayment.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_pendingwebhook is sent once. The body carriesdeliverable: 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
CAPTUREDandpayment.capturedis sent; if the bank declines the application or the process is not completed, the payment becomesFAILEDandpayment.failedis 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
| Situation | What happens | What to do |
|---|---|---|
| The loan was disbursed | The payment is CAPTURED, payment.captured is sent | Ship the order |
| The application is in progress at the bank | The payment is PROCESSING, payment.provider_pending is sent | Do not ship; wait for the result. See Applications pending at the bank |
| The buyer gave up, the bank declined, or the process was not completed | The payment is FAILED, payment.failed is sent | No money moved. Offer the buyer another method |
| The buyer did not go to the bank and come back within 30 minutes | The 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 state | Do not start a new payment; wait for the webhook |
- While the payment is
PROCESSINGorNEEDS_RECONCILIATION, do not start a new payment for the same order. - If the payment is
FAILED, start a new payment with a newIdempotency-Keyto 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.identityNumberon every payment. In the Checkout Form this field is read from thebuyerdata 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.
| Situation | Response | What to do |
|---|---|---|
No shoppingLoan block, bankCode missing or not in the list | 400 payment.method.block_invalid | Fix the details.field field; let the buyer choose the bank from the options |
The basket total does not equal amount | 400 VALIDATION_ERROR | Make the items' price values add up to amount |
| The method is disabled in the panel | 422 payment.method.disabled | Enable 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 sent | 422 payment.method.bank_not_enabled | The 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 settings | 422 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 connected | 422 payment.provider.not_available | Check the provider connection in the panel |
preauth: true was sent | 422 payment.preauth.unsupported_for_method | Send without preauth |
| No basket or an empty basket, or an item priced at zero | 400, payment FAILED | The 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 FAILED | Banks do not lend for gold. Offer the buyer another method |
Your connection requires the identity number and buyer.identityNumber is missing or invalid | 400, payment FAILED | Send the number and start again with a new Idempotency-Key |
| The buyer gave up or the bank declined | Payment FAILED, payment.failed | Offer the buyer another method |
Other codes: Payment — Error codes.
Webhooks
| Event | When |
|---|---|
payment.provider_pending | The application was put on hold at the bank; no funds have moved yet. Do not ship the order. Sent once per payment |
payment.captured | The loan was disbursed; the money reached your account. Ship the order on this event |
payment.failed | The payment failed; nothing was charged |
payment.refunded, payment.partially_refunded | A 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
- Basket Items —
productCategorycodes - Payment — common request, response, actions and error codes
- Shopping Loan Providers — connection details and settings
- Refunds — full and partial refunds
- Checkout Form — Payment — the flow of non-card methods in the form