API reference

Hatalar

Başarısız istekler 2xx dışında bir HTTP durumu ve tek bir error nesnesi içeren JSON gövde döndürür:

{
  "error": {
    "type": "card_error",
    "code": "no_eligible_terminal",
    "decline_code": "card_not_supported",
    "param": null,
    "message": "No terminal can take this card.",
    "request_id": "req_01J9ZQ4V8K2M3N5P7R9T1W3Y5F"
  }
}
Alan Anlamı
type Hatanın sınıfı; hata yönetiminizi buna göre belirleyin.
code Kararlı, makine tarafından okunabilir bir neden. null olabilir.
decline_code Kart retlerinde, ihraççı bankadan veya bankadan gelen normalize edilmiş neden.
param Varsa, hataya yol açan istek parametresi.
message Geliştiriciler için insan tarafından okunabilir bir açıklama. Kararlı değildir; ayrıştırmayın ve müşterilere göstermeyin.
request_id İsteğin kimliği. Aynı zamanda Request-Id yanıt başlığında bulunur; destek ekibine iletin ve isteği Geliştiriciler → İstek kayıtları bölümünde bulun.
payment_intent Onay sırasında oluşan bir kart hatasında, ödemenin o anki durumu.

HTTP durum kodları

HTTP Anlamı
200 Başarılı.
400 İstek geçersiz (invalid_request_error) veya bir kuralı ihlal ediyor.
401 API anahtarı eksik veya geçersiz (authentication_error).
402 İstek geçerliydi ancak gerçekleştirilemedi: kart reddi, sahtecilik reddi veya bakiye sorunu.
403 İzin verilmiyor (permission_error): kapsam, IP izin listesi, ürün, üye işyeri durumu.
404 Nesne mevcut değil veya başka bir üye işyerine ait.
409 Idempotency çakışması veya zaten bekleyen bir değişiklik.
429 İstek sınırı aşıldı. Bekleyin ve yeniden deneyin.
5xx Platformda veya bankada bir sorun. Yeniden denemeden önce ödemeyi kontrol edin (idempotency kılavuzuna bakın).

Hata türleri

error.type Anlamı
card_error Kart reddedildi veya kullanılamıyor (bkz. decline_code).
invalid_request_error İstek hatalı ya da bir kuralı ihlal ediyor; isteği düzeltin, aynen tekrar denemeyin.
api_error Platformda veya bağlı bir sistemde sorun var; aynı Idempotency-Key ile tekrar denemek güvenlidir.
idempotency_error Idempotency-Key farklı bir gövdeyle yeniden kullanıldı ya da ilk istek hâlâ çalışıyor.
authentication_error API anahtarı eksik, hatalı, iptal edilmiş veya türü uygun değil.
permission_error Anahtar veya kullanıcının bu işlem için yetkisi yok (kapsam, IP izin listesi, ürün, üye işyeri durumu).
rate_limit_error Çok fazla istek; bekleyip tekrar deneyin.
balance_error Kullanılabilir bakiyeniz işlemi karşılamıyor.
fraud_error Ödeme sahtecilik denetiminde durduruldu.

Hata kodları

Aşağıdaki tablo API sözleşmesinden üretilir ve API'nin belgelediği tüm kodları listeler. error.type hatanın sınıfından belirlenir; birkaç kod birden fazla türle görünür.

