Fiziksel POS
Ödeme İşlemleri
Satış (Ödeme Çekme)

Satış (Ödeme Çekme)

Fatura no, alıcı ve mali belge alanları ile yayın bekleyen satış uygulaması kaydının kapsamı: Satış verisi ve destek durumu. merchantReference, fatura numarası/doğrulaması yerine geçmez.

Bu uçları kim çağırır?Dış API (s2s)
Taban yol
/api/v1/physical-pos
Kimlik
Her istekte Ed25519 istek imzası — X-Key-Id, X-Date, X-Nonce, X-Signature; gövdeli isteklerde ayrıca Digest. Zaman penceresi ±5 dk, nonce tek kullanımlık. Bearer jetonu ya da panel oturumu bu uçlarda kabul edilmez.
Yetki
Anahtarınız Fiziksel POS ürününü (PHYSICAL_POS) ve bu sayfadaki uçların kapsamını taşımalıdır: physical_pos:payments. Ürünü olmayan anahtar 403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar 403 API_INSUFFICIENT_SCOPE alır. Bkz. Kimlik Doğrulama ve Kapsamlar.
Çapraz yüzey
Bu uçlar s2s yüzeyindedir; kendi sunucunuzdan imzalı istekle çağırırsınız. Aynı kayıtların panelde ekranları var, ama panel uçları API anahtarıyla çağrılamaz; bu uçlar da panel oturumuyla çağrılamaz.

Mağazanızdaki POS cihazında müşterinin kartından ödeme çekersiniz: peşin ya da taksitli satış. İstek cihaza iletilir, müşteri kartını cihaza okutur, banka cevabı webhook ile size gelir.

YöntemYolKapsam
POST/api/v1/physical-pos/paymentsphysical_pos:payments
  • Bu uç ön provizyon ve eşleşmesiz iade de başlatır; onlar için: Ön Provizyon · Eşleşmesiz İade.

  • Ödeme asenkrondur: 202 "ödeme kabul edildi" demektir, "ödendi" demek değildir.

  • Adım adım rehber (cihazı seçmek, anahtarı saklamak, sonucu almak): Hızlı Başlangıç.

  • Okuma uçları için iki kapsamdan biri yeterlidir. Yazma uçları yalnız physical_pos:payments ile çağrılır; physical_pos:manage ödeme işlemi yapamaz. → Kapsamlar

  • Ödemeler anahtarınızın ortamındadır. Test anahtarı ödemeleri yalnız okur; başlatma, ters işlem ve iptal istekleri 403 physical_pos.environment.test_key_read_only alır. → Ortamlar

cURL örnekleri imzayı lunixi-sign.sh ile hesaplar: Kimlik Doğrulama › İmza yardımcısı.

Ödeme başlatma ve ters işlem, hedef cihazın modeli için ödeme yetenek tanımı bulunduğunda yürür. Yetenek tanımı bulunmayan cihazda istek, cihaz bulunduktan, terminal bağı ve haberleşme kanalı denetlendikten sonra 422 physical_pos.payment.operation_unsupported (details.reason: capability_undefined) alır; ödeme kaydı oluşmaz.

İstek

Ödeme başlatma sırasıSunucunuz ödemeyi başlatır ve 202 alır; Lunixi imzalı komutu cihaza gönderir; cihaz kartı okuyup bankadan provizyon alır ve sonucu Lunixi'ye bildirir; Lunixi sonucu webhook ile sunucunuza gönderir.POST /payments202 NOT_STARTEDİMZALI KOMUTKARTONAY / RETSONUÇWEBHOOKSunucunuzLunixiPOS cihazıBanka202 "kabul edildi" demektir, "ödendi" değil.
Kesik çizgiler yanıttır. Sonucu webhook ile alın; beklemek istemezseniz ödemeyi sorgulayın.

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

Satış, ön provizyon ya da eşleşmesiz iade başlatır.

