Payment — Single Endpoint

POST /payments/direct/payment starts a payment from your server with any payment method open on your account: card, wallet, mobile billing (Faturana Yansıt) and promissory notes (Senetle Öde) use the same endpoint and the same order fields. The paymentMethod field selects the method; method-specific data goes in that method's block. When the buyer has to do something (enter a verification code, go to a bank page) the response carries an action. The final result is always sent by webhook as well.

How it works

Methods

• The methods above can be started from this endpoint today. The other methods in the Payment menu are coming soon.
• This endpoint takes a single method. To split one order across several cards and methods, use the Split Payments endpoint.
• The methods and providers you can use are in the GET /payments/methods response.
• An unknown method code gets 400 payment.method.unknown; a method that cannot be used on this endpoint gets 400 payment.method.not_supported. The request is never turned into another method or into a card payment.

Authentication

POST /payments/direct/payment and GET /payments/methods require Step-Up: your Authorization: Bearer at_… token and an Ed25519 signature of the request.

How to build the signature is described on Authentication. The endpoints require the Payment Gateway product to be active on your account.

Listing the open methods

GET /payments/methods returns the methods open on your account, the providers of each method, who chooses the provider (providerSelectionMode) and the fields asked from the buyer (inputFields); ?paymentMethod= reads a single method's row. Methods and providers come in your Form Settings order. The endpoint, the response fields, the order and the provider selection rules: Listing Methods.

Method fields (inputFields)

The fields in the block are defined by the provider's inputFields definition; you send the values under the definition's key. The definition's fields and value types: Listing Methods › Method fields.

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

• A key that is not in the definition, a missing required field or a value that does not match its type gets 400 payment.method.block_invalid. The offending field is in details.field (e.g. mobileBilling.gsmNumber) and details.reason; every violation is listed in details.errors[]. The value you sent is never included in the error response.
• In nested fields the path points to the field: promissoryNote.address.districtCode, promissoryNote.guarantors[1].identityNumber.
• details.reason values: unknown_field, required, not_applicable (a field sent while its requiredWhen condition does not hold), invalid_type, invalid_format, too_short, too_long, invalid_option, too_few_items, too_many_items (GROUP item count). Method-specific reasons are on the method page, e.g. Promissory Notes.
• Values are only passed to the provider; they are not stored on the payment record.

Address dictionary

The province, district and neighbourhood codes of an ADDRESS field come from the Lunixi address dictionary. The dictionary endpoints are public: they need no authentication and return no personal data. Responses may be cached for a day.

GET https://api-gateway.lunixi.com/api/v1/reference/tr-address/districts?provinceCode=06

{
  "status": "success",
  "code": "SUCCESS",
  "message": "…",
  "data": {
    "items": [
      { "code": "<districtCode>", "name": "<district name>" }
    ]
  },
  "statusCode": 200,
  "requestId": "…"
}

• Read the codes from the dictionary and let the buyer pick by name; do not build codes by hand. If the neighbourhood, district and province do not belong together the request gets 400 payment.method.block_invalid (….address.neighborhoodCode, invalid_option).
• An invalid provinceCode or districtCode query gets 400. For a province or district without entries in the dictionary the list is empty.

Request

POST https://api-gateway.lunixi.com/api/v1/payments/direct/payment
Content-Type: application/json

Fields

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 a prefill source for method fields: it is used when the wallet or mobile billing block has no phone. metadata is not read in payment decisions: for example a method or pre-authorization value written into metadata does not change the payment.

card

• When sent, expireMonth and expireYear must have two digits.
• For a raw card charge send cardHolderName, cardNumber, expireMonth, expireYear and cvcNumber. For a saved card charge send cardUserKey and cardToken instead of the raw card fields.

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.

Rules

• The amount is sent only in amount; the removed amount fields get 400 payment.amount.field_removed. If you send basketItems, the items' price must add up to amount; otherwise the request gets 400 VALIDATION_ERROR.
• If a card installment is chosen (installment + installmentQuoteToken), the system computes the installment fee from the quote and adds it to the charged amount: charged amount = amount + installment fee. Amount fields in queries and webhooks show this charged amount.
• The body contains only the block that matches paymentMethod. Another method's block, or card, force3D, installment, installmentQuoteToken with a non-card method, gets 400 VALIDATION_ERROR.
• The method's block is required. The fields in the block are the provider's inputFields definition; apart from providerCode, fields that are not in the definition cannot be sent.
• providerCode: not needed when one provider is connected for the method. When more than one is connected, the method's providerSelectionMode sets the rule:
  • BUYER (e.g. wallet): required; if you omit it you get 400 payment.provider.required with the connected codes in details.boundProviderCodes.
  • PLATFORM (e.g. mobile billing): optional. If you omit it, the platform picks one of the connected providers before any money moves; if none of them can take this payment you get 422 payment.provider.none_eligible.
