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.
- 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ıcaDigest. 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 anahtar403 PRODUCT_NOT_ENABLED, kapsamı olmayan anahtar403 API_INSUFFICIENT_SCOPEalı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öntem | Yol | Kapsam |
|---|---|---|
POST | /api/v1/physical-pos/payments | physical_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:paymentsile ç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_onlyalı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
POST /api/v1/physical-pos/payments · Idempotency-Key zorunlu
Satış, ön provizyon ya da eşleşmesiz iade başlatır.
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
operation | string | Evet | SALE (satış), PREAUTH_OPEN (ön provizyon) ya da REFUND_UNMATCHED (eşleşmesiz iade). Büyük/küçük harf fark etmez. |
target | object | Evet | Hedef cihaz. → Hedef cihaz |
amountMinor | string | Evet | Tutar, en küçük birimde (TRY'de kuruş); "4500" gibi kanonik pozitif tam sayı dizesi. JSON sayıları reddedilir. |
currency | string | Evet | ISO 4217 kodu (TRY). Cihaz ve banka satırı bu para birimini desteklemelidir. |
installmentCount | integer | null | Hayır | Taksit sayısı, 2–36; yalnız SALE'de. Gönderilmez, null ya da 0 ise peşin. |
instrument | string | Hayır | Ödeme aracı: CARD ya da MEAL_CARD. Gönderilmezse CARD. → Yemek Kartıyla Satış |
interaction | string | MEAL_CARD'da | INSTRUMENT_READ (kart okutma) ya da CODE_DISPLAY (QR / kısa kod). Kartlı satışta gönderilmez. |
terminalProviderId | string (UUID) | Hayır | MEAL_CARD'da kart sağlayıcı satırı. Kartlı satışta gönderilmez. |
merchantReference | string | null | Hayır | Kendi sipariş ya da fiş numaranız: boşluksuz yazdırılabilir ASCII, en çok 128 karakter. → Aynı referansla yeni satış |
allowDuplicateReference | boolean | Hayır | true ise aynı referans denetimleri atlanır. Varsayılan false. |
startTimeoutSeconds | integer | Hayı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. |
terminalAcquirerId | string (UUID) | null | Hayır | Banka satırı. → Banka satırı |
items | array | Hayır | Satış 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:
- Ortam alanı ve kart verisine benzeyen alan adları (
400 physical_pos.input.environment_invalid,400 physical_pos.payment.card_data_rejected). - Oran sınırı (
429 RATE_LIMITED). - 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. - Test anahtarı (
403 physical_pos.environment.test_key_read_only). Idempotency-Keybaşlığı.- Servis denetimleri:
- Alan kuralları ve alan değerlerinde kart verisi taraması.
- Aynı anahtarla yapılmış önceki istek (tekrar ya da
409 physical_pos.idempotency_mismatch). - Hedef cihaz, terminal bağı ve haberleşme kanalı.
- Cihaz modelinin ödeme yeteneği: işlem, para birimi, taksit.
- Cihazın ödemeye hazır olması (bağlantı ve cihazdaki uygulamalar).
- Banka satırı.
- 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:
| HTTP | code | Ne zaman |
|---|---|---|
400 | physical_pos.idempotency.key_required · .key_invalid | Idempotency-Key yok ya da biçim dışı. |
400 | physical_pos.payment.target_invalid | Hedef yok, birden çok ya da biçim dışı (details.reason). |
400 | physical_pos.device.vendor_unknown | Seri hedefinde bilinmeyen üretici kodu. |
400 | physical_pos.input.serial_invalid | Seri hedefinde serialNumber dize değil (invalid) ya da 128 karakteri aşıyor (too_long). |
400 | VALIDATION_ERROR | Tanımlanmamış alan (target ve kalem nesnelerinin içindekiler dahil); operation, instrument ya da allowDuplicateReference türü yanlış. details.errors[].field alanın yolunu verir. |
400 | physical_pos.payment.amount_invalid | Tutar yok, sıfır veya negatif, JSON sayısı, kanonik olmayan tam sayı dizesi ya da desteklenen aralığın dışında. |
400 | physical_pos.payment.currency_unsupported | Para 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). |
400 | physical_pos.payment.installment_unsupported | Taksit aralık dışı, SALE dışında (details.reason: operation) ya da cihaz modelinin sınırının üstünde (capability). |
400 | physical_pos.input.ref_invalid | merchantReference biçim dışı. |
400 | physical_pos.payment.card_data_rejected | Gövdede kart verisi. → Kart verisi |
400 | physical_pos.validation.invalid | startTimeoutSeconds ya da terminalAcquirerId biçim dışı (details.field). |
400 | physical_pos.fiscal_document.items_invalid | Kalem kurallarından biri bozuk. → Kalemler |
400 | physical_pos.input.environment_invalid | İstekte environment. |
403 | physical_pos.environment.test_key_read_only | Test anahtarı. |
403 | physical_pos.auth.api_key_not_allowed | Eşleşmesiz iade yalnız panelden yapılacak biçimde ayarlı. |
404 | physical_pos.device.not_found | Hedef cihaz yok. |
409 | physical_pos.payment.device_busy | Cihazda yürüyen ödeme, belirsiz sonuç bekletmesi ya da gün sonu var. → Tek aktif ödeme |
409 | physical_pos.payment.device_offline | Cihaz ödemeye hazır değil: bağlı değil ya da cihazdaki uygulamalardan biri hazır değil. → Cihazın ödemeye hazır olması |
409 | physical_pos.payment.device_not_payable · .terminal_not_payable | Cihaz ya da terminal ödeme almaya hazır değil (details.reason). |
409 | physical_pos.payment.previous_outcome_unknown · .duplicate_reference_recent | Aynı referanslı önceki satış. → Referans tekrarı |
409 | physical_pos.idempotency_mismatch | Anahtar başka bir istekle kullanılmış. |
422 | physical_pos.payment.operation_unsupported | İşlem bu cihazda, kanalda ya da ayarlarınızda desteklenmiyor (details.reason; aşağıya bakın). |
422 | physical_pos.payment.unmatched_refund_limit_exceeded | Eşleşmesiz iade tavanı aşılıyor. |
422 | physical_pos.payment.identity_required | SoftPOS ya da uygulamayla bağlanan cihazda uygulama kimlik doğrulaması kapalı ya da uygun anahtar seçili değil (details.reason). → Uygulama kimliği |
422 | physical_pos.fiscal_document.unsupported | Kalemdeki vergi grubu tanınmıyor (details.reason: tax_group_unsupported). |
429 | RATE_LIMITED | Oran sınırı. → Oran sınırı |
503 | physical_pos.presence.unavailable · physical_pos.signing.unavailable · physical_pos.service.busy · physical_pos.service.clock_skew | Geç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.reason | Anlamı |
|---|---|
operation_not_root | operation bu uçta kullanılamaz (ters işlemler için ters işlem ucu). |
instrument_unsupported | instrument 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_unsupported | items yalnız SALE'de gönderilir. |
channel_unset | Cihazın haberleşme kanalı tanımlı değil. |
capability_undefined | Cihaz modelinin ödeme yetenek tanımı yok. |
capability_invalid | Cihaz modelinin yetenek tanımı kullanılamıyor. |
operation_not_supported, capability | Cihaz modeli bu işlemi desteklemiyor. |
disabled_by_setting | Eşleşmesiz iade hesap ayarlarınızda kapalı. |
terminal_acquirer_not_eligible | terminalAcquirerId 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şlemde400 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
installmentCountalanında döner; peşin satıştanull.
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.
- Onaylanan satışı geri almak için: gün sonundan önce İptal (Void), sonra İade.
- Sonuç belirsiz kalırsa satışı yeniden başlatmayın: Sonucu Belirsiz Ödeme.
- Satışı ürün satırlarıyla göndermek için: Satış Kalemleri.