Request to Pay — Payment
Request to Pay is a separate option under Open Banking (paymentMethod: "OPEN_BANKING"). The buyer enters their IBAN and full name; Lunixi sends a payment request to the buyer's bank. The buyer approves the request in their banking app and the money reaches your account.
There is no bank selection: the bank is derived from the buyer's IBAN. That is why Request to Pay is shown in its own row, not among the Open Banking bank rows.
The payment runs with an APP_APPROVAL action: you do not ask the buyer for a code and you do not call confirm. The final result is verified with the bank and reported with the payment.captured or payment.failed webhook.
All amounts are canonical minor-unit strings: "amount": "250000" = ₺2,500.00. Request, response and error rules shared by every method are on the Payment page. For a redirect payment where the buyer picks a bank, see Open Banking.
How it works
Collect the IBAN and full name
Ask the buyer for the IBAN of the paying account and the account holder's full name. The fields are defined in inputFields of the method row; see Method row.
Start the payment
Start the payment with the Checkout Form or from your server with the Direct API. The response (202) carries an APP_APPROVAL action.
The buyer approves in the banking app
The payment request goes to the buyer's bank. Show the buyer which bank received the request (action.appApproval) and ask them to approve it in their app. In the Checkout Form the form shows this screen.
Get the result
The platform queries the request status from the bank. Once the buyer approves, the payment becomes CAPTURED and the payment.captured webhook is sent. Deliver the order on payment.captured.
Prerequisites
- Request to Pay needs a creditor account and the Request to Pay service at Misyon Bank; payments go to that account. In the panel, connect Misyon Bank Ödeme İste on POS Center → Discover and enter the details Misyon Bank gave you → Open Banking Providers.
- In the panel, enable the Open Banking method on Payment → Form Settings; Request to Pay is one of its options. A method disabled in the panel is disabled on every channel; a Direct API request gets
422payment.method.disabled. - The currency is
TRY. The payment is a single charge: no instalments and no pre-authorisation. Withpreauth: truethe request gets422payment.preauth.unsupported_for_method. - Request to Pay cannot be a leg of a split payment.
Method row
In the OPEN_BANKING row of the GET /payments/methods response, Request to Pay is the entry in providers that asks for the iban and fullName fields. It is not in the banks list and has no bankCode field. The output below is shortened:
{
"paymentMethod": "OPEN_BANKING",
"blockName": "openBanking",
"actionTypes": ["REDIRECT", "APP_APPROVAL"],
"providers": [
{
"providerCode": "MISYON",
"displayName": "Misyon Bank Ödeme İste",
"actionTypes": ["APP_APPROVAL"],
"currencies": ["TRY"],
"preauth": false,
"inputFields": [
{ "key": "iban", "type": "IBAN", "required": true, "label": { "tr": "IBAN", "en": "IBAN" }, "pii": true },
{
"key": "fullName", "type": "TEXT", "required": true, "minLength": 2, "maxLength": 70,
"label": { "tr": "Hesap sahibinin adı soyadı", "en": "Account holder full name" }, "pii": true
}
],
"splitEligible": false,
"splitBehavior": null
}
],
"banks": []
}- Recognise Request to Pay as the entry in
providerswhoseinputFieldshave nobankCodefield and whoseactionTypesisAPP_APPROVAL. Always read the provider code from this response; do not hard-code it. - If Open Banking also has bank rows (
banks), show Request to Pay separately from them. Suggested row text: Request to Pay — A payment request is sent to your bank; approve it in your banking app. - The
IBANfield type: Turkish IBAN, 26 characters; spaces and dashes are removed, letters are upper-cased and the mod-97 check is applied. All field properties: Listing Methods › Method fields.
With the Checkout Form
In the form, the Checkout Form SDK makes the Request to Pay calls. Your code is the same as for a card payment: create the intent on your server and mount the form on your page → Checkout Form. The method's form group is open_banking.
What the buyer sees
Chooses Request to Pay
Under Open Banking, the buyer chooses the Request to Pay row below the bank rows.
Enters the IBAN and name
The buyer enters their IBAN and the account holder's full name and starts the payment. The IBAN is checked in the form as well.
Approves in the banking app
The form shows the bank that received the request, the masked IBAN and the time left. The buyer approves the request in their banking app; the form follows the result on its own.
Sees the result
After approval the payment completes. If you set callbackUrl on the intent, the buyer comes to your page with the signed result form; otherwise they see Lunixi's result page.
With the Direct API
POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment
Content-Type: application/jsonThe request carries Step-Up authentication (see Authentication) and the mandatory Idempotency-Key header; the rules are the same as in Payment — Idempotency.
Method fields
| Field | Type | Required | Description |
|---|---|---|---|
paymentMethod | string | Yes | OPEN_BANKING |
openBanking.providerCode | string | Yes | The providerCode of the Request to Pay entry in the method row |
openBanking.iban | string | Yes | The buyer's Turkish IBAN; may contain spaces |
openBanking.fullName | string | Yes | Full name of the IBAN holder, 2–70 characters |
callbackUrl | string | No | The buyer's browser comes to this address with the result. See Payment — Order fields |
- Do not send
openBanking.bankCodefor this option; the bank is derived from the IBAN. - Order fields (
orderId,amount,currency,buyer,description…) are the same for every method. If you setdescription, it appears as the request description in the buyer's banking app (at most 100 characters); otherwiseorderIdis used.
Example request
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-16T09:00:00.000Z" \
-H "X-Nonce: 6e1b3d5f-7a9c-4e2b-8d0f-1a3c5e7b9d2f" \
-H "Digest: SHA-256=..." \
-H "X-Signature: ..." \
-H "Idempotency-Key: ORDER-2001-1" \
-d '{
"paymentMethod": "OPEN_BANKING",
"orderId": "ORDER-2001",
"amount": "250000",
"currency": "TRY",
"openBanking": {
"providerCode": "MISYON",
"iban": "TR60 0006 2012 3456 7890 1234 56",
"fullName": "Ayşe Yılmaz"
}
}'Response
{
"status": "partial",
"code": "CUSTOMER_ACTION_REQUIRED",
"data": {
"paymentId": "8c1e3a5f-7b9d-4f2a-9c0e-3b5d7f9a1c2e",
"orderId": "ORDER-2001",
"status": "PROCESSING",
"paymentMethod": "OPEN_BANKING",
"providerCode": "MISYON",
"action": {
"id": "act_7c9e1b3d5f7a9c0e2f4a6c8e0b1d3f5a",
"type": "APP_APPROVAL",
"expiresAt": "2026-11-16T09:30:00.000Z",
"appApproval": {
"bankCode": "0062",
"bankName": "Garanti BBVA",
"maskedIban": "TR6000062*************3456",
"expiresAt": "2026-11-16T09:30:00.000Z"
}
}
},
"statusCode": 202
}| Field | Description |
|---|---|
data.status | PROCESSING: the payment is waiting for the buyer's approval |
action.type | APP_APPROVAL |
action.appApproval.bankCode | Four-digit BKM code of the bank that received the request (from the IBAN) |
action.appApproval.bankName | Bank name you can show the buyer |
action.appApproval.maskedIban | Masked IBAN; the full IBAN is never returned |
action.appApproval.expiresAt | Deadline for the buyer's approval (ISO 8601); 30 minutes after the request opens |
You make no call to approve. Query the status with GET /payments/:id or wait for the webhook.
Result
| Situation | What happens | What to do |
|---|---|---|
| The buyer approved in the app | The payment becomes CAPTURED, payment.captured is sent | Deliver the order |
| The buyer rejected the request or the bank cancelled it | The payment becomes FAILED, payment.failed is sent | No money moved. Offer a new payment or another method |
| The buyer did not approve within 30 minutes | The platform asks the bank; if the request is closed the payment becomes FAILED. If the bank gives no definitive answer the payment shows NEEDS_RECONCILIATION and the result is verified with the bank | 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; the buyer could receive two requests and pay twice. - If the payment is
FAILED, retry with a new payment and a newIdempotency-Key. - The payment completes only when the amount reported by the bank equals the requested amount.
Refunds, cancellation and pre-authorisation
- Request to Pay payments cannot be refunded, fully or partially. If you need to pay the buyer back, do it outside Lunixi from your own bank.
- An open payment request cannot be withdrawn through Lunixi; it closes by itself when it expires.
- Pre-authorisation is not supported.
Errors
Error responses use the common error envelope; branch on code, not on message → Error Handling.
| Situation | Response | What to do |
|---|---|---|
iban is invalid (format or mod-97), fullName is missing or too short | 400 payment.method.block_invalid (details.field openBanking.iban or openBanking.fullName) | Fix the field; the payment did not start |
| The method is disabled in the panel | 422 payment.method.disabled | Enable it on Payment → Form Settings |
| Request to Pay is not connected | 422 payment.provider.not_available | Check the connection in the panel |
| The bank did not open the request | 400, payment FAILED (details.rawErrorCode REQUEST_TO_PAY_REJECTED) | No request reached the buyer, no money moved. Offer another method |
| The bank rejected the connection details | 400, payment FAILED (details.rawErrorCode REQUEST_TO_PAY_CREDENTIALS_REJECTED) | Check your connection details in the panel |
preauth: true was sent | 422 payment.preauth.unsupported_for_method | Send without preauth |
Other codes: Payment — Error codes.
Webhooks
| Event | When |
|---|---|
payment.captured | The buyer approved and the payment completed. Deliver the order on this event |
payment.failed | The payment failed; no money was taken |
The event data contains paymentMethod: "OPEN_BANKING" and the providerCode. Delivery, signature verification and retry rules → Webhooks.
Next steps
- Open Banking — redirect payment with bank selection
- Listing Methods — method row and method fields
- Payment — shared request, response, actions and error codes