Siparişler

CheckoutSession alıcının gördüğü şeyse, Order sizin önemsediğiniz şeydir. Şunların kalıcı kaydıdır:

Ne satın alındığı (line item’lar)
Ne kadar borçlu olunduğu ve gerçekte ne kadarının ödendiği
Bekleyen ve uygulanmış iadeler
Harici referansınız (external_ref) — tipik olarak kendi sipariş ID’niz, Order üzerinde saklanır ve GET /b2b/v1/orders/{id} üzerinde döndürülür (webhook payload’larında yansıtılmaz — aşağıya bakınız)

Bir siparişin kalem içermesi gerekmez: yalnızca bir tutar tahsil etmek için items yerine amount gönderin (fatura, depozito, serbest tutarlı ödeme bağlantısı). İkisinden yalnızca birini gönderin.

Bir CheckoutSession, PaymentIntent’lerinden biri tahsil edildiğinde veya TTL süresi dolduğunda ölür. Order sonsuza kadar yaşar.

Bir Order ne zaman oluşturulur

POST /b2b/v1/checkout-sessions/quick çağrısı yaptığınızda, InfraIO Pay tek bir transaction’da hem yeni bir Order hem de yeni bir CheckoutSession oluşturur. Zaten bir Order’ınız varsa ve checkout’u yeniden denemek istiyorsanız (örn. alıcı vazgeçtikten sonra), bunun yerine POST /b2b/v1/checkout-sessions kullanarak mevcut siparişe yeni bir oturum ekleyin — denetim izini koruyarak.

Yaşam döngüsü

Durum	Anlamı
`PENDING`	Bir CheckoutSession aktif ve çözümsüz.
`PAID`	Tam tutar tahsil edildi. `payment.settled` webhook’u burada tetiklenir. Karşılamak için güvenlidir.
`PARTIAL_PAID`	Para geldi ama toplamdan az. Aşağıdaki “Eksik ödeme” kısmına bakın.
`CANCELED`	Oturum süresi doldu veya satıcı iptal etti. `metadata.canceled_reason` nedeni açıklar (`payment_timeout`, `merchant_canceled`, …).
`REFUNDED`	Ödenen tutarın tamamı iade edildi.
`PARTIALLY_REFUNDED`	Bir miktar iade gerçekleşti ama bakiye ödenmiş olarak kaldı.

Sipariş karşılama mantığınızı dayandıracağınız durum PAID’dir — CheckoutSession’ın COMPLETED durumu değil. payment.settled webhook’u kanonik sinyaldir.

`external_ref` alanı

Bir oturum oluştururken external_ref’i dahil edebilirsiniz (255 karaktere kadar herhangi bir string — tipik olarak kendi sipariş ID’niz). Tüm pipeline boyunca taşınır:

Order üzerinde saklanır
Destek araması için satıcı panelinde görünür
GET /b2b/v1/orders/{id} üzerinde döndürülür, böylece bir webhook işleyici payment.settled aldıktan sonra alabilir

Webhook payload’ları external_ref içermez. Bir payment.* webhook’unu kendi kaydınıza eşlemek için payload’dan order_id’yi alın ve siparişi alın.

Eksik ödeme

Alıcının zincir üstü transferi sipariş toplamından daha az tahsil edilirse, Order PARTIAL_PAID durumuna geçer. Üç seçeneğiniz var:

Kabul edin ve çözümleyin. Siparişi PAID durumuna geçirir ve order.resolved tetiklenir. Bu, REST API üzerinden kullanılamaz; bu nedenle self-servis bir akış için seçenek 2’yi kullanın (kalanı tahsil edin).
Kalanı bekleyin. amount_due = artık olan aynı Order’a karşı yeni bir CheckoutSession oluşturun. Alıcı farkı öder; bu tahsil edildiğinde, Order PAID durumuna geçer.
İptal edin ve iade edin. Kısmi tutarı iade edin ve Order’ı iptal edin. Alıcı, herhangi bir ağ ücretinden sorumludur.

İadeler

İadeler ayrı bir API yüzeyi ve ayrı bir kavram sayfasıdır. Bkz. Kavramlar → İadeler.

API uç noktaları

Method	Path	Notlar
`POST`	`/b2b/v1/orders`	Oturumsuz bir Order oluştur (nadir)
`GET`	`/b2b/v1/orders/:order_id`	Line item’lar + ödeme geçmişi ile tam siparişi oku
`PATCH`	`/b2b/v1/orders/:order_id/cancel`	Ödenmemiş bir siparişi iptal et
`PATCH`	`/b2b/v1/orders/:order_id/reopen`	Otomatik iptal edilmiş (`payment_timeout`) bir siparişi yeniden aç

Sırada ne var

Kavramlar → Oturumlar — bir Order’ı saran alıcıya yönelik kabuk.
Kavramlar → İadeler — iade durumları ve manuel zincir üstü gönderim adımı.
Webhook’lar → Genel bakış — bir Order yaşam döngüsü sırasında tetiklenen her event.