Physical POS
Quickstart: First Payment

Quickstart: First Payment

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.

Who calls these endpoints?External API (s2s)
Base path
/api/v1/physical-pos
Identity
Ed25519 request signature on every request — X-Key-Id, X-Date, X-Nonce, X-Signature, plus Digest on 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 · physical_pos:view. Without the product the call gets 403 PRODUCT_NOT_ENABLED; without the scope 403 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.

This guide takes you through starting a sale on a POS device in your store from your own server, end to end: you choose the device, start the payment, read the response and get the outcome. The card is read on the device; the API takes no card data.

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.

1. Choose the device   GET  /devices                  → presence.decision: READY
2. Start the payment   POST /payments                 → 202 · paymentStatus: NOT_STARTED
3. Store the response  paymentId, resultDeadlineAt
4. Get the outcome     webhook physical_pos.payment.*  or  GET /payments/{paymentId}

The payment state machine, reversals and end of day: Payment Flow. Every field and error code of the endpoints: Payment Operations.

Before you start

API key and scopes

RequirementDescription
Live API key (mk_live_…)You start payments with a live key. A test key only reads payments; a start request gets 403 physical_pos.environment.test_key_read_only. → Environments
Physical POS productYour key must have the PHYSICAL_POS product; otherwise 403 PRODUCT_NOT_ENABLED.
physical_pos:payments scopeStarting, reversing and cancelling payments is possible only with this scope. It also reads payments, transactions and reports.
physical_pos:view scopeNeeded to read devices (Step 1). physical_pos:manage cannot make payments and does not include reads.
Request signatureEvery request is signed with your API key; requests with a body also send the Digest header. → Authentication › Signing helper

physical_pos:payments is not added to your existing keys automatically; select it in the key's permission settings in the panel. → Scopes

⚠️

Payments cannot be started in the test environment. You can try reads, signing and scope errors with a test key; you start payments with a live key and a real device. Keep the live key on your server only.

Device and terminal

For a device to take payments it must be active, its ownership verified, linked to a logical terminal and connected to Lunixi and ready. The steps to prepare a device from scratch and the full list of conditions: Preparing a Device for Payments.

How your request reaches the device

The payment request is delivered, depending on the device record's connection method (integrationChannel), to the Lunixi app on the device or to the vendor's cloud service; you always send the same request. Methods, differences by device model and what happens when the device is offline: Connection Methods.

Step 1 — Choose the device

Choose the device you will start the payment on from the list. List rows carry a summary of the device's connection status (presence), so a single request shows which devices are ready for payment.

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/devices?storeId=00000000-0000-0000-0000-000000000101&lifecycleStatus=ACTIVE&ownershipStatus=VERIFIED"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

Check these fields on each row of the response (the other fields of the row: Devices › Device object):

{
  "id": "00000000-0000-0000-0000-000000000401",
  "displayName": "Till 1 POS",
  "lifecycleStatus": "ACTIVE",
  "ownershipStatus": "VERIFIED",
  "integrationChannel": "APP2APP",
  "logicalTerminal": { "id": "00000000-0000-0000-0000-000000000301", "code": "IST-KADIKOY-01" },
  "presence": {
    "connectionState": "ONLINE",
    "lastSeenAt": "2026-01-02T08:59:50.000Z",
    "readyForPayment": true,
    "notReadyReason": null,
    "decision": "READY",
    "source": "LIVE"
  }
}

presence.decision is the result the device readiness check will give when you start a payment:

presence.decisionMeaningIf you start a payment
READYThe device is connected and ready to take a payment.Passes the readiness check.
NOT_READY_DEVICEThe device is not connected, has not sent a signal for a while, or one of the apps on the device is not ready. The reason is in presence.notReadyReason.409 physical_pos.payment.device_offline
UNVERIFIABLELunixi cannot verify the device's status at the moment; the cause is not on your device.503 physical_pos.presence.unavailable
  • The value set can grow; do not treat a value you do not recognise as READY. presence is null when it could not be read.
  • presence covers only the connection and the apps on the device. The device's status, ownership and terminal link are checked separately against the conditions above.
  • You see why a device is not ready, and whether a payment is running on it (presence.busy), in the device detail: GET /api/v1/physical-pos/devices/{deviceId}. → Devices › Connection status
  • This read is optional. Readiness is checked again on every payment request; the device can lose its connection between the read and the payment.

You use the device's id as target.deviceId in the payment. If you work with your own device identifiers, you can also target the device by the externalRef you gave when registering it: Target device.

Step 2 — Start the payment