AlanTipZorunluAçıklama
operationstringEvetSALE (satış), PREAUTH_OPEN (ön provizyon) ya da REFUND_UNMATCHED (eşleşmesiz iade). Büyük/küçük harf fark etmez.
targetobjectEvetHedef cihaz. → Hedef cihaz
amountMinorstringEvetTutar, en küçük birimde (TRY'de kuruş); "4500" gibi kanonik pozitif tam sayı dizesi. JSON sayıları reddedilir.
currencystringEvetISO 4217 kodu (TRY). Cihaz ve banka satırı bu para birimini desteklemelidir.
installmentCountinteger | nullHayırTaksit sayısı, 2–36; yalnız SALE'de. Gönderilmez, null ya da 0 ise peşin.
instrumentstringHayırÖdeme aracı: CARD ya da MEAL_CARD. Gönderilmezse CARD. → Yemek Kartıyla Satış
interactionstringMEAL_CARD'daINSTRUMENT_READ (kart okutma) ya da CODE_DISPLAY (QR / kısa kod). Kartlı satışta gönderilmez.
terminalProviderIdstring (UUID)HayırMEAL_CARD'da kart sağlayıcı satırı. Kartlı satışta gönderilmez.
merchantReferencestring | nullHayırKendi sipariş ya da fiş numaranız: boşluksuz yazdırılabilir ASCII, en çok 128 karakter. → Aynı referansla yeni satış
allowDuplicateReferencebooleanHayırtrue ise aynı referans denetimleri atlanır. Varsayılan false.
startTimeoutSecondsintegerHayırÖdemenin cihazda başlaması için süre, 5–30 saniye. Gönderilmez ya da 0 ise 30. Cihaz modelinin sınırı daha kısaysa o uygulanır.
terminalAcquirerIdstring (UUID) | nullHayırBanka satırı. → Banka satırı
itemsarrayHayırSatış kalemleri; yalnız SALE'de, en çok 500 satır. Kalemlerin lineTotalMinor toplamı amountMinor'a eşit olmalıdır. Kalemsiz satışta alanı göndermeyin; boş dizi reddedilir. → Kalemler
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"

Yeni ödemede 202, aynı anahtar ve aynı gövdeyle tekrarda 200 döner:

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

Yanıt ödemenin kabul edildiğini söyler; sonucu webhook ile ya da ödemeyi okuyarak izleyin.

Denetim sırası. İmza, ürün ve kapsam denetiminden sonra istek şu sırayla denetlenir; ilk takıldığı adımın hatasını alırsınız:

  1. Ortam alanı ve kart verisine benzeyen alan adları (400 physical_pos.input.environment_invalid, 400 physical_pos.payment.card_data_rejected).
  2. Oran sınırı (429 RATE_LIMITED).
  3. Alan türleri ve sınırları (tutar, para birimi, taksit, referans, başlatma süresi, hedef ve kalem alanları için tipli kodlar; tanımlanmamış alan ve diğer tür hataları için 400 VALIDATION_ERROR). Birden çok hata varsa yanıt ilk tipli hatayı döner.
  4. Test anahtarı (403 physical_pos.environment.test_key_read_only).
  5. Idempotency-Key başlığı.
  6. Servis denetimleri:
    1. Alan kuralları ve alan değerlerinde kart verisi taraması.
    2. Aynı anahtarla yapılmış önceki istek (tekrar ya da 409 physical_pos.idempotency_mismatch).
    3. Hedef cihaz, terminal bağı ve haberleşme kanalı.
    4. Cihaz modelinin ödeme yeteneği: işlem, para birimi, taksit.
    5. Cihazın ödemeye hazır olması (bağlantı ve cihazdaki uygulamalar).
    6. Banka satırı.
    7. Cihaz ve terminalin ödeme almaya hazır olması, eşleşmesiz iade ayarları, aynı referans denetimleri ve cihazda yürüyen başka ödeme olmaması.

Örneğin biçimi bozuk gövde gönderen test anahtarı 403 değil 400 alır; oran sınırına takılan istek alan denetiminden önce 429 alır.

Hatalar:

HTTPcodeNe zaman
400physical_pos.idempotency.key_required · .key_invalidIdempotency-Key yok ya da biçim dışı.
400physical_pos.payment.target_invalidHedef yok, birden çok ya da biçim dışı (details.reason).
400physical_pos.device.vendor_unknownSeri hedefinde bilinmeyen üretici kodu.
400physical_pos.input.serial_invalidSeri hedefinde serialNumber dize değil (invalid) ya da 128 karakteri aşıyor (too_long).
400VALIDATION_ERRORTanımlanmamış alan (target ve kalem nesnelerinin içindekiler dahil); operation, instrument ya da allowDuplicateReference türü yanlış. details.errors[].field alanın yolunu verir.
400physical_pos.payment.amount_invalidTutar yok, sıfır veya negatif, JSON sayısı, kanonik olmayan tam sayı dizesi ya da desteklenen aralığın dışında.
400physical_pos.payment.currency_unsupportedPara birimi biçim dışı ya da cihaz veya banka satırı desteklemiyor (details.reason: capability). Eşleşmesiz iadede ayardaki para biriminden farklı (unmatched_refund_currency).
400physical_pos.payment.installment_unsupportedTaksit aralık dışı, SALE dışında (details.reason: operation) ya da cihaz modelinin sınırının üstünde (capability).
400physical_pos.input.ref_invalidmerchantReference biçim dışı.
400physical_pos.payment.card_data_rejectedGövdede kart verisi. → Kart verisi
400physical_pos.validation.invalidstartTimeoutSeconds ya da terminalAcquirerId biçim dışı (details.field).
400physical_pos.fiscal_document.items_invalidKalem kurallarından biri bozuk. → Kalemler
400physical_pos.input.environment_invalidİstekte environment.
403physical_pos.environment.test_key_read_onlyTest anahtarı.
403physical_pos.auth.api_key_not_allowedEşleşmesiz iade yalnız panelden yapılacak biçimde ayarlı.
404physical_pos.device.not_foundHedef cihaz yok.
409physical_pos.payment.device_busyCihazda yürüyen ödeme, belirsiz sonuç bekletmesi ya da gün sonu var. → Tek aktif ödeme
409physical_pos.payment.device_offlineCihaz ödemeye hazır değil: bağlı değil ya da cihazdaki uygulamalardan biri hazır değil. → Cihazın ödemeye hazır olması
409physical_pos.payment.device_not_payable · .terminal_not_payableCihaz ya da terminal ödeme almaya hazır değil (details.reason).
409physical_pos.payment.previous_outcome_unknown · .duplicate_reference_recentAynı referanslı önceki satış. → Referans tekrarı
409physical_pos.idempotency_mismatchAnahtar başka bir istekle kullanılmış.
422physical_pos.payment.operation_unsupportedİşlem bu cihazda, kanalda ya da ayarlarınızda desteklenmiyor (details.reason; aşağıya bakın).
422physical_pos.payment.unmatched_refund_limit_exceededEşleşmesiz iade tavanı aşılıyor.
422physical_pos.payment.identity_requiredSoftPOS ya da uygulamayla bağlanan cihazda uygulama kimlik doğrulaması kapalı ya da uygun anahtar seçili değil (details.reason). → Uygulama kimliği
422physical_pos.fiscal_document.unsupportedKalemdeki vergi grubu tanınmıyor (details.reason: tax_group_unsupported).
429RATE_LIMITEDOran sınırı. → Oran sınırı
503physical_pos.presence.unavailable · physical_pos.signing.unavailable · physical_pos.service.busy · physical_pos.service.clock_skewGeçici durum; aynı Idempotency-Key ile, geri çekilerek ve sınırlı sayıda yeniden deneyin; sürerse destekle iletişime geçin. → Yeniden deneme

physical_pos.payment.operation_unsupported için details.reason değerleri:

details.reasonAnlamı
operation_not_rootoperation bu uçta kullanılamaz (ters işlemler için ters işlem ucu).
instrument_unsupportedinstrument desteklenmiyor ya da cihaz modeli bu ödeme aracını desteklemiyor.
instrument_operation_unsupported, items_instrument_unsupported, provider_terminal_*Yemek kartı kuralları. → Yemek Kartıyla Satış
items_operation_unsupporteditems yalnız SALE'de gönderilir.
channel_unsetCihazın haberleşme kanalı tanımlı değil.
capability_undefinedCihaz modelinin ödeme yetenek tanımı yok.
capability_invalidCihaz modelinin yetenek tanımı kullanılamıyor.
operation_not_supported, capabilityCihaz modeli bu işlemi desteklemiyor.
disabled_by_settingEşleşmesiz iade hesap ayarlarınızda kapalı.
terminal_acquirer_not_eligibleterminalAcquirerId bu ödeme için uygun değil.

Taksitli satış

Taksit için installmentCount alanına taksit sayısını gönderin (2–36). Alan gönderilmez, null ya da 0 ise satış peşindir.

{"operation":"SALE","target":{"deviceId":"00000000-0000-0000-0000-000000000401"},"amountMinor":"120000","currency":"TRY","installmentCount":6,"merchantReference":"ORD-2026-000125"}
  • Taksit yalnız SALE'de kullanılır; başka işlemde 400 physical_pos.payment.installment_unsupported (details.reason: operation).
  • Cihaz modelinin taksit sınırı daha düşükse 400 physical_pos.payment.installment_unsupported (details.reason: capability).
  • Taksit sayısı ödeme nesnesinde installmentCount alanında döner; peşin satışta null.

Sonucu alma

Sonucu webhook ile alırsınız: physical_pos.payment.approved, …partially_approved, …declined, …cancelled, …expired, …failed, …unknown ya da …manual_review. Webhook beklemek istemezseniz ödemeyi sorgulayın.