Physical POS
Payment Operations
Sale (Charge a Card)

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.

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. 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.

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.

MethodPathScope
POST/api/v1/physical-pos/paymentsphysical_pos:payments
  • This endpoint also starts pre-authorisations and unmatched refunds; for those see Pre-authorisation · Unmatched Refund.

  • Payments are asynchronous: 202 means "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:manage cannot 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

Payment start sequenceYour server starts the payment and gets 202; Lunixi sends a signed command to the device; the device reads the card, gets an authorisation from the bank and reports the result to Lunixi; Lunixi sends the result to your server by webhook.POST /payments202 NOT_STARTEDSIGNED COMMANDCARDAPPROVE / DECLINERESULTWEBHOOKYour serverLunixiPOS deviceBank202 means "accepted", not "paid".
Dashed lines are responses. Get the outcome by webhook; if you do not want to wait, retrieve the payment.

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

Starts a sale, a pre-authorisation or an unmatched refund.

FieldTypeRequiredDescription
operationstringYesSALE, PREAUTH_OPEN (pre-authorisation) or REFUND_UNMATCHED (unmatched refund). Case-insensitive.
targetobjectYesTarget device. → Target device
amountMinorstringYesAmount in minor units (kuruş for TRY); a canonical positive integer string, such as "4500". JSON numbers are rejected.
currencystringYesISO 4217 code (TRY). The device and the bank row must support this currency.
installmentCountinteger | nullNoInstallment count, 2–36; SALE only. Omitted, null or 0 means a single payment.
instrumentstringNoPayment instrument: CARD or MEAL_CARD. Defaults to CARD. → Meal Card Sale
interactionstringFor MEAL_CARDINSTRUMENT_READ (card read) or CODE_DISPLAY (QR / short code). Not sent on a card sale.
terminalProviderIdstring (UUID)NoFor MEAL_CARD, the card provider row. Not sent on a card sale.
merchantReferencestring | nullNoYour order or receipt number: printable ASCII without spaces, at most 128 characters. → A new sale with the same reference
allowDuplicateReferencebooleanNoWhen true, the duplicate reference checks are skipped. Default false.
startTimeoutSecondsintegerNoTime 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.
terminalAcquirerIdstring (UUID) | nullNoBank row. → Bank row
itemsarrayNoSale 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:

  1. The environment field and field names that look like card data (400 physical_pos.input.environment_invalid, 400 physical_pos.payment.card_data_rejected).
  2. Rate limit (429 RATE_LIMITED).
  3. Field types and limits (typed codes for amount, currency, installments, reference, start time, target and item fields; 400 VALIDATION_ERROR for undefined fields and other type errors). If there is more than one error, the response returns the first typed error.
  4. Test key (403 physical_pos.environment.test_key_read_only).
  5. Idempotency-Key header.
  6. Service checks:
    1. Field rules and the card data scan of field values.
    2. An earlier request with the same key (a repeat or 409 physical_pos.idempotency_mismatch).
    3. Target device, terminal link and communication channel.
    4. The device model's payment capability: operation, currency, installments.
    5. The device being ready for payment (connection and the apps on the device).
    6. Bank row.
    7. 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:

HTTPcodeWhen
400physical_pos.idempotency.key_required · .key_invalidIdempotency-Key missing or malformed.
400physical_pos.payment.target_invalidTarget missing, multiple or malformed (details.reason).
400physical_pos.device.vendor_unknownUnknown vendor code in a serial target.
400physical_pos.input.serial_invalidIn a serial target, serialNumber is not a string (invalid) or longer than 128 characters (too_long).
400VALIDATION_ERRORUndefined field (including fields inside target and the item objects); wrong type of operation, instrument or allowDuplicateReference. details.errors[].field gives the field's path.
400physical_pos.payment.amount_invalidAmount missing, zero or negative, a JSON number, a noncanonical integer string or outside the supported range.
400physical_pos.payment.currency_unsupportedCurrency 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).
400physical_pos.payment.installment_unsupportedInstallments out of range, outside SALE (details.reason: operation) or above the device model's limit (capability).
400physical_pos.input.ref_invalidmerchantReference malformed.
400physical_pos.payment.card_data_rejectedCard data in the body. → Card data
400physical_pos.validation.invalidstartTimeoutSeconds or terminalAcquirerId malformed (details.field).
400physical_pos.fiscal_document.items_invalidAn item rule is broken. → Items
400physical_pos.input.environment_invalidenvironment in the request.
403physical_pos.environment.test_key_read_onlyTest key.
403physical_pos.auth.api_key_not_allowedUnmatched refunds are set to the panel only.
404physical_pos.device.not_foundTarget device not found.
409physical_pos.payment.device_busyA payment, an uncertain outcome hold or an end-of-day is running on the device. → One active payment
409physical_pos.payment.device_offlineThe device is not ready for payment: not connected, or one of the apps on the device is not ready. → Device readiness
409physical_pos.payment.device_not_payable · .terminal_not_payableThe device or the terminal is not ready to take payments (details.reason).
409physical_pos.payment.previous_outcome_unknown · .duplicate_reference_recentAn earlier sale with the same reference. → Duplicate reference
409physical_pos.idempotency_mismatchThe key was used with another request.
422physical_pos.payment.operation_unsupportedThe operation is not supported on this device, channel or by your settings (details.reason; see below).
422physical_pos.payment.unmatched_refund_limit_exceededThe unmatched refund limit would be exceeded.
422physical_pos.payment.identity_requiredOn a SoftPOS device or a device connected through an app, app identity is disabled or no suitable key is selected (details.reason). → App identity
422physical_pos.fiscal_document.unsupportedAn item's tax group is not recognised (details.reason: tax_group_unsupported).
429RATE_LIMITEDRate limit. → Rate limits
503physical_pos.presence.unavailable · physical_pos.signing.unavailable · physical_pos.service.busy · physical_pos.service.clock_skewTemporary; 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.reasonMeaning
operation_not_rootoperation cannot be used on this endpoint (for reversals use the reversal endpoint).
instrument_unsupportedinstrument 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_unsupporteditems is sent only on SALE.
channel_unsetThe device's communication channel is not set.
capability_undefinedThe device model has no payment capability definition.
capability_invalidThe device model's capability definition cannot be used.
operation_not_supported, capabilityThe device model does not support this operation.
disabled_by_settingUnmatched refunds are off in your account settings.
terminal_acquirer_not_eligibleterminalAcquirerId 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 operation 400 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; null for 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.