Mobile Billing — Payment

POST /payments/direct/payment with paymentMethod: "MOBILE_BILLING" adds the amount to the buyer's mobile phone bill (Faturana Yansıt). The buyer enters the code sent to their line and accepts the provider's agreement; you send both with confirm. This page shows every request field, the response, the confirmation and the errors for mobile billing; the action, confirm and error-code rules shared by all methods are on Payment.

Whether the method is open on your account, its provider, amount limits and the fields asked from the buyer are in the MOBILE_BILLING row of the GET /payments/methods response.

How it works

If the line was already approved for this method, the provider may complete the payment without a code: in that case there is no action in the response and the result returns directly.

Choosing the provider

On this endpoint you do not have to choose the mobile billing provider: on the MOBILE_BILLING row providerSelectionMode is PLATFORM and providerSelection is OPTIONAL. mobileBilling.providerCode is optional:

• If you omit it, the platform picks, before any money moves, one of the providers connected to your account that can take this payment, and pins it to the payment. When one provider is connected, that one is used.
• If you send it, that provider is used. If the code is not connected to this method on your account, the request gets 422 payment.provider.not_available.
• After the choice 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.
• If none of the connected providers can take this payment, the request gets 422 payment.provider.none_eligible; see No provider is eligible.

The checks the platform uses to choose: Listing Methods › How the platform chooses.

You can show the providers on your own payment page in the order of the GET /payments/methods response (displayName, logoUrl) and send the code the buyer chooses. In the Checkout Form the buyer always chooses the provider → Checkout Form — Payment › Provider choice.

No provider is eligible

When more than one provider is connected, you omit providerCode and none of them can take this payment, the payment is not started, nothing is added to the bill and no code is sent:

{
  "status": "failure",
  "code": "payment.provider.none_eligible",
  "message": "None of the connected providers can take this payment; the payment was not started and nothing was charged. …",
  "statusCode": 422,
  "timestamp": "2026-10-12T09:00:00.000Z",
  "service": "api-gateway",
  "systemTime": 1791795600000,
  "requestId": "…",
  "docsUrl": "https://docs.lunixi.com/getting-started/errors#payment.provider.none_eligible",
  "details": {
    "paymentMethod": "MOBILE_BILLING",
    "candidates": [
      { "providerCode": "<providerCode>", "outcome": "INELIGIBLE", "reason": "AMOUNT_OUT_OF_RANGE" },
      { "providerCode": "<providerCode-2>", "outcome": "UNAVAILABLE", "reason": "ELIGIBILITY_TIMEOUT" }
    ]
  }
}

details.candidates[] carries one row per provider. The rows contain no personal data.

• If any result is UNAVAILABLE or NOT_CHECKED, you can retry the same request later.
• You can also choose the provider yourself with mobileBilling.providerCode.
• If every result is INELIGIBLE, offer the buyer another method.

Request

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

The body contains only the mobileBilling block: another method's block, or card, force3D, installment, installmentQuoteToken, gets 400 VALIDATION_ERROR.

Order fields

The amount is sent only in amount; the removed amount fields get 400 payment.amount.field_removed. Sending a field that is not defined here rejects the request with 400 VALIDATION_ERROR.

buyer.gsmNumber is used when mobileBilling.gsmNumber is omitted.

buyer

buyer is optional. If you send it, every field marked "Yes" below must be filled. On a Checkout Form intent (POST /payments/intents, POST /payments/marketplace/intents) this rule does not apply: every field is optional, and the fields you send are checked for type and length.

Required-field rule, how it differs from customerId, and error field paths: Buyer.

Address

shippingAddress and billingAddress share the same shape. If you send the object, all five fields are required.

How the two addresses differ and error field paths: Addresses.

basketItems[]

The sum of the items' price must equal amount; otherwise the request is rejected with 400 VALIDATION_ERROR. The installment fee is not added to the items.

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-10-11T09:00:00.000Z" \
  -H "X-Nonce: 8d4f2c1e-0a7b-4b3c-9e5d-6f1a2b3c4d5e" \
  -H "Digest: SHA-256=..." \
  -H "X-Signature: ..." \
  -H "Idempotency-Key: ORDER-1002-1" \
  -d '{
    "paymentMethod": "MOBILE_BILLING",
    "orderId": "ORDER-1002",
    "amount": 5000,
    "currency": "TRY",
    "basketItems": [
      { "id": "DIGITAL-1", "name": "Dijital ürün", "category1": "Dijital", "itemType": "VIRTUAL", "price": 5000 }
    ],
    "mobileBilling": { "gsmNumber": "+905321234567" }
  }'

Response and action

{
  "status": "partial",
  "code": "CUSTOMER_ACTION_REQUIRED",
  "message": "…",
  "data": {
    "paymentId": "7b0e4c2a-1f3d-4e5b-8a6c-9d0e1f2a3b4c",
    "orderId": "ORDER-1002",
    "status": "PROCESSING",
    "paymentMethod": "MOBILE_BILLING",
    "providerCode": "<providerCode>",
    "action": {
      "id": "act_5c2e9f0a1b3d4e6f7a8b9c0d1e2f3a4b",
      "type": "OTP",
      "expiresAt": "2026-10-11T09:03:00.000Z",
      "otp": { "maskedTarget": "53****67" },
      "consent": { "required": true, "url": "https://…" }
    }
  },
  "statusCode": 202,
  "requestId": "…"
}

• <providerCode> is a placeholder.
• The code's validity is in action.expiresAt.
• consent.url is the provider's agreement address; show it to the buyer as a link they can open.

Confirm

POST https://api-gateway.lunixi.com/api/v1/payments/{paymentId}/actions/{actionId}/confirm

{ "otp": "123456", "consentAccepted": true }

If the code expires, the payment becomes FAILED and payment.failed is sent.

Resending the code

If the buyer did not receive the code, send a new one with POST /payments/{paymentId}/actions/{actionId}/resend. The response carries a new action; use the new action.id for confirm. A code can be resent at most 3 times per payment, with at least 30 seconds between sends; the rules are the same as in Payment — resend.

Line eligibility and limits

• If the line is closed to this method, not eligible, or its billing limit is not enough for the amount, the payment is declined: response 400, data.status FAILED. Offer the buyer another method.
• When more than one provider is connected and you omit providerCode, eligibility is checked with the providers before the payment starts. If none is eligible the response is 422 payment.provider.none_eligible; no payment record is opened.
• Amount limits and currencies are in the minAmount, maxAmount and currencies fields of the GET /payments/methods response.

Pre-authorization

Pre-authorization support is shown by the preauth field of the GET /payments/methods response. When it is not supported, a request with preauth: true gets 422 payment.preauth.unsupported_for_method before the payment starts; nothing is added to the bill.

Errors

Codes of the action endpoints: Payment — Error codes.

Webhooks

The data of the events carries paymentMethod: "MOBILE_BILLING" and the provider's providerCode. See Webhooks.

Next steps

• Listing Methods — connected providers and provider selection
• Payment — common request, response and error codes
• Checkout Form — Payment — the mobile billing flow in the form