Kod HTTP Anlamı
non_secure_not_allowed 400 3-D Secure none istendi ancak hesabınız veya bu tutar için 3D'siz ödemeye izin yok.
payment_intent_unexpected_state 400 Ödeme bu çağrıya uygun durumda değil (örneğin requires_capture olmayan ödemenin capture edilmesi).
no_eligible_terminal 402 (card_error) Bu kartı veya ödemeyi alabilecek bir terminal yok; tahsilat yapılmadı.
installments_not_available 402 (card_error) İstenen taksit sayısını bu kart için çalıştıran terminal yok. Önce taksit önizlemesini çağırın.
insufficient_available_balance 402 (balance_error) Kullanılabilir bakiye yetersiz (iade, ödeme talebi vb. için).
fraudulent 402 (fraud_error) Sahtecilik denetimi ödemeyi reddetti.
idempotency_conflict 409 Aynı Idempotency-Key farklı bir istek gövdesiyle kullanıldı.
idempotency_in_progress 409 Bu Idempotency-Key ile gönderilen ilk istek henüz bitmedi; kısa süre sonra tekrar deneyin.
capture_failed 502 (api_error) Banka capture işlemini yapamadı; ödeme değişmedi, çağrı tekrar denenebilir.
void_failed 502 (api_error) Banka iptal işlemini yapamadı; ödeme değişmedi, çağrı tekrar denenebilir.
resource_missing 404 Nesne yok (veya başka bir üye işyerine ait).
parameter_invalid 400 Bir parametrenin değeri geçersiz; param alanı hangisi olduğunu söyler.
parameter_missing 400 Zorunlu bir parametre eksik; param alanı hangisi olduğunu söyler.
payouts_frozen 403 Hesabınızda ödemeler dondurulmuş; destekle iletişime geçin.
manual_payouts_not_allowed 403 Hesabınız planlı ödeme alıyor; manuel ödeme talebi açık değil.
amount_exceeds_refundable 400 İade tutarı ödemenin amount_refundable değerini aşıyor.
card_data_in_unexpected_field 400 Kart numarası payment_method_data[card] dışında bir alanda bulundu; istek hiçbir şey saklanmadan reddedildi.
card_data_in_url 400 Kart numarası URL veya sorgu dizesinde bulundu; kart verisini asla URL'ye koymayın.
card_vault_unavailable 503 Kart kasası geçici olarak kullanılamıyor; aynı Idempotency-Key ile tekrar deneyin.
token_invalid 404 Belirteç veya bağlantı geçersiz ya da süresi dolmuş.
password_too_weak 400 Parola güç kurallarını karşılamıyor.
mfa_code_invalid 400 Tek kullanımlık kod yanlış veya süresi dolmuş.
invitation_not_accepted 409 Davet henüz kabul edilmedi.
evidence_rejected 400 Uyuşmazlık kanıtı reddedildi (kapanmış uyuşmazlık, çok büyük veya geçersiz tür).
amount_below_minimum 400 Tutar izin verilen asgari tutarın altında.
settlement_account_unavailable 403 Bu işlem için onaylı bir hesap (IBAN) yok.
merchant_not_active 403 Üye işyeri hesabınız aktif değil (henüz onaylanmadı veya askıda).
currency_not_supported 400 Para birimi hesabınızda etkin değil.
payouts_not_configured 403 Hesabınızda ödeme yapılandırması yok.
ip_not_allowed 403 İstek, izin listenizde olmayan bir IP adresinden geldi (kimlik doğrulama rehberine bakın).
product_not_enabled 403 Ürün hesabınızda etkin değil (örneğin online kart ödemesi için sanal POS ürünü gerekir).
website_not_registered 403 Web sitesi hesabınıza kayıtlı değil.
return_url_not_allowed 400 return_url kayıtlı bir callback URL değil (3-D Secure rehberine bakın).
webhook_url_not_allowed 400 Webhook url değeri kayıtlı bir callback URL değil.
change_pending 409 Aynı türde önceki bir değişiklik hâlâ onay bekliyor.
user_not_authorized 403 Kullanıcı şirket ortağı değil ve bu rol için onaylı yetkisi yok.
billing_details_required 400 Onay için fatura bilgileri zorunlu: name, address.line1, address.city, address.country.
line_items_required 400 Bu hesap için kalem (line_items) bilgisi zorunlu.
line_items_amount_mismatch 400 Kalemlerin toplamı amount değerine eşit değil.

Kart ret kodları

Bir card_error durumunda decline_code nedenini belirtir. Müşteriye genel bir mesaj gösterin ("kartınız reddedildi, başka bir kart deneyin"); tam neden kayıtlarınız ve destek ekibiniz içindir.

decline_code Anlamı
insufficient_funds Kartta yeterli bakiye/limit yok.
do_not_honor Kartı çıkaran banka özel bir neden belirtmeden reddetti.
lost_card Kart kayıp olarak bildirilmiş.
stolen_card Kart çalıntı olarak bildirilmiş.
expired_card Kartın süresi dolmuş.
incorrect_cvc CVC hatalı.
invalid_card Kart numarası veya bilgileri geçersiz.
card_not_supported Kartın markası veya türü kabul edilemiyor.
installment_not_supported Kart veya terminal istenen taksit sayısını desteklemiyor.
authentication_failed 3-D Secure doğrulaması başarısız oldu veya tamamlanmadı.
issuer_unavailable Kartı çıkaran bankaya ulaşılamadı; daha sonra tekrar deneyin.
processing_error Bankada işlem hatası; daha sonra tekrar deneyin.
fraudulent Kartı çıkaran banka sahtecilik şüphesi duyuyor.
limit_exceeded Kart limiti (tutar veya adet) aşıldı.
restricted_card Karta kısıt konmuş.
transaction_not_allowed Kart bu tür işleme izin vermiyor (örneğin internet kullanımı).

Ret kodları normalize edilmiştir: bankalar çok farklı ham kodlar kullanır ve platform bunları yukarıdaki listeye eşler. Retler ya kesin (aynı kartı yeniden denemek işe yaramaz; örneğin lost_card, stolen_card, expired_card) ya da teknik (issuer_unavailable, processing_error; müşteri daha sonra yeniden deneyebilir) olur.

Kodda hata yönetimi