Payment Orchestrator
Request to Pay

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 422 payment.method.disabled.
  • The currency is TRY. The payment is a single charge: no instalments and no pre-authorisation. With preauth: true the request gets 422 payment.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 providers whose inputFields have no bankCode field and whose actionTypes is APP_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 IBAN field 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/json

The request carries Step-Up authentication (see Authentication) and the mandatory Idempotency-Key header; the rules are the same as in Payment — Idempotency.

Method fields

FieldTypeRequiredDescription
paymentMethodstringYesOPEN_BANKING
openBanking.providerCodestringYesThe providerCode of the Request to Pay entry in the method row
openBanking.ibanstringYesThe buyer's Turkish IBAN; may contain spaces
openBanking.fullNamestringYesFull name of the IBAN holder, 2–70 characters
callbackUrlstringNoThe buyer's browser comes to this address with the result. See Payment — Order fields
  • Do not send openBanking.bankCode for this option; the bank is derived from the IBAN.
  • Order fields (orderId, amount, currency, buyer, description …) are the same for every method. If you set description, it appears as the request description in the buyer's banking app (at most 100 characters); otherwise orderId is 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
}
FieldDescription
data.statusPROCESSING: the payment is waiting for the buyer's approval
action.typeAPP_APPROVAL
action.appApproval.bankCodeFour-digit BKM code of the bank that received the request (from the IBAN)
action.appApproval.bankNameBank name you can show the buyer
action.appApproval.maskedIbanMasked IBAN; the full IBAN is never returned
action.appApproval.expiresAtDeadline 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

SituationWhat happensWhat to do
The buyer approved in the appThe payment becomes CAPTURED, payment.captured is sentDeliver the order
The buyer rejected the request or the bank cancelled itThe payment becomes FAILED, payment.failed is sentNo money moved. Offer a new payment or another method
The buyer did not approve within 30 minutesThe 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 bankDo 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; the buyer could receive two requests and pay twice.
  • If the payment is FAILED, retry with a new payment and a new Idempotency-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.

SituationResponseWhat to do
iban is invalid (format or mod-97), fullName is missing or too short400 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 panel422 payment.method.disabledEnable it on Payment → Form Settings
Request to Pay is not connected422 payment.provider.not_availableCheck the connection in the panel
The bank did not open the request400, payment FAILED (details.rawErrorCode REQUEST_TO_PAY_REJECTED)No request reached the buyer, no money moved. Offer another method
The bank rejected the connection details400, payment FAILED (details.rawErrorCode REQUEST_TO_PAY_CREDENTIALS_REJECTED)Check your connection details in the panel
preauth: true was sent422 payment.preauth.unsupported_for_methodSend without preauth

Other codes: Payment — Error codes.

Webhooks

EventWhen
payment.capturedThe buyer approved and the payment completed. Deliver the order on this event
payment.failedThe 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