Sağlayıcı Tahsilatı

Sağlayıcınızla anlaşmanız primi sağlayıcının tahsil etmesini öngörüyorsa prim sizin ödemenize eklenmez. Prim, sizin ödemenizden ayrı olarak sağlayıcınız tarafından çekilir. Çekimi POST /api/v1/insurance/orders/{orderId}/pay ile başlatırsınız.

• Önce sizin ödemeniz alınır. Siparişi bir Lunixi ödemesine bağladıysanız prim, o ödeme tahsil edildikten sonra çekilebilir. Sizin ödemeniz alınmadıysa sağlayıcıya ödeme gönderilmez.
• Prim ayrı bir çekimdir. Alıcı iki ayrı çekim görür: sizin ödemeniz ve sağlayıcının prim çekimi. Primin çekilememesi sizin ödemenizi etkilemez.
• Prim Lunixi ödemenizden geçmez. Prim ödeme kaydınıza ve payout'unuza girmez; sağlayıcıya doğrudan ödenir.
• Poliçe, prim çekildikten sonra otomatik olarak istenir. issue-policy çağırmanız gerekmez.

Bu yol yalnızca API yolunda kullanılır. Checkout Form'da yalnızca primi sizin tahsil ettiğiniz ürünler sunulur.

Başlamadan önce

• Panelde POS Merkezi > Sigorta sayfasında, bağlantınızdaki üründe Primi kim tahsil ediyor sorusunu Sağlayıcı tahsil eder olarak seçin: Sağlayıcı Bağlantısı › Bağlantıdaki ürünler. Liste yalnızca ürünün desteklediği biçimleri gösterir.
• Bu ürünün teklif seçeneklerinde ve siparişlerinde premiumCollectedBy değeri PROVIDER'dır.
• Sağlayıcının ürünü primi iki biçimden biriyle çeker:

Akış

Prim çekimi: POST /api/v1/insurance/orders/{orderId}/pay

Kimlik doğrulama

Bu uç kart verisi taşıyabildiği için doğrudan ödeme uçlarıyla aynı kimlik kuralını uygular: Bearer erişim token'ı ve Ed25519 istek imzası birlikte (Step-Up). Diğer sigorta uçlarından farklı olarak Authorization başlığı zorunludur.

Erişim token'ının alınması ve Step-Up kuralları: Kimlik Doğrulama. Token ile imza anahtarı aynı hesaba ve aynı ortama ait olmalıdır.

İstek

source lunixi-sign.sh
REQ_PATH="/api/v1/insurance/orders/<orderId>/pay"
BODY='{"card":{"cardNumber":"<kart numarası>","expireMonth":"<AA>","expireYear":"<YYYY>","cvcNumber":"<güvenlik kodu>","cardHolderName":"<kart sahibi>"},"returnUrl":"https://example.com/insurance/return"}'
lunixi_sign POST "$REQ_PATH" "$BODY"
 
curl -X POST "https://api-gateway.lunixi.com$REQ_PATH" \
  -H "Authorization: Bearer $LUNIXI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: insurance-pay-1001" \
  -H "X-Key-Id: $LUNIXI_KEY_ID" \
  -H "X-Date: $DATE" \
  -H "X-Nonce: $NONCE" \
  -H "Digest: $DIGEST" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Ürün sağlayıcının ödeme sayfasında çekiyorsa (HOSTED) gövde yalnızca returnUrl taşır.

Kart bilgisi

• Hesabınız PCI-DSS sertifikalı olarak tanımlı değilse kartlı üründe istek, kart işlenmeden 403 insurance.card.pci_required döner; sağlayıcıya istek gitmez.
• Kart Lunixi'de saklanmaz. Yalnızca istek sırasında işlenir ve sağlayıcınıza iletilir. Güvenlik kodu hiçbir yerde tutulmaz.
• Kart bilgisi yanıtlara, hata iletilerine, istek kayıtlarına ve webhook'lara girmez. Hata yanıtında yalnızca hangi alanın geçersiz olduğu döner.
• Kart biçimi geçersizse (ör. kart numarası doğrulamadan geçmiyor ya da kartın süresi dolmuş) istek 422 insurance.card.invalid döner; geçersiz alan details.field alanındadır. Sağlayıcıya istek gitmez.

