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 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, payment-service 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ı
`DRAFT`	Gelecekteki bir taslak akışı için ayrılmıştır. Bugün hiçbir kod yolu `DRAFT` sipariş oluşturmaz — her sipariş `PENDING` olarak oluşturulur, bu yüzden bu durumu gözlemlemezsiniz.
`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 bugün doğrudan yansıtmaz — bu dokümanların önceki taslakları data.external_ref’in her event’e aktığını iddia ediyordu, bu yanlıştı. Bir payment.* webhook’unu kendi DB satırınıza eşlemek için, payload’dan order_id’yi alın ve siparişi alın. Webhook payload’larında yerel external_ref alanı yol haritasında.

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 herkese açık bir REST uç noktası değildir — çözümleme bugün dahili/operasyonel bir eylemdir, bu nedenle self-servis bir akış için seçenek 2’yi tercih edin (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 zincir ücretinden sorumludur.

Ürün burada bir tavsiye yapmıyor — farklı satıcılar farklı politikalar ister. Birini seçin ve admin’inize entegre edin.

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