Create and store an Idempotency-Key

Idempotency-Key is required on payment start and reversal requests. The key prevents a second payment from being opened for the same sale after a network error.

  1. Create a new UUID for every payment.
  2. Write the key to your own records together with your order before you send the request.
  3. Send the request with this key. Use the same key and the same body on every attempt of the same payment.
EndpointIdempotency-Key
POST /paymentsRequired
POST /payments/{paymentId}/reversalsRequired
POST /payments/{paymentId}/cancelOptional

Format: 8–200 printable ASCII characters without spaces. A missing header gets 400 physical_pos.idempotency.key_required, a malformed one 400 physical_pos.idempotency.key_invalid.

SituationResult
New keyThe payment is opened: 202, replayed: false.
Same key, same bodyNo new payment is opened; the payment is returned in its current state: 200, replayed: true. The response is not a copy of the first response; it shows the payment's state at that moment.
Same key, different body or another operation (e.g. a refund with a sale's key)409 physical_pos.idempotency_mismatch.
  • Bodies are compared after the field rules are applied; field order does not matter.
  • On a reversal, the paymentId in the path is part of the comparison.
  • If the request was rejected by a field rule or a device or terminal check (e.g. 400, 404, 409 device_busy, 409 device_offline, 422), nothing is written; you can retry with the same key.
  • A key is kept for at least 7 days. After that, the same key opens a new payment: use a new UUID for every payment; do not reuse keys.
  • The panel and your live API key share the same key space.
🚫

After a network error, retry with the same key. When you get a timeout, a dropped connection, a 5xx or 503 physical_pos.service.busy, repeat the request with the same Idempotency-Key and the same body: if the payment was opened, the existing payment comes back with replayed: true; if not, it is opened now. Retrying with a new key can open a second payment. → Retries

On the cancel endpoint the key is optional; repeating a cancellation is always safe. If you send a key, the same key on the same payment's cancellation returns the payment's current state with replayed: true; the same key on another payment or another operation gets 409 physical_pos.idempotency_mismatch.

Send the request

POST /api/v1/physical-pos/payments · Idempotency-Key required

The request below starts a single (non-instalment) sale of 45.00 TRY on the device:

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments"
IDEMPOTENCY_KEY="7b0c6a1e-2f8d-4c55-9a51-3f0e8d1c2a90"   # store it with your order first
BODY='{"operation":"SALE","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"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: $IDEMPOTENCY_KEY" \
  --data-raw "$BODY"
  • The cURL example computes the signature with lunixi-sign.sh. Send the body as compact JSON without spaces; Digest is computed from this text. → Signing helper
  • The SDKs sign the request, repeat an uncertain attempt with the same key and the same body, and throw PhysicalPosOutcomeUnknownError (PHP: PhysicalPosOutcomeUnknownException) if the outcome is still uncertain. They reject a field that looks like card data before anything is sent. → Node.js SDK · PHP SDK
  • The amount is always a string in the minor unit: "4500" = 45.00 TRY. A JSON number (4500) is rejected. → Payment Flow › Amounts

Fields

FieldTypeRequiredDescription
operationstringYesSALE (sale). Other values: PREAUTH_OPEN (pre-authorisation) and REFUND_UNMATCHED (unmatched refund).
targetobjectYesThe target device; exactly one of the forms below. → Target device
amountMinorstringYesAmount in the minor unit (kuruş for TRY); a canonical positive integer string such as "4500".
currencystringYesISO 4217 code (TRY). The device and the bank row must support this currency.
merchantReferencestring | nullNo, recommendedYour own order or receipt number: printable ASCII without spaces, at most 128 characters. A second safeguard against charging the same sale twice. → merchantReference
installmentCountinteger | nullNoNumber of instalments, 2–36; SALE only. Not sent, null or 0 means a single payment. The device model's limit applies.
startTimeoutSecondsintegerNoTime for the payment to start on the device, 5–30 seconds. Not sent or 0 means 30. If the device model's limit is shorter, that limit applies.
terminalAcquirerIdstring (UUID) | nullNoThe bank row the payment goes through. If not sent, the device chooses the bank. → Bank row
itemsarrayNoSale items; SALE only. → Sale with items
allowDuplicateReferencebooleanNoWhen true, the duplicate reference checks are skipped. Default false. → Warning
instrumentstringNoPayment instrument; only CARD is valid for a payment started from the API. CARD when not sent.
  • An undeclared field in the body gets 400 VALIDATION_ERROR. organizationId, merchantId and environment are not sent; your signed key decides the organization and the environment.
  • The rules and error codes of every field: Payments › Starting a payment.

Target device

FormWhen
{ "deviceId": "…" }Recommended. The id from the device list.
{ "externalRef": "…" }When you gave your own identifier as externalRef while registering the device.
{ "vendorCode": "…", "serialNumber": "…" }When you know the device by its vendor code and serial number; the two fields are sent together.

No target or more than one target gets 400 physical_pos.payment.target_invalid (details.reason: none or multiple). A device that is not found, belongs to another organization or the other environment, or is retired gets the same answer: 404 physical_pos.device.not_found. Targeting by store, register or terminal id is not possible. → Payments › Target device

merchantReference and a new sale with the same reference

merchantReference is the order or receipt number in your own system. When you start a new sale (SALE) with the same reference, two checks are made:

SituationResult
A sale with the same reference and an outcome not yet final (NOT_STARTED, IN_PROGRESS, UNKNOWN, MANUAL_REVIEW) exists within the last 30 days409 physical_pos.payment.previous_outcome_unknown, details.previousPaymentId
An APPROVED sale with the same reference exists within a short time (10 minutes by default)409 physical_pos.payment.duplicate_reference_recent, details.previousPaymentId
  • The check runs across devices: a sale started with the same reference on another device is caught too.
  • allowDuplicateReference: true skips both checks. Use it only when you deliberately take a second payment with the same reference.
  • The rule does not apply to reversals or other operations.
  • You can read the earlier payment with details.previousPaymentId or find it with the merchantReference filter of the list.
⚠️

Always use the same merchantReference for the same sale. Do not change the reference across the attempts of one sale (a retry after a network error, restarting while the device is busy); the check only works this way.

Do not use allowDuplicateReference when you get previous_outcome_unknown. The earlier payment's outcome is not known and money may have been taken; wait for the earlier payment's outcome.

No card data

The card is read on the device; the API does not take card numbers, expiry dates, security codes or magnetic stripe data.

  • If the body or the query string contains a field name that looks like card data (such as pan, cardNumber, cvv, expiry, track2), the request gets 400 physical_pos.payment.card_data_rejected.
  • A value that looks like a card number in a free-text field (merchantReference, the item name items[].name, items[].taxGroupCode) gets the same code.
  • details.field gives only the path of the field (e.g. items[1].name); the value you sent is not written to the response, records or webhooks.
  • A 13- or 14-digit barcode with a valid check digit in an item name is not treated as a card number. → Items › Barcode

In responses, card details appear only as the masked number (cardMasked: first 6 and last 4 digits, or the last 4 digits only), the card brand and the entry mode.

Sale with items

To start a sale with product lines, send the items array. Items come back with their tax breakdown when the payment is read, and they allow item-based refunds.

{
  "operation": "SALE",
  "target": { "deviceId": "00000000-0000-0000-0000-000000000401" },
  "amountMinor": "4500",
  "currency": "TRY",
  "merchantReference": "ORD-2026-000124",
  "items": [
    { "lineNo": 1, "name": "Tea", "quantityMilli": 2000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV10", "lineTotalMinor": "3000", "barcode": "8690000000005" },
    { "lineNo": 2, "name": "Simit", "quantityMilli": 1000, "unitCode": "C62", "unitPriceMinor": "1500", "taxGroupCode": "KDV1", "lineTotalMinor": "1500" }
  ]
}
  1. Send items only on SALE; at most 500 lines. For a sale without items, do not send the field at all; an empty array is rejected.
  2. lineNo starts at 1 and increases without gaps.
  3. quantityMilli is quantity × 1000: 1 piece = 1000, 1.5 kg = 1500.
  4. unitPriceMinor is the unit price including all taxes. You do not send tax amounts; tax is calculated from taxGroupCode.
  5. lineTotalMinor = quantityMilli × unitPriceMinor / 1000, rounded half up, and must match exactly.
  6. The sum of the lines' lineTotalMinor must equal amountMinor.

If a rule is broken the request gets 400 physical_pos.fiscal_document.items_invalid; details.field gives the dotted path of the field (such as items.0.quantityMilli) and details.reason the reason. An unknown tax group gets 422 physical_pos.fiscal_document.unsupported (tax_group_unsupported). Tax groups, unit codes and the item view: Items and Item Refunds.

Step 3 — Understand the response

The response says the payment was accepted, not that it was paid. The card has not been read yet; the outcome arrives asynchronously.

HTTPdata.replayedMeaning
202 AcceptedfalseA new payment was opened; paymentStatus: "NOT_STARTED". The command is sent to the device.
200 OKtrueThis body was already sent with this key; no new payment was opened. The payment comes back in its current state: the status may be other than NOT_STARTED, e.g. APPROVED.
{
  "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"
}

Fields to store at this step:

FieldWhy
paymentIdTo read the payment, match the webhook to your order, and for cancellation and reversals.
paymentStatusWhere the payment stands in terms of money; base your decisions on this field only.
expiresAtThe last moment for the payment to start on the device. If it does not start in time, the payment becomes EXPIRED.
resultDeadlineAtThe last moment the outcome is expected. If no outcome arrives, the payment becomes UNKNOWN.
historySeqTo check the order of webhooks. → Ordering and duplicates

Even for a sale with items, items is an empty array in the start response; you read the items with GET /payments/{paymentId}. Every field of the payment object: Payments › Payment object.

Statuses. The payment goes from NOT_STARTED through IN_PROGRESS (the device is waiting for the card or the bank's answer) to one of its final statuses:

Final statusMoney
APPROVEDTaken.
PARTIALLY_APPROVEDLess than requested was taken; the amount taken is approvedAmountMinor.
DECLINED, CANCELLED, EXPIRED, FAILEDNot taken.

UNKNOWN and MANUAL_REVIEW are not final statuses: money may have been taken. → If the outcome is uncertain. All statuses and statusReason values: Payment Flow › Payment statuses.

Step 4 — Get the outcome

By webhook (recommended)

  1. In the panel, on the Webhooks page, create an endpoint for the Physical POS product and subscribe it to the physical_pos.* events. → Webhook Setup
  2. Verify the delivery's signature over the raw body, before parsing it. → Webhook Events › Signature verification
  3. Match the event to your payment with data.paymentId and to your order with data.merchantReference.
  4. Update the order according to data.paymentStatus:
EventWhat to do
physical_pos.payment.approvedComplete the sale. A partial approval arrives as partially_approved; the amount taken is approvedAmountMinor.
physical_pos.payment.declined, .cancelled, .expired, .failedNo money was taken. To take the payment with another card, you can start a new payment (new Idempotency-Key).
physical_pos.payment.unknown, .manual_reviewDo not charge again. → If the outcome is uncertain
  • No webhook is sent when the payment is started or starts on the device (NOT_STARTED, IN_PROGRESS).
  • The same event can arrive more than once; deduplicate with id. Order is not guaranteed; ignore an event whose data.historySeq is lower than the one you have.
  • The webhook does not carry the bank's authorisation code, the RRN or the items; read the payment for these.

The event list and payload fields: Webhook Events.

By polling

If you cannot receive webhooks, or you doubt a webhook, read the payment:

source lunixi-sign.sh
REQ_PATH="/api/v1/physical-pos/payments/01900000-0000-7000-8000-000000000501"
lunixi_sign GET "$REQ_PATH"
 
curl "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "X-Signature: $SIGNATURE"

Node: await lunixi.physicalPos.getPayment(paymentId) · PHP: $lunixi->physicalPos()->getPayment($paymentId) · Python: lunixi.physical_pos().get_payment(payment_id) · Java: lunixi.physicalPos().getPayment(paymentId)

  • Read at short intervals (e.g. every 2 seconds) until the payment reaches a final status. Payment reads are not rate limited.
  • The outcome is expected until resultDeadlineAt. If no outcome has arrived by then, the payment becomes UNKNOWN; keep reading less often.
  • A timeout is not a failure: a payment whose outcome deadline passes becomes UNKNOWN, not DECLINED.

Timings

TimingValue
Start time (expiresAt)startTimeoutSeconds: 5–30 seconds, default 30. If the payment does not start on the device in this time, it becomes EXPIRED.
Outcome deadline (resultDeadlineAt)At most 180 seconds after expiresAt; can be shorter depending on the device model. The exact moment is in the payment's resultDeadlineAt field.
Uncertain outcome hold10 minutes by default; the device takes no new payment during it.

All timings: Payment Flow › Timings.

If the outcome is uncertain

🚫

NEVER start a new payment for the same sale with a new Idempotency-Key. While the outcome is uncertain, money may have been taken; a new key can charge your customer twice. Lunixi never charges an uncertain payment again automatically.

SituationWhat to do
You got no answer to the start request (timeout, dropped connection, 5xx) or the SDK threw PhysicalPosOutcomeUnknownError / PhysicalPosOutcomeUnknownExceptionRepeat the request with the same Idempotency-Key and the same body. If the payment was opened, its current state comes back with 200, replayed: true; if not, it is opened now. You can also find the payment with GET /payments?merchantReference=….
The payment is UNKNOWN (physical_pos.payment.unknown)Wait. The outcome is verified automatically; once settled, the payment moves to its final status and a webhook is sent. During this time (10 minutes by default) the device takes no new payment: 409 physical_pos.payment.device_busy (unknown_outcome_hold).
The payment is MANUAL_REVIEW (physical_pos.payment.manual_review)Resolve the payment in the panel with evidence (such as a bank statement, an end-of-day report or the device receipt). There is no API endpoint for this. The device can take payments again.
A new sale with the same reference got 409 physical_pos.payment.previous_outcome_unknownThe earlier payment (details.previousPaymentId) is not settled. Wait for its outcome; do not send allowDuplicateReference: true.

Retries

ErrorWhat to do
409 physical_pos.payment.device_busy, 409 physical_pos.payment.device_not_payable (pairing_hold)Wait details.retryAfterSeconds and retry with the same Idempotency-Key.
409 physical_pos.payment.device_offlineStart it again when the device is ready for payment; the payment is not queued. No record was opened, so you can use the same Idempotency-Key. → Device readiness
503 physical_pos.presence.unavailableThe device's status cannot be verified at the moment. Retry with the same Idempotency-Key, with backoff and a limited number of attempts (e.g. at most 5, waiting 1, 2, 4 and 8 seconds); if it persists, contact support.
503 physical_pos.signing.unavailable, 503 physical_pos.service.busy, 503 physical_pos.service.clock_skew, other 5xx and timeoutsRetry with the same Idempotency-Key, with backoff and a limited number of attempts (e.g. at most 5, waiting 1, 2, 4 and 8 seconds); if it persists, contact support.

Other 4xx errors are not fixed by retrying; fix the request.

Rate limits

Payment writes (start, reverse and cancel) are limited to 120 requests per 60 seconds per organization and API key; the three endpoints share one counter. Payment reads, transactions, reports and end-of-day records are not limited.

Over the limit the request gets 429 RATE_LIMITED; the Retry-After header and details.retryAfterSeconds give the seconds to wait. Limits of the management endpoints: Common Rules › Rate limits.

Common errors and fixes

ErrorCauseFix
400 physical_pos.payment.card_data_rejectedA field name that looks like card data in the body, or a value that looks like a card number in free text.Remove or fix the field in details.field. → Card data
400 physical_pos.payment.amount_invalidThe amount is a JSON number, zero or a non-canonical string.Send the amount as a string such as "4500".
400 physical_pos.payment.target_invalid · 400 physical_pos.fiscal_document.items_invalidA nested field (target.*, items.N.*) is missing, has the wrong type or breaks a rule.details.field gives the dotted path (such as items.0.quantityMilli), details.reason the reason. The response returns the first error; fix it and send again.
400 physical_pos.idempotency.key_requiredNo Idempotency-Key header.Send a new UUID for every payment. → Idempotency-Key
403 physical_pos.environment.test_key_read_onlyThe payment was started with a test key.Use a live key.
409 physical_pos.payment.device_offlineThe device is not ready for payment (presence.decision: "NOT_READY_DEVICE").Check that the device is on, connected to the network and that the Lunixi app is running; the reason is in presence.notReadyReason. → Step 1
503 physical_pos.presence.unavailableThe device's status cannot be verified at the moment (UNVERIFIABLE); the cause is not on your device.Retry with the same key, with backoff. → Retries
409 physical_pos.payment.device_busyA payment, an uncertain outcome hold or an end-of-day is running on the device.Retry with the same key after details.retryAfterSeconds.
409 physical_pos.payment.device_not_payable · 409 physical_pos.payment.terminal_not_payableThe device or the terminal is not active or not verified, or the device is not linked to a terminal.Check details.reason. → Device and terminal
422 physical_pos.payment.operation_unsupportedcapability_undefined: no payment capability definition for the device model. channel_unset: no communication channel is set.Check details.reason; no payment record is created.
409 physical_pos.payment.previous_outcome_unknownAn earlier sale with the same reference is not settled.Wait for the earlier payment's outcome; do not use allowDuplicateReference.
409 physical_pos.idempotency_mismatchThe key was used with another body or operation.Do not change the body when repeating the same payment; use a new key for a new payment.
429 RATE_LIMITEDMore than 120 payment writes in 60 seconds.Wait Retry-After. → Rate limits

All codes: Error Codes.

Next steps