Yanıt

İstek tamamlandığında 200 döner. data iki nesne taşır:

providerPayment:

Yanıtta sağlayıcının referansları, ödeme sayfasının adresi ve hata kodları bulunmaz. Kart bilgisi yanıtta hiçbir biçimde yer almaz.

Sonuçlar

• Bir siparişte aynı anda tek bir açık deneme bulunur. Açık (PENDING, ACTION_REQUIRED, UNKNOWN) ya da başarılı bir deneme varken yeni deneme başlatılamaz; aynı karta ikinci çekim yapılmaz.
• İstek sağlayıcıya ulaşmadan düşerse (ör. sağlayıcıya ulaşılamıyor) para hareket etmez: hata yanıtı döner ve sipariş önceki tahsilat durumuna geri döner. İsteği bir süre sonra tekrarlayabilirsiniz.

Tekrar ve Idempotency-Key

• Prim çekimi teklifin sağlayıcıya iletilmesini ve çekimi aynı istekte yapar. İstek bir dakikadan uzun sürebilir; istemcinizin zaman aşımını buna göre ayarlayın.
• Zaman aşımı ya da 5xx sonrasında isteği aynı Idempotency-Key ve aynı gövdeyle tekrarlayın. Aynı anahtar aynı denemeyi döner; kart yeniden işlenmez ve ikinci çekim yapılmaz.
• Yeni bir deneme (ör. reddedilen çekimden sonra başka bir kart) için yeni bir anahtar üretin.

Alıcının adımı (nextAction)

Sağlayıcı çekim için alıcının bir adım atmasını isterse (3D Secure doğrulaması ya da sağlayıcının ödeme sayfası) deneme ACTION_REQUIRED olur ve nextAction döner. Aynı nesne, adım beklendiği sürece siparişin nextAction alanında da bulunur.

• redirectUrl bir Lunixi adresidir (/api/v1/insurance/payments/{insurancePaymentId}/redirect). Lunixi alıcıyı buradan sağlayıcının sayfasına yönlendirir; sağlayıcının sayfa adresi size iletilmez.
• Adresi yalnızca alıcının tarayıcısında açın. Dönüş işlendikten sonra ya da deneme artık alıcının adımını beklemiyorsa adres 404 insurance.payment.not_found döner.
• Alıcı expiresAt anına kadar dönmezse sonuç sağlayıcıdan doğrulanır.

Dönüş

Alıcı sağlayıcının sayfasındaki adımı tamamladığında sağlayıcı Lunixi'ye döner. Ardından:

• returnUrl gönderdiyseniz alıcı bu adrese yönlendirilir. Adrese şu sorgu parametreleri eklenir: insurancePaymentId, orderId, status.
• returnUrl göndermediyseniz alıcıya sonuç JSON olarak gösterilir. Alıcıyı yönlendirdiğiniz her istekte returnUrl gönderin.

Hatalar

Ortak kodlar: Akışlar › Yanıt ve hatalar.

Durum çakışması

Desteklenmeyen tahsilat

İptal ve iade

• Poliçeyi cancel ucuyla iptal edebilirsiniz: İptal ve Prim İadesi › Poliçe iptali.
• Prim sağlayıcıya ödendiği için prim iadesi Lunixi üzerinden yapılmaz; refund-premium bu siparişlerde 409 (reason: collected_by_provider) döner.
• Kendi ödemenizden yaptığınız iadeler sigortaya bağlı değildir ve poliçeyi iptal etmez.

İlgili

• Sipariş ve Ödeme Bağlama: sipariş nesnesi ve bind-payment
• Prim ve Ödeme: primi sizin tahsil ettiğiniz akışlar
• Yalnız Sigorta Entegrasyonu: Lunixi ödemesi olmadan uçtan uca akış
• Webhook Olayları: insurance.policy.issued ve insurance.policy.failed
• Hata Kodları: sağlayıcı tahsilatının kodları