Idempotency

Ağlar kesintiye uğrayabilir. Bir istek zaman aşımına uğradığında platformun isteği işleyip işlemediğini bilemezsiniz. Bir Idempotency-Key (idempotency anahtarı), isteği güvenle tekrarlamanızı sağlar: istek en fazla bir kez yürütülür ve her tekrar aynı yanıtı döndürür.

Her POST isteği, en fazla 255 karakterlik bir Idempotency-Key başlığı kabul eder.

curl -X POST https://pay.example.com/v1/refunds \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: refund-order-1001-1" \
  -H "Content-Type: application/json" \
  -d '{"payment_intent": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A", "amount": 2500}'

Kurallar

Anahtarlar 24 saat boyunca, her API anahtarı için ayrı ayrı saklanır.
Platform isteğin bir özetini (hash) saklar. Aynı anahtar ve aynı gövde, saklanan yanıtı (durum ve gövde) yeniden oynatır ve Idempotent-Replayed: true başlığını ekler.
Aynı anahtar ile farklı bir gövde, 409 ve error.type = idempotency_error, error.code = idempotency_conflict ile reddedilir. Bu, bir anahtarı yanlışlıkla başka bir sipariş için yeniden kullanmanızı engeller.
Tekrar isteği geldiğinde ilk istek hâlâ çalışıyorsa tekrar isteği 409 idempotency_in_progress alır. Biraz bekleyin ve aynı anahtarla yeniden deneyin.
Platformun ilk istek için ürettiği her yanıt saklanır ve yeniden oynatılır; 4xx ve 5xx yanıtları dahil. Harici bir etkiden (örneğin bir banka çağrısı) sonra başarısız olan bir istek, aynı anahtarla sessizce yeniden yürütülmez.
Aynı anahtarın farklı bir uç noktada kullanılması da 409 idempotency_conflict sonucunu verir.
Idempotency adımına ulaşmadan reddedilen istekler (401, eksik kapsam veya IP nedeniyle 403, hatalı biçimli JSON, yanlış alandaki kart numarası) anahtarı tüketmez.
GET ve DELETE istekleri doğası gereği idempotent'tir; başlık yok sayılır.

Anahtar seçimi

Anahtarı, her denemede rastgele üretilen bir değerden değil, kendi iş nedeninizden türetin: order-1001-payment, refund-order-1001-1. Böylece worker'ınız çöküp yeniden başladığında aynı anahtarla yeniden dener ve çift tahsilat yapamaz. Rastgele bir UUID'yi yalnızca sisteminizde kararlı bir tanımlayıcı yoksa kullanın ve isteği göndermeden önce siparişle birlikte saklayın.

Gerçekten yeni bir deneme için yeni bir anahtar kullanın; örneğin müşteri bir retten sonra farklı bir kartla yeniden denediğinde.

Neyi yeniden denemeli

Sonuç	Ne yapmalı
Zaman aşımı veya bağlantı sıfırlanması (yanıt alınmadı)	Aynı anahtarla yeniden deneyin.
`409 idempotency_in_progress`	Kısa bir bekleyişten sonra aynı anahtarla yeniden deneyin.
Saklanmış herhangi bir yanıt (`4xx`, `5xx`)	Aynı anahtarla tekrar, aynı yanıtı döndürür. İsteği düzeltin, ardından yeni bir anahtar kullanın.
`402` kart reddi	Başka bir ödeme yöntemi isteyin ve yeni bir anahtar kullanın.
Hiç bitmeyen `idempotency_in_progress` (işleminiz istek sırasında çöktü)	Anahtar 24 saat sonra süresi dolana kadar kilitli kalır ve otomatik olarak devralınmaz, çünkü yeniden çalıştırmak ödemeyi çoğaltabilir. Önce ödemenin durumunu kontrol edin, ardından yeni bir anahtarla yeniden deneyin.

Bir ödemenin gerçekleşip gerçekleşmediğinden emin değilseniz, yenisini oluşturmadan önce ödemeyi arayın (GET /v1/payment_intents?q=… bir id'yi, müşteri e-postasını veya açıklama önekini eşleştirir; metadata[order_id]=1001 tam eşleşme yapar) veya isteği Geliştiriciler → İstek kayıtları altında inceleyin.