API reference

İadeler

Tek bir çağrıyla, POST /v1/refunds ile iade yaparsınız. İptal (void) ile iade (refund) arasında seçim yapmazsınız: platform, kart ağının ve acquirer bankanın izin verdiği en ucuz yöntemi seçer ve hangisini kullandığını size bildirir.

{
  "payment_intent": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A",
  "amount": 2500,
  "reason": "requested_by_customer",
  "metadata": {"ticket": "SUP-4411"}
}

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}'

{
  "id": "re_01J9ZQ7B2C4D6F8H1K3M5P7R9T",
  "object": "refund",
  "amount": 2500,
  "amount_returned_to_card": 2500,
  "currency": "try",
  "payment_intent": "pi_01J9ZQ4V8K2M3N5P7R9T1W3Y5A",
  "status": "succeeded",
  "method": "partial_void",
  "scheduled_for": null,
  "reason": "requested_by_customer",
  "failure_reason": null,
  "metadata": {"ticket": "SUP-4411"},
  "created": 1790000600
}

Platform bunu nasıl yürütür

Türk acquirer'lar birbirinden farklıdır: çoğu yalnızca gün sonu kesim saatinden önce tutarın tamamının iptaline izin verir, birçoğu o günün batch'i kapanana kadar iadeyi reddeder ve bazıları aynı gün satışın bir kısmını iptal edebilir. Platform her acquirer'ın yeteneklerini bilir ve seçimi yapar. İadenin method alanı sonucu gösterir:

method Ne zaman Sizin için anlamı
void Capture edilen tutarın tamamı, daha önce iade yok, kesim saatinden önce aynı iş günü, para henüz bakiyenize aktarılmamış. Satış iptal edilir. Müşteri genellikle hiç tahsilat görmez. Bakiyenizden hiçbir şey düşülmez ve bakiye kontrolü yapılmaz. Ödeme canceled olur.
partial_void Satışın bir kısmı, kesim saatinden önce aynı iş günü, kısmi iptali destekleyen bir acquirer'da. Satış tutarı düşürülür. Bakiyenizden tahsil edilmez.
refund Diğer her durum: sonraki günler veya kısmi iptal desteği olmayan bir acquirer. Bankada normal bir iade. Kullanılabilir bakiyenize karşı kontrol edilir ve tutar işlenirken bloke edilir.
external API dışında yapılan ve platform tarafından kaydedilen bir iade. Bilgilendirme amaçlıdır.

Bir ödemede herhangi bir kısmi iade veya iptal varsa, sonradan tam bir void artık mümkün değildir; kalan tutar partial_void veya refund olarak iade edilir.

Ertelenmiş iadeler

Bazı bankalar, aynı günkü bir satışın iadesini gün sonu batch'leri kapanana kadar reddeder. Bu durumda platform isteğinizi hemen kabul eder, tutarı bakiyenizde bloke eder ve izin verildiğinde bankaya gönderir. İade bu durumda status: processing olur ve scheduled_for alanı, gönderileceği unix zamanını (bu zamanda veya sonrasında) içerir. İade gönderildiğinde ilerler (refund.updated, ardından refund.succeeded) ve scheduled_for değeri null olur. Sizin bir şey yapmanız gerekmez; yalnızca aynı iadeyi yeniden başlatmayın.

Fonlar ve onay

Bir refund kullanılabilir bakiye gerektirir: bakiye çok düşükse çağrı 402 insufficient_available_balance (balance_error) ile başarısız olur. Void ve partial void için fon gerekmez. Hesabınız iade onayı gerektiriyorsa iade pending_approval olarak başlar ve yöntem, onaylandığında yeniden belirlenir.

Komisyon

Başarılı bir iade fees taşır: pf_fee_refunded ve fee_tax_refunded (iade edilen komisyon ve vergisi; yalnızca hesabınızın iade komisyon politikası refund ise), installment_surcharge_refunded (iadeyle karta dönen taksit farkı), fee_retained_on_void (bir iptalde platformun tuttuğu komisyon) ve merchant_debit (bakiyenizden düşen tutar: tutar − iade edilen komisyon). Ödemenin fees.refunded alanı bunların toplamıdır, fees.net_after_refunds ise size kalan net tutardır. GET /v1/balance_transactions içinde iade edilen komisyon, negatif fee ile bir refund_fee_return hareketidir.

Durumlar ve olaylar

status şunlardan biridir: pending_approval, processing, succeeded, failed (failure_reason ile) veya canceled. refund.created, refund.updated, refund.succeeded ve refund.failed olaylarına abone olun (webhook kılavuzuna bakın). İadeleri GET /v1/refunds ile listeleyin ve payment_intent, status ve method ile filtreleyin.

Kontrol listesi