• The selected provider is pinned: on an error the payment does not move to another provider, another method or card.
• A provider you turned off only for the form in Form Settings is accepted on this endpoint; turning it off affects only the Checkout Form. To turn a provider off everywhere, turn off its provider connection.
• An undefined field (method, basketId, paymentSource …) gets 400 VALIDATION_ERROR.

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": "Digital product", "category1": "Digital", "itemType": "VIRTUAL", "price": 5000 }
    ],
    "mobileBilling": { "gsmNumber": "+905321234567" }
  }'

Method-specific examples: Card — 2D, Card — 3D Secure, Pay with Wallet, Mobile Billing, Promissory Notes.

Response

The response uses the common envelope; the payment itself is in data. Starting a payment, confirm and resend use the same shape.

{
  "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": "…"
}

In a decline, details.retryability (RETRYABLE, NON_RETRYABLE, UNKNOWN) tells whether retrying the same request makes sense. If the request was rejected before it was processed (validation, authentication, method or provider error), data is empty and code describes the error; see Errors.

data fields

Actions

action tells you the buyer has to do something. A payment has at most one open action at a time. The types a method can return are in the actionTypes field of the GET /payments/methods response.

If you receive a type you do not recognise, do not treat the payment as paid; wait for the webhook.

Provider session data, references and verification codes never appear in any response, query or webhook.

Confirming an action — confirm

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

Completes the open action; it does not start a new charge. When calling from your server, send the signature headers described on Authentication (X-Key-Id, X-Date, X-Nonce, Digest, X-Signature); do not put token in the body. If the payment does not belong to your account or the action cannot be found you get 404 payment.action.not_found.

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

The response has the same shape as the payment response:

• If you send the same confirm again, the provider is not called a second time; the recorded result is returned. If your connection dropped you can safely repeat the request.
• Attempts are counted per action; unless the provider declares otherwise there are 3.
• When the action expires (expiresAt) it is closed. For a verification code sent by a provider the payment becomes FAILED and payment.failed is sent; for the merchant's own wallet program see Pay with Wallet.
• If the code or the consent is missing, the request is rejected without using an attempt: payment.action.otp_required, payment.action.consent_required.

Resending the code — resend

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

Sends a new code when the provider supports it. The previous action is closed and the response (202) carries the new action; use the new action.id for confirm. The body is empty ({}); authentication is the same as for confirm.

• A code can be resent at most 3 times per payment; after that you get 422 payment.action.resend_limit_reached.
• At least 30 seconds must pass between sends; an earlier request gets 429 payment.action.resend_too_soon with the wait time in details.retryAfterSeconds.
• For a method that does not support resending you get 422 payment.action.resend_not_supported.
• If the provider cannot send the code you get 502 payment.action.resend_failed and the current action stays open.
• A confirm on the old action gets 409 payment.action.replaced; the new action's ID is in details.replacedByActionId.

Pre-authorization

To hold the amount before charging it, send "preauth": true. When the payment succeeds it becomes AUTHORIZED and payment.authorized is sent; you later charge it with capture or remove the hold with void.

• For card the rules are on Card — 2D and Card — 3D Secure.
• For a non-card method the provider must support pre-authorization (preauth in the GET /payments/methods response). With a method that does not, the request gets 422 payment.preauth.unsupported_for_method before the payment starts; nothing is charged.
• preauth must be a boolean; a value sent inside metadata does not request a pre-authorization.

Capture, void, expiry and errors: Pre-authorization, Capture & Void.

Idempotency

Idempotency-Key is required on this endpoint (at most 200 characters). Without it the request gets 400 payment.operation.idempotency_key_required and is not processed. Use a value that identifies the attempt, not the payment (for example ORDER-1002-1).

To retry a declined order, send a new Idempotency-Key.

Results and webhooks

The data object of payment events carries paymentMethod and providerCode:

{
  "id": "2f6c1b9e-…",
  "type": "payment.captured",
  "data": {
    "intentId": "7b0e4c2a-1f3d-4e5b-8a6c-9d0e1f2a3b4c",
    "merchantId": "m_…",
    "orderId": "ORDER-1002",
    "currency": "TRY",
    "status": "CAPTURED",
    "paymentMethod": "MOBILE_BILLING",
    "providerCode": "<providerCode>",
    "capturedAmountMinor": "5000"
  }
}

When you query the payment with GET /payments/:id, the response also carries paymentMethod and, when an action is open, action. For delivery, signature verification and the other fields see Webhooks.

Errors

Error responses use the common error envelope; branch on code, not on message → Error Handling.

Method-specific errors are on the method pages.

Error codes

The codes below are specific to payment methods, provider selection and the action endpoints.

Next steps

• Listing Methods — open methods, provider selection and method fields
• Card — 2D (Card — 2D) and 3D Secure (Card — 3D Secure) card payments from this endpoint
• Pay with Wallet — wallet providers and the merchant's own wallet program
• Mobile Billing — paying with the phone bill
• Promissory Notes — deferred collection with electronic promissory notes
• Pre-authorization, Capture & Void — hold now, charge later
• Webhooks — payment events