> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Payven Hata Kodları

> Payven domain hata kodlarının tam listesi (snake_case).

Bu sayfa Sanal POS'un kendi domain hata kodlarını listeler. Tüm kodlar **lowercase snake\_case** formatındadır ve hata yanıtının `code` alanında döner. Banka tarafından gelen ham yanıt kodları için: [Banka Yanıt Kodları](/sanal-pos/errors/bank-codes).

## Genel ödeme akışı

| Kod                     | Anlam                                                                   |
| ----------------------- | ----------------------------------------------------------------------- |
| `insufficient_funds`    | Yetersiz bakiye                                                         |
| `card_expired`          | Kart süresi dolmuş                                                      |
| `invalid_card`          | Kart numarası geçersiz (Luhn / format)                                  |
| `invalid_cvv`           | CVV yanlış                                                              |
| `invalid_card_number`   | Kart numarası alan validasyonu başarısız                                |
| `invalid_card_expiry`   | Son kullanma tarihi format hatalı                                       |
| `invalid_card_holder`   | Kart sahibi adı geçersiz / boş                                          |
| `invalid_amount`        | Tutar geçersiz (negatif, sıfır, minimum altında)                        |
| `invalid_currency`      | Desteklenmeyen para birimi                                              |
| `invalid_installment`   | Taksit sayısı bu kart için desteklenmiyor                               |
| `bank_declined`         | Banka işlemi reddetti — `provider_error_code` daha spesifik bilgi taşır |
| `do_not_honor`          | Banka spesifik "Do Not Honor" reddi (banka kodu 05)                     |
| `limit_exceeded`        | Banka harcama limiti aşıldı                                             |
| `fraud_suspected`       | Banka fraud şüphesiyle reddetti                                         |
| `bin_restricted`        | BIN blacklist / kısıtlama nedeniyle reddedildi                          |
| `duplicate_external_id` | Aynı `external_id` ile başka bir işlem zaten var                        |
| `payment_failed`        | Genel ödeme başarısız (spesifik kod yok)                                |
| `payment_exception`     | Konnektöre ulaşılamadan yakalanan exception                             |
| `bank_timeout`          | Banka yanıt vermedi                                                     |
| `bank_system_error`     | Banka iç sistem hatası                                                  |
| `internal_server_error` | Payven iç sistem hatası                                                 |
| `config_error`          | Konnektör konfigürasyonu hatalı / eksik                                 |
| `unknown_error`         | Eşlenmemiş hata — destek talebine açın                                  |

## Akış kontrol kodları

| Kod                      | Anlam                                                           |
| ------------------------ | --------------------------------------------------------------- |
| `payment_not_found`      | Verilen `transaction_id` bulunamadı                             |
| `connector_not_found`    | Bu işlem için uygun konnektör yok                               |
| `routing_no_match`       | Hiçbir yönlendirme kuralı koşulları karşılamadı                 |
| `invalid_merchant_id`    | `X-Merchant-Id` veya `X-External-Merchant-Id` header'ı geçersiz |
| `merchant_not_found`     | Merchant kaydı bulunamadı                                       |
| `merchant_inactive`      | Merchant pasif statüde                                          |
| `invalid_billing_city`   | Fatura adresi şehir kodu geçersiz                               |
| `invalid_shipping_city`  | Gönderim adresi şehir kodu geçersiz                             |
| `invalid_callback_url`   | `callback_url` HTTPS değil veya geçersiz                        |
| `non_3d_not_allowed`     | Tenant policy'sinde Non-3D ödeme kapalı                         |
| `empty_callback_data`    | Banka callback'i boş veya parse edilemedi                       |
| `missing_transaction_id` | Callback'te `transaction_id` yok                                |

## 3D Secure kodları

| Kod                             | Anlam                                          |
| ------------------------------- | ---------------------------------------------- |
| `three_ds_failed`               | 3DS doğrulaması başarısız (genel)              |
| `three_ds_init_exception`       | 3DS başlatma sırasında exception               |
| `three_ds_not_supported`        | Konnektör 3DS desteklemiyor                    |
| `three_ds_init_not_allowed`     | İşlem mevcut durumunda 3DS init yapılamaz      |
| `three_ds_verify_failed`        | 3DS verify adımı başarısız (CAVV/ECI mismatch) |
| `three_ds_complete_not_allowed` | 3DS complete bu durumda izin verilmiyor        |
| `three_ds_complete_failed`      | 3DS complete sırasında banka reddi             |
| `three_ds_complete_exception`   | 3DS complete sırasında exception               |
| `three_ds_card_data_missing`    | Callback'te kart verisi eksik                  |
| `three_ds_module_not_found`     | 3DS modülü konnektörde implemente değil        |
| `three_ds_timeout`              | 3DS akışı 15 dakika içinde tamamlanmadı        |
| `three_ds_card_mismatch`        | Init ile complete arasında kart bilgisi farklı |

## Void / İptal kodları

| Kod                                 | Anlam                                                 |
| ----------------------------------- | ----------------------------------------------------- |
| `void_not_supported`                | Konnektör void operasyonu desteklemiyor               |
| `void_not_allowed`                  | İşlem mevcut durumunda void edilemez                  |
| `void_not_allowed_after_settlement` | Mutabakat sonrası void yapılamaz — `/refund` kullanın |
| `void_failed`                       | Banka void talebini reddetti                          |
| `void_exception`                    | Void sırasında exception                              |
| `payment_already_voided`            | İşlem zaten void edilmiş                              |
| `payment_not_voidable`              | Bu durumdaki işlem iptal edilemez                     |

## Refund / İade kodları

| Kod                          | Anlam                                           |
| ---------------------------- | ----------------------------------------------- |
| `refund_not_supported`       | Konnektör refund operasyonu desteklemiyor       |
| `refund_not_allowed`         | İşlem mevcut durumunda iade edilemez            |
| `refund_failed`              | Banka iade talebini reddetti                    |
| `refund_exception`           | İade sırasında exception                        |
| `payment_already_refunded`   | Tüm tutar zaten iade edilmiş                    |
| `invalid_refund_amount`      | İade tutarı negatif / sıfır                     |
| `refund_exceeds_original`    | İade tutarı kalan iade edilebilir tutarı aşıyor |
| `refund_currency_mismatch`   | İade para birimi orijinal işlemden farklı       |
| `bank_refund_period_expired` | Banka iade süresi dolmuş                        |
| `payment_not_refundable`     | İşlem iade edilebilir durumda değil             |

## Capture / Çekim kodları (Pre-Auth)

| Kod                                    | Anlam                                           |
| -------------------------------------- | ----------------------------------------------- |
| `capture_not_supported`                | Konnektör capture operasyonu desteklemiyor      |
| `capture_not_allowed`                  | İşlem Pre-Auth değil veya capture süresi dolmuş |
| `capture_failed`                       | Banka capture talebini reddetti                 |
| `capture_exception`                    | Capture sırasında exception                     |
| `capture_amount_exceeds_authorization` | Çekim tutarı rezerve tutarı aşıyor              |
| `capture_currency_mismatch`            | Capture para birimi orijinalden farklı          |
| `capture_state_update_failed`          | Capture sonrası kayıt güncellemesi başarısız    |
| `payment_already_captured`             | Pre-Auth tutarı zaten capture edilmiş           |
| `pre_auth_expired`                     | 24 saatlik capture süresi aşıldı                |
| `payment_not_pre_auth`                 | Bu işlem bir Pre-Auth değil (zaten Sale)        |

## Recurring kodları

| Kod                          | Anlam                                   |
| ---------------------------- | --------------------------------------- |
| `recurring_exception`        | Recurring oluşturma sırasında exception |
| `recurring_not_supported`    | Konnektör recurring desteklemiyor       |
| `recurring_cancel_exception` | Recurring iptal sırasında exception     |

## Point Inquiry kodları

| Kod                           | Anlam                                 |
| ----------------------------- | ------------------------------------- |
| `point_inquiry_not_supported` | Konnektör point inquiry desteklemiyor |
| `point_inquiry_failed`        | Banka point inquiry başarısız         |
| `point_inquiry_exception`     | Point inquiry sırasında exception     |

## Checkout Session kodları

| Kod                               | Anlam                                             |
| --------------------------------- | ------------------------------------------------- |
| `session_not_found`               | Session ID geçersiz                               |
| `session_closed`                  | Session zaten kapalı (completed/failed/expired)   |
| `session_expired`                 | Session geçerlilik süresi doldu                   |
| `session_amount_mismatch`         | İstekteki tutar session'daki ile uyuşmuyor        |
| `session_installment_not_allowed` | İstenen taksit `allowed_installments`'da değil    |
| `payment_mode_not_allowed`        | İstenen `payment_mode` session'da izin verilmemiş |
| `pre_auth_not_allowed`            | Pre-Auth seçildi ama `allow_pre_auth` kapalı      |
| `max_attempts_exceeded`           | Maksimum başarısız deneme sayısı aşıldı           |

## Generic / HTTP kodları

Aşağıdaki kodlar HTTP altyapısı tarafından üretilir; spesifik bir Payven domain kodu yoksa fallback olarak kullanılır.

| HTTP  | `code`                   | Anlam                                               |
| ----- | ------------------------ | --------------------------------------------------- |
| `400` | `bad_request`            | Genel istek hatası                                  |
| `400` | `invalid_json`           | Body geçersiz JSON                                  |
| `401` | `unauthorized`           | Token eksik / geçersiz                              |
| `403` | `forbidden`              | Yetki yok                                           |
| `404` | `resource_not_found`     | Generic kaynak bulunamadı                           |
| `409` | `conflict`               | Generic çakışma                                     |
| `409` | `idempotency_key_in_use` | Aynı `Idempotency-Key` farklı body için kullanılmış |
| `422` | `validation_failed`      | Validasyon kuralı ihlali                            |
| `429` | `rate_limit_exceeded`    | İstek limiti aşıldı                                 |
| `500` | `internal_server_error`  | Sunucu hatası                                       |
| `502` | `bad_gateway`            | Konnektör kötü yanıt                                |
| `503` | `service_unavailable`    | Servis geçici olarak erişilemez                     |

## Bilinmeyen kod

`unknown_error` — konnektörden gelen kod Payven eşleme tablosunda yok. Bu durumlarda ham mesaj `detail` alanında bulunur. Lütfen `correlation_id` ile birlikte [destek ekibimize](/resources/support) yazın — eşleme tablosunu güncelleyebiliriz.