Sale (Charge a Card)
For invoice, buyer and fiscal-document fields, and the sale application registration awaiting release, see Sales data and support status. merchantReference does not provide an invoice number or fiscal validation.
- Base path
/api/v1/physical-pos- Identity
- Ed25519 request signature on every request —
X-Key-Id,X-Date,X-Nonce,X-Signature, plusDigeston requests with a body. ±5 min clock window, single-use nonce. A Bearer token or a panel session is not accepted here. - Authorization
- The key must carry the Physical POS product (
PHYSICAL_POS) and the scope for the endpoints on this page:physical_pos:payments. Without the product the call gets403 PRODUCT_NOT_ENABLED; without the scope403 API_INSUFFICIENT_SCOPE. See Authentication and Scopes. - Cross-surface
- These endpoints are the s2s surface — call them from your own server with a signed request. The same records have screens in the panel, but panel endpoints cannot be called with an API key, and these endpoints cannot be called with a panel session.
You charge the customer's card on the POS device in your store: a single-payment or instalment sale. The request is sent to the device, the customer presents the card, and the bank's answer reaches you by webhook.
| Method | Path | Scope |
|---|---|---|
POST | /api/v1/physical-pos/payments | physical_pos:payments |
-
This endpoint also starts pre-authorisations and unmatched refunds; for those see Pre-authorisation · Unmatched Refund.
-
Payments are asynchronous:
202means "payment accepted", not "paid". -
Step-by-step guide (choosing the device, storing the key, getting the outcome): Quickstart.
-
Either scope is enough for the read endpoints. The write endpoints take only
physical_pos:payments;physical_pos:managecannot make payments. → Scopes -
Payments live in your key's environment. A test key can only read payments; start, reversal and cancel requests get
403 physical_pos.environment.test_key_read_only. → Environments
The cURL examples compute the signature with lunixi-sign.sh: Authentication › Signing helper.
Starting a payment or a reversal runs when a payment capability definition exists for the target device's model. On a device without a capability definition the request gets 422 physical_pos.payment.operation_unsupported (details.reason: capability_undefined) once the device is found and its terminal link and communication channel are checked; no payment record is created.
Request
POST /api/v1/physical-pos/payments · Idempotency-Key required
Starts a sale, a pre-authorisation or an unmatched refund.
| Field | Type | Required | Description |
|---|---|---|---|
operation | string | Yes | SALE, PREAUTH_OPEN (pre-authorisation) or REFUND_UNMATCHED (unmatched refund). Case-insensitive. |
target | object | Yes | Target device. → Target device |
amountMinor | string | Yes | Amount in minor units (kuruş for TRY); a canonical positive integer string, such as "4500". JSON numbers are rejected. |
currency | string | Yes | ISO 4217 code (TRY). The device and the bank row must support this currency. |
installmentCount | integer | null | No | Installment count, 2–36; SALE only. Omitted, null or 0 means a single payment. |
instrument | string | No | Payment instrument: CARD or MEAL_CARD. Defaults to CARD. → Meal Card Sale |
interaction | string | For MEAL_CARD | INSTRUMENT_READ (card read) or CODE_DISPLAY (QR / short code). Not sent on a card sale. |
terminalProviderId | string (UUID) | No | For MEAL_CARD, the card provider row. Not sent on a card sale. |
merchantReference | string | null | No | Your order or receipt number: printable ASCII without spaces, at most 128 characters. → A new sale with the same reference |
allowDuplicateReference | boolean | No | When true, the duplicate reference checks are skipped. Default false. |
startTimeoutSeconds | integer | No | Time for the payment to start on the device, 5–30 seconds. Omitted or 0 means 30. If the device model's limit is shorter, that limit applies. |
terminalAcquirerId | string (UUID) | null | No | Bank row. → Bank row |
items | array | No | Sale items; SALE only, at most 500 lines. The sum of the lines' lineTotalMinor must equal amountMinor. For a sale without items omit the field; an empty array is rejected. → Items |
source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
BODY='{"operation":"SALE","target":{"vendorCode":"PAVO","serialNumber":"SN0000000001"},"amountMinor":"4500","currency":"TRY","merchantReference":"ORD-2026-000123"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
-H "Content-Type: application/json" \
-H "X-Key-Id: $LUNIXI_KEY_ID" \
-H "X-Date: $DATE" \
-H "X-Nonce: $NONCE" \
-H "Digest: $DIGEST" \
-H "X-Signature: $SIGNATURE" \
-H "Idempotency-Key: 7b0c6a1e-2f8d-4c55-9a51-3f0e8d1c2a90" \
--data-raw "$BODY"A new payment returns 202, a repeat with the same key and the same body 200:
{
"status": "success",
"code": "SUCCESS",
"data": {
"payment": {
"paymentId": "01900000-0000-7000-8000-000000000501",
"rootPaymentId": "01900000-0000-7000-8000-000000000501",
"originalPaymentId": null,
"origin": "API",
"operation": "SALE",
"paymentStatus": "NOT_STARTED",
"statusReason": null,
"outcomeConflict": false,
"resolvable": false,
"deviceId": "00000000-0000-0000-0000-000000000401",
"logicalTerminalId": "00000000-0000-0000-0000-000000000301",
"terminalAcquirerId": null,
"channel": "APP2APP",
"vendorReference": "01900000000070008000000000000501",
"amountMinor": "4500",
"approvedAmountMinor": null,
"currency": "TRY",
"installmentCount": null,
"instrument": "CARD",
"merchantReference": "ORD-2026-000123",
"reversedMinor": "0",
"capturedMinor": "0",
"reversalReservedMinor": "0",
"pendingReversalId": null,
"reversalStatus": "NONE",
"expiresAt": "2026-01-02T09:00:30.000Z",
"resultDeadlineAt": "2026-01-02T09:03:30.000Z",
"completedAt": null,
"settledAt": null,
"settlementBatchNo": null,
"createdAt": "2026-01-02T09:00:00.000Z",
"updatedAt": "2026-01-02T09:00:00.000Z",
"rowVersion": 2,
"historySeq": 1,
"tender": {
"tenderStatus": "PENDING",
"cardMasked": null,
"cardBrand": null,
"entryMode": null,
"acquirerCode": null,
"authCode": null,
"rrn": null
},
"items": [],
"refundItems": []
},
"replayed": false
},
"statusCode": 202,
"requestId": "00000000-0000-0000-0000-000000000000"
}The response says the payment was accepted; follow the outcome by webhook or by reading the payment.
Check order. After the signature, product and scope checks, the request is checked in this order; you get the error of the first step it fails:
- The environment field and field names that look like card data (
400 physical_pos.input.environment_invalid,400 physical_pos.payment.card_data_rejected). - Rate limit (
429 RATE_LIMITED). - Field types and limits (typed codes for amount, currency, installments, reference, start time, target and item fields;
400 VALIDATION_ERRORfor undefined fields and other type errors). If there is more than one error, the response returns the first typed error. - Test key (
403 physical_pos.environment.test_key_read_only). Idempotency-Keyheader.- Service checks:
- Field rules and the card data scan of field values.
- An earlier request with the same key (a repeat or
409 physical_pos.idempotency_mismatch). - Target device, terminal link and communication channel.
- The device model's payment capability: operation, currency, installments.
- The device being ready for payment (connection and the apps on the device).
- Bank row.
- Device and terminal ready to take payments, unmatched refund settings, duplicate reference checks and no other payment running on the device.
For example, a test key sending a malformed body gets 400, not 403; a request over the rate limit gets 429 before the field checks.
Errors:
| HTTP | code | When |
|---|---|---|
400 | physical_pos.idempotency.key_required · .key_invalid | Idempotency-Key missing or malformed. |
400 | physical_pos.payment.target_invalid | Target missing, multiple or malformed (details.reason). |
400 | physical_pos.device.vendor_unknown | Unknown vendor code in a serial target. |
400 | physical_pos.input.serial_invalid | In a serial target, serialNumber is not a string (invalid) or longer than 128 characters (too_long). |
400 | VALIDATION_ERROR | Undefined field (including fields inside target and the item objects); wrong type of operation, instrument or allowDuplicateReference. details.errors[].field gives the field's path. |
400 | physical_pos.payment.amount_invalid | Amount missing, zero or negative, a JSON number, a noncanonical integer string or outside the supported range. |
400 | physical_pos.payment.currency_unsupported | Currency malformed or not supported by the device or the bank row (details.reason: capability). On an unmatched refund, different from the currency in your settings (unmatched_refund_currency). |
400 | physical_pos.payment.installment_unsupported | Installments out of range, outside SALE (details.reason: operation) or above the device model's limit (capability). |
400 | physical_pos.input.ref_invalid | merchantReference malformed. |
400 | physical_pos.payment.card_data_rejected | Card data in the body. → Card data |
400 | physical_pos.validation.invalid | startTimeoutSeconds or terminalAcquirerId malformed (details.field). |
400 | physical_pos.fiscal_document.items_invalid | An item rule is broken. → Items |
400 | physical_pos.input.environment_invalid | environment in the request. |
403 | physical_pos.environment.test_key_read_only | Test key. |
403 | physical_pos.auth.api_key_not_allowed | Unmatched refunds are set to the panel only. |
404 | physical_pos.device.not_found | Target device not found. |
409 | physical_pos.payment.device_busy | A payment, an uncertain outcome hold or an end-of-day is running on the device. → One active payment |
409 | physical_pos.payment.device_offline | The device is not ready for payment: not connected, or one of the apps on the device is not ready. → Device readiness |
409 | physical_pos.payment.device_not_payable · .terminal_not_payable | The device or the terminal is not ready to take payments (details.reason). |
409 | physical_pos.payment.previous_outcome_unknown · .duplicate_reference_recent | An earlier sale with the same reference. → Duplicate reference |
409 | physical_pos.idempotency_mismatch | The key was used with another request. |
422 | physical_pos.payment.operation_unsupported | The operation is not supported on this device, channel or by your settings (details.reason; see below). |
422 | physical_pos.payment.unmatched_refund_limit_exceeded | The unmatched refund limit would be exceeded. |
422 | physical_pos.payment.identity_required | On a SoftPOS device or a device connected through an app, app identity is disabled or no suitable key is selected (details.reason). → App identity |
422 | physical_pos.fiscal_document.unsupported | An item's tax group is not recognised (details.reason: tax_group_unsupported). |
429 | RATE_LIMITED | Rate limit. → Rate limits |
503 | physical_pos.presence.unavailable · physical_pos.signing.unavailable · physical_pos.service.busy · physical_pos.service.clock_skew | Temporary; retry with the same Idempotency-Key, with backoff and a limited number of attempts; if it persists, contact support. → Retries |
details.reason values of physical_pos.payment.operation_unsupported:
details.reason | Meaning |
|---|---|
operation_not_root | operation cannot be used on this endpoint (for reversals use the reversal endpoint). |
instrument_unsupported | instrument is not supported, or the device model does not support this instrument. |
instrument_operation_unsupported, items_instrument_unsupported, provider_terminal_* | Meal card rules. → Meal Card Sale |
items_operation_unsupported | items is sent only on SALE. |
channel_unset | The device's communication channel is not set. |
capability_undefined | The device model has no payment capability definition. |
capability_invalid | The device model's capability definition cannot be used. |
operation_not_supported, capability | The device model does not support this operation. |
disabled_by_setting | Unmatched refunds are off in your account settings. |
terminal_acquirer_not_eligible | terminalAcquirerId is not eligible for this payment. |
Instalment sale
For instalments, send the number of instalments in installmentCount (2–36). If the field is not sent, null or 0, the sale is a single payment.
{"operation":"SALE","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"120000","currency":"TRY","installmentCount":6,"merchantReference":"ORD-2026-000125"}- Instalments apply only to
SALE; on another operation400 physical_pos.payment.installment_unsupported(details.reason:operation). - If the device model's instalment limit is lower:
400 physical_pos.payment.installment_unsupported(details.reason:capability). - The instalment count is returned in the payment object's
installmentCount;nullfor a single payment.
Getting the outcome
You get the outcome by webhook: physical_pos.payment.approved, …partially_approved, …declined, …cancelled, …expired, …failed, …unknown or …manual_review. If you do not want to wait for a webhook, retrieve the payment.
- To undo an approved sale: before end of day Void, afterwards Refund.
- If the outcome stays uncertain, do not start the sale again: Uncertain Outcome.
- To send the sale with product lines: Sale Items.