Listing Methods

GET /payments/methods returns the payment methods open on your account: each method's providers, who chooses the provider, the fields asked from the buyer, amount limits, currencies and the actions the buyer may need to take. Read this response before you start a payment with POST /payments/direct/payment. The Checkout Form uses the same list.

The list only contains methods that are enabled in your Checkout Form settings (panel: Payments → Form Settings) and have at least one connected provider. Methods and providers come in the order you set in Form Settings; see Order.

Flow

Request

GET https://api-gateway.lunixi.com/api/v1/payments/methods

The endpoint requires Step-Up authentication (Bearer token and Ed25519 signature headers); it has no body, so no Digest header is sent. How to build the signature is described on Authentication. The endpoint requires the Payment Gateway product to be active on your account.

Filter (?paymentMethod=)

GET https://api-gateway.lunixi.com/api/v1/payments/methods?paymentMethod=MOBILE_BILLING

• Without the parameter, all open methods are returned.
• With the parameter, the response is still the methods list and carries only that method's row. The row is identical to the row in the unfiltered list.
• If the method is disabled in your form settings or has no connected provider, the response is 200 with { "methods": [] }; no error is returned.
• An unknown code, a lower-case code (mobile_billing), an empty value (?paymentMethod=) and a repeated parameter get 400 payment.method.unknown. The valid codes are in the details.allowed list; see Errors.
• Other query parameters are ignored.

Response

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "methods": [
      {
        "paymentMethod": "CARD",
        "category": "CARD",
        "blockName": "card",
        "displayName": "Card",
        "providerSelection": "ROUTED",
        "providerSelectionMode": "PLATFORM",
        "actionTypes": ["REDIRECT"],
        "currencies": ["TRY"],
        "minAmount": null,
        "maxAmount": null,
        "preauth": true,
        "providers": [],
        "splitEligible": true,
        "splitBehavior": "HOLD_CAPTURE"
      },
      {
        "paymentMethod": "MOBILE_BILLING",
        "category": "TELCO",
        "blockName": "mobileBilling",
        "displayName": "Mobile billing",
        "providerSelection": "OPTIONAL",
        "providerSelectionMode": "PLATFORM",
        "actionTypes": ["OTP"],
        "currencies": ["TRY"],
        "minAmount": 100,
        "maxAmount": 50000,
        "preauth": false,
        "providers": [
          {
            "providerCode": "<providerCode>",
            "displayName": "<provider display name>",
            "logoUrl": "https://…",
            "actionTypes": ["OTP"],
            "currencies": ["TRY"],
            "minAmount": 100,
            "maxAmount": 50000,
            "preauth": false,
            "inputFields": [
              {
                "key": "gsmNumber",
                "type": "PHONE",
                "required": true,
                "label": { "tr": "Faturasına yansıtılacak hat", "en": "Mobile line to be billed" },
                "prefill": "buyer.gsmNumber",
                "pii": true,
                "pattern": null,
                "minLength": null,
                "maxLength": null,
                "options": [],
                "url": null
              }
            ],
            "splitEligible": true,
            "splitBehavior": "CAPTURE_IRREVERSIBLE"
          }
        ],
        "splitEligible": true,
        "splitBehavior": "CAPTURE_IRREVERSIBLE"
      }
    ]
  },
  "statusCode": 200,
  "requestId": "…"
}

Method row

Provider row (providers[])

Order

You order the methods, and the providers within each method, in the panel on Payments → Form Settings. This endpoint, the Checkout Form and the panel use the same order.

• Methods come in your order. If you have not set one, the default order is: CARD, BNPL, SHOPPING_LOAN, PROMISSORY_NOTE, MEAL_CARD, GIFT_CARD, CASH, CASH_ON_DELIVERY, WALLET, BANK_TRANSFER, OPEN_BANKING, MOBILE_BILLING, QR_CODE, CRYPTO, OTHER. The list contains only the methods open on your account.
• Providers (providers[]) come in your order within the method. If you have not set one, they are sorted by provider code.
• A provider you connect later is added to the end of its method's order. A provider whose connection you turn off drops out of the list.
• The order is the same in the test and live environments.

A provider you turned off only for the form in Form Settings stays in this list and can be used with POST /payments/direct/payment; it is not shown in the Checkout Form. To turn a provider off everywhere, turn off its provider connection → Checkout Form — Payment › Order and providers shown in the form.

Split payment fields

splitEligible and splitBehavior on a row tell you whether the method and provider can be used in a split payment and how they are charged there.

• On a provider row, splitEligible is true when the provider supports split payments and you enabled the method for split payments in Form Settings.
• splitBehavior is a property of the provider: it is shown even if you have not enabled the method for split payments.
• For a non-card leg of a split payment, use only providers with splitEligible: true.

Order details: Multiple Payment Methods › Order of the steps.

Provider selection

More than one provider may be connected to a method on your account. providerSelectionMode on the method row tells you what happens when you do not send providerCode:

Modes of the methods available today:

Relation to providerSelection

providerSelection tells you directly whether you must send providerCode; its value is derived from the mode and the number of connected providers:

An integration that sends providerCode whenever providerSelection is REQUIRED works correctly. Whether you show the buyer a list of providers is up to you: for a PLATFORM method you can also show the list and send the code the buyer chooses.

How the platform chooses

For a PLATFORM method, when you omit providerCode and more than one provider is connected, the platform tries the providers in turn and picks the first one that can take this payment:

• The amount and currency must be within the provider's limits.
• If you sent preauth: true, the provider must support pre-authorization.
• The fields in the method block must match the provider's inputFields definition.
• If the provider supports checking the buyer's eligibility (e.g. whether the line is open to this method), the check must come back positive. This check does not move money.

After the choice:

• The chosen provider is pinned to the payment. If something fails, the payment does not move to another provider, another method or a card.
• The provider that runs the payment is in the providerCode field of the response and the webhook.
• A request repeated with the same Idempotency-Key does not choose again; the provider chosen on the first request is used.

Two cases during platform selection return the same code as a single-provider method:

• If every provider was ruled out only because it does not support pre-authorization: 422 payment.preauth.unsupported_for_method.
• If the method block matches no provider's field definition: 400 payment.method.block_invalid.

Method fields (inputFields)

Each provider may ask the buyer for different data: a phone number, a Turkish ID number, a date of birth and so on. The provider's inputFields definition tells you which fields are needed; you send the values in the method block under the definition's key:

"mobileBilling": { "providerCode": "<providerCode>", "gsmNumber": "+905321234567" }

How the fields are validated in the request and the error details: Payment — Method fields.

Errors

{
  "status": "failure",
  "code": "payment.method.unknown",
  "message": "Unknown payment method — send a valid method code in `paymentMethod`.",
  "statusCode": 400,
  "timestamp": "2026-10-12T09:00:00.000Z",
  "service": "api-gateway",
  "systemTime": 1791795600000,
  "requestId": "…",
  "details": {
    "field": "paymentMethod",
    "allowed": ["CARD", "BNPL", "SHOPPING_LOAN", "PROMISSORY_NOTE", "MEAL_CARD", "GIFT_CARD", "CASH", "CASH_ON_DELIVERY", "WALLET", "BANK_TRANSFER", "OPEN_BANKING", "MOBILE_BILLING", "QR_CODE", "CRYPTO", "OTHER"]
  }
}

details.allowed carries every recognized method code. Read whether a method is usable on your account from the unfiltered list.

Next steps

• Payment — the POST /payments/direct/payment request, actions and error codes
• Credit/Debit Card · Pay with Wallet · Mobile Billing — method-specific requests
• Checkout Form — Payment — the same methods in the form