> For the complete documentation index, see [llms.txt](https://docs.iyzico.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iyzico.com/on-hazirliklar/test-ve-dogrulama.md).

# Test ve Doğrulama

## Test Stratejisi ve Yaklaşımı

iyzico entegrasyonu canlıya çıkmadan önce tüm ödeme akışlarının sandbox ortamında uçtan uca test edilmesi, canlı ortamda ise yalnızca düşük tutarlı bir smoke test yapılması tavsiye edilir. Testlerin dört katmanda yürütülmesi önerilir:

{% stepper %}
{% step %}

## Birim testleri

İmza (signature) üretimi, tutar formatı, `conversationId` üretimi ve yanıt eşleme (mapping) kodunun test edilmesi tavsiye edilir.
{% endstep %}

{% step %}

## Entegrasyon testleri

Sandbox API'sine gerçek çağrı yapılması; her senaryo için test kartı ve beklenen `status` / `errorCode` değerinin doğrulanması tavsiye edilir.
{% endstep %}

{% step %}

## Uçtan uca (E2E) testler

Checkout Form, Pay with iyzico veya 3DS akışının tarayıcıda baştan sona çalıştırılması; callback ve webhook dahil sipariş durumunun kontrol edilmesi tavsiye edilir.
{% endstep %}

{% step %}

## UAT ve canlı smoke test

İş biriminin senaryoları onaylaması; canlıda gerçek kartla düşük tutarlı bir ödeme + iade yapılması tavsiye edilir.
{% endstep %}
{% endstepper %}

**Temel ilkeler:**

* Her testte, iyzico yanıtındaki `status` (`success` / `failure`) alanına ve kendi sisteminizdeki sipariş durumuna birlikte bakılması tavsiye edilir; yalnızca HTTP 200 alınması başarı sayılmamalıdır.
* Her istekte benzersiz bir `conversationId` gönderilmesi ve yanıtta aynı değerin döndüğünün kontrol edilmesi tavsiye edilir.
* Ödeme sonucunun her zaman iyzico'dan sorgulanarak (retrieve/webhook) teyit edilmesi mümkündür ve tavsiye edilir.
* Test kapsamının projede kullanılan ürünlere göre daraltılması önerilir (ör. yalnızca Checkout Form kullanılıyorsa Non-3DS API senaryoları kapsam dışı bırakılabilir).

## Test Ortamı ve Kimlik Bilgileri

Tüm testlerin `https://sandbox-api.iyzipay.com` adresine, sandbox hesabının `sandbox-` önekli API ve Secret Key çifti ile yapılması tavsiye edilir. Canlı ortam `https://api.iyzipay.com` adresini ve tamamen farklı anahtarları kullanır (Live vs Sandbox).

**Ortam kuralları:**

* Sandbox'ta gerçek kartla ödeme yapılamaz; yalnızca test kartları çalışır.
* Test kartlarında son kullanma tarihi ve CVC rastgele olabilir; ancak formatın doğru ve tarihin ileri bir tarih olması gerekir (ör. `12/2030`, `123`).
* API anahtarlarının kodda değil, ortam değişkeninde veya secret manager'da tutulması tavsiye edilir; sandbox ve canlı anahtarlarının ayrı konfigürasyon profillerinde saklanması önerilir.
* Webhook testleri için uygulamanızın dışarıdan erişilebilir bir HTTPS URL'sine sahip olması gerekir.

| Bileşen                 | Sandbox değeri                                       | Kaynak                      |
| ----------------------- | ---------------------------------------------------- | --------------------------- |
| API Base URL            | `https://sandbox-api.iyzipay.com`                    | Live vs Sandbox             |
| Merchant paneli (kayıt) | `https://sandbox-merchant.iyzipay.com/auth/register` | Sandbox                     |
| API Key / Secret Key    | Panelde Ayarlar > Firma Ayarları > API Anahtarları   | Sandbox                     |
| 3DS / SMS şifresi       | Her zaman `283126`                                   | Sandbox                     |
| Test kartları           | Başarılı, yabancı ve hata üreten kartlar             | Test Kartları               |
| Kimlik doğrulama        | HMACSHA256 imzalı header                             | HMACSHA256 Kimlik Doğrulama |
| Hazır istekler          | Postman koleksiyonu, GitHub                          | Postman Collections, GitHub |

## Test Senaryoları ve Beklenen Sonuçlar

Her test senaryosunun aşağıdaki alanlarla kayıt altına alınması tavsiye edilir. "Beklenen sonuç" alanının her zaman hem iyzico yanıtını hem de kendi sisteminizdeki durumu içermesi önerilir.

| Alan                   | Açıklama                                           | Örnek                                                                 |
| ---------------------- | -------------------------------------------------- | --------------------------------------------------------------------- |
| Test ID                | Grup öneki + sıra numarası                         | `TC-NEG-03`                                                           |
| Başlık                 | Senaryonun tek satırlık adı                        | Yetersiz bakiye ile ödeme                                             |
| Ön koşul               | Gerekli veri ve durum                              | Sepette 1 ürün, 3DS kapalı akış                                       |
| Test verisi            | Kart, tutar, taksit                                | `4111111111111129`, 100.00 TRY, 1 taksit                              |
| Adımlar                | Uygulanacak adımlar                                | BIN kontrol, öde vb.                                                  |
| Beklenen iyzico yanıtı | `status`, `errorCode`, `errorGroup`                | `failure`, `10051`, `NOT_SUFFICIENT_FUNDS`                            |
| Beklenen sistem durumu | Sipariş, stok, e-posta, log                        | Sipariş `PAYMENT_FAILED`, stok düşülmedi, kullanıcıya anlaşılır mesaj |
| Gerçekleşen sonuç      | Test sırasında doldurulur                          | —                                                                     |
| Sonuç                  | Pass / Fail / Blocked                              | —                                                                     |
| Kanıt                  | Ekran görüntüsü, request/response log, `paymentId` | —                                                                     |

**Test ID önekleri ve senaryo grupları:**

| Önek     | Grup                          |
| -------- | ----------------------------- |
| `TC-POS` | Başarılı ödeme                |
| `TC-NEG` | Hatalı ve başarısız ödeme     |
| `TC-3DS` | 3D Secure                     |
| `TC-REF` | İptal ve iade                 |
| `TC-WH`  | Webhook ve asenkron olaylar   |
| `TC-IDM` | Idempotency ve mükerrer istek |
| `TC-REG` | Regresyon                     |
| `TC-UAT` | Kullanıcı kabul               |

Hata kodlarının listesi ve kullanıcıya gösterilecek mesajlar için: Hata Kodları.

## Başarılı Ödeme Senaryoları

Başarılı bir ödemenin; iyzico'nun `status: success` dönmesi (Checkout Form ve PWI sorgulamalarında ayrıca `paymentStatus: SUCCESS`), siparişin ödendi olarak işaretlenmesi ve Retrieve sorgusunun aynı sonucu vermesiyle geçmesi beklenir. Kartların tam listesi: Test Kartları.

| Test ID     | Senaryo                                 | Test verisi                             | Nasıl test edilir                                                                                     | Beklenen sonuç                                                                |
| ----------- | --------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `TC-POS-01` | Kredi kartı ile tek çekim               | `5528790000000008` (Halkbank MC Credit) | Checkout Form veya API ile 1 taksit ödeme yapılması tavsiye edilir                                    | `success`; `paymentId` kaydedildi; sipariş `PAID`                             |
| `TC-POS-02` | Banka kartı (debit) ile ödeme           | `5890040000000016` (Akbank MC Debit)    | 3DS akışıyla tek çekim yapılması tavsiye edilir                                                       | `success`; yanıttaki `cardType` banka kartını gösterir                        |
| `TC-POS-03` | Taksitli ödeme                          | `5528790000000008`, 3 taksit            | Önce Taksit ve BIN Sorgulama ile seçeneklerin getirilmesi, ardından 3 taksit seçilmesi tavsiye edilir | `installment: 3`; `paidPrice` vade farkını içerir                             |
| `TC-POS-04` | Troy kart                               | `9792030000000000` (QNB Troy Credit)    | Tek çekim yapılması tavsiye edilir                                                                    | `success`; `cardAssociation: TROY`                                            |
| `TC-POS-05` | American Express                        | `374427000000003`, CVC 4 hane           | Tek çekim yapılması tavsiye edilir                                                                    | `success`; 3 haneli CVC ile hata 15 alınır                                    |
| `TC-POS-06` | Yabancı kart                            | `5400010000000004` (Non-Turkish Credit) | Tek çekim yapılması tavsiye edilir                                                                    | Hesapta yabancı kart açıksa `success`; kapalıysa `10221` ve kullanıcıya mesaj |
| `TC-POS-07` | Farklı para birimi (kullanılıyorsa)     | `currency: USD` / `EUR`                 | Tek çekim yapılması tavsiye edilir                                                                    | Yanıttaki `currency` istekle aynı                                             |
| `TC-POS-08` | Sepette birden fazla ürün               | 3 `basketItem`, toplam = `price`        | Ödeme yapılması tavsiye edilir                                                                        | `success`; her kalem için `paymentTransactionId` döner ve saklanır            |
| `TC-POS-09` | Kayıtlı kart ile ödeme (kullanılıyorsa) | `cardUserKey` + `cardToken`             | Önce kartın kaydedilmesi, sonra token ile ödeme yapılması tavsiye edilir                              | `success`; kart numarası sizin sisteminizde tutulmuyor (Kart Saklama)         |
| `TC-POS-10` | iyzico ile Öde (PWI) (kullanılıyorsa)   | Sandbox iyzico hesabı, SMS `283126`     | PWI sayfasına yönlendirilmesi, ödemenin yapılması ve callback'e dönülmesi tavsiye edilir              | Retrieve sonucu `success`; sipariş `PAID`                                     |
| `TC-POS-11` | Ön provizyon + kapama (kullanılıyorsa)  | `5528790000000008`                      | Provizyon başlatılması, ardından kapama yapılması tavsiye edilir                                      | Provizyon `success`; kapama sonrası tutar tahsil edildi                       |

**Her başarılı senaryoda ek olarak şunların kontrol edilmesi tavsiye edilir:**

* Yanıttaki `price`, `paidPrice`, `currency` ve `conversationId` istekle eşleşiyor.
* Yanıt imzası doğrulanıyor (İmza Yanıtının Doğrulanması).
* Ödeme, sandbox merchant panelinde aynı tutar ve durumla görünüyor.
* Müşteriye onay e-postası / ekranı gösteriliyor; stok ve muhasebe kayıtları güncelleniyor.

## Hatalı ve Başarısız Ödeme Senaryoları

Hatalı senaryolarda amaç, iyzico'nun döndürdüğü `status: failure` + `errorCode` değerinin doğru yakalanması, siparişin ödendi sayılmaması ve kullanıcıya anlaşılır bir mesaj gösterilmesidir. Kod eşleşmeleri Hata Kodları sayfasından alınmıştır; kartlar Test Kartları sayfasındaki "Hata Üreten Kartlar" tablosundandır.

### A. Banka red senaryoları (hata üreten test kartları)

<table><thead><tr><th>Test ID</th><th>Senaryo</th><th width="164.9140625">Test kartı</th><th>Beklenen errorCode / errorGroup</th><th>Kullanıcıya gösterilecek davranış</th></tr></thead><tbody><tr><td><code>TC-NEG-01</code></td><td>Yetersiz bakiye</td><td><code>4111111111111129</code></td><td><code>10051</code> / <code>NOT_SUFFICIENT_FUNDS</code></td><td>"Kart limiti yetersiz"; başka kartla tekrar denemesi önerilir</td></tr><tr><td><code>TC-NEG-02</code></td><td>Do not honour</td><td><code>4129111111111111</code></td><td><code>10005</code> / <code>DO_NOT_HONOUR</code></td><td>Bankasıyla görüşmesi önerilir</td></tr><tr><td><code>TC-NEG-03</code></td><td>Geçersiz işlem</td><td><code>4128111111111112</code></td><td><code>10012</code> / <code>INVALID_TRANSACTION</code></td><td>Genel red mesajı</td></tr><tr><td><code>TC-NEG-04</code></td><td>Kayıp kart</td><td><code>4127111111111113</code></td><td><code>10041</code> / <code>LOST_CARD</code></td><td>Detay verilmeden genel red mesajı</td></tr><tr><td><code>TC-NEG-05</code></td><td>Çalıntı kart</td><td><code>4126111111111114</code></td><td><code>10043</code> / <code>STOLEN_CARD</code></td><td>Detay verilmeden genel red mesajı</td></tr><tr><td><code>TC-NEG-06</code></td><td>Vadesi geçmiş kart</td><td><code>4125111111111115</code></td><td><code>10054</code> / <code>EXPIRED_CARD</code></td><td>"Kartın süresi dolmuş"</td></tr><tr><td><code>TC-NEG-07</code></td><td>Hatalı CVC</td><td><code>4124111111111116</code></td><td><code>10084</code> / <code>INVALID_CVC2</code></td><td>CVC'yi tekrar girmesi istenir</td></tr><tr><td><code>TC-NEG-08</code></td><td>Kart sahibine izin yok</td><td><code>4123111111111117</code></td><td><code>10057</code> / <code>NOT_PERMITTED_TO_CARDHOLDER</code></td><td>Bankasıyla görüşmesi önerilir</td></tr><tr><td><code>TC-NEG-09</code></td><td>Terminale izin yok</td><td><code>4122111111111118</code></td><td><code>10058</code> / <code>NOT_PERMITTED_TO_TERMINAL</code></td><td>Genel hata; destek kaydı açılması önerilir</td></tr><tr><td><code>TC-NEG-10</code></td><td>Fraud şüphesi</td><td><code>4121111111111119</code></td><td><code>10034</code> / <code>FRAUD_SUSPECT</code></td><td>Detay verilmeden genel red mesajı</td></tr><tr><td><code>TC-NEG-11</code></td><td>Pickup card</td><td><code>4120111111111110</code></td><td><code>10041</code> / <code>PICKUP_CARD</code></td><td>Detay verilmeden genel red mesajı</td></tr><tr><td><code>TC-NEG-12</code></td><td>Genel banka hatası</td><td><code>4130111111111118</code></td><td><code>failure</code> (ilk koşumda dönen kodun kayıt altına alınması önerilir)</td><td>"Ödeme alınamadı, tekrar deneyin"</td></tr></tbody></table>

### B. İstek ve doğrulama hataları

| Test ID     | Senaryo                        | Nasıl tetiklenir                                                                          | Beklenen sonuç                    |
| ----------- | ------------------------------ | ----------------------------------------------------------------------------------------- | --------------------------------- |
| `TC-NEG-13` | Geçersiz kart numarası         | Luhn'a uymayan bir numara gönderilmesi tavsiye edilir                                     | `12` – Kart numarası geçersiz     |
| `TC-NEG-14` | Geçmiş son kullanma tarihi     | `expireYear` alanına geçmiş bir yıl gönderilmesi tavsiye edilir                           | `13` / `14`                       |
| `TC-NEG-15` | Yanlış CVC uzunluğu            | 2 haneli CVC gönderilmesi tavsiye edilir                                                  | `15` – cvc geçersiz               |
| `TC-NEG-16` | Sepet toplamı tutmuyor         | `basketItem` toplamının `price` değerinden farklı gönderilmesi tavsiye edilir             | `5062`                            |
| `TC-NEG-17` | Sıfır veya negatif ürün fiyatı | `basketItem.price = 0` gönderilmesi tavsiye edilir                                        | `5050`                            |
| `TC-NEG-18` | Zorunlu alan eksik             | `buyer.email` / `gsmNumber` / `identityNumber` alanlarının boş bırakılması tavsiye edilir | `3` / `25` / `8`                  |
| `TC-NEG-19` | Hatalı imza                    | Secret key'in bilerek yanlış verilmesi tavsiye edilir                                     | `1000` – Geçersiz imza            |
| `TC-NEG-20` | Ortam / anahtar uyuşmazlığı    | Sandbox anahtarının canlı URL ile kullanılması tavsiye edilir                             | `1001` – API bilgileri bulunamadı |
| `TC-NEG-21` | Banka kartı ile taksit         | Debit kart + 3 taksit denenmesi tavsiye edilir                                            | `10218`                           |
| `TC-NEG-22` | Banka kartı 3DS'siz            | Debit kart ile Non-3DS ödeme denenmesi tavsiye edilir                                     | `10217` (bankaya bağlı)           |

### C. Sistem ve akış hataları

* **`TC-NEG-23` – Zaman aşımı:** İstemci timeout değerinin çok düşük ayarlanması tavsiye edilir (ör. 1 ms). Beklenen: sipariş `PENDING` kalır, ardından Ödeme Sorgulama veya webhook ile gerçek durum tespit edilir; kullanıcıdan ikinci kez para çekilmez.
* **`TC-NEG-24` – Kullanıcı Checkout Form'u kapatır:** Formun açılıp ödeme yapılmadan sekmenin kapatılması tavsiye edilir. Beklenen: sipariş `PAID` olmaz, token süresi dolunca iptal çalışır.
* **`TC-NEG-25` – Callback manipülasyonu:** Callback URL'ine sahte token / `status=success` ile istek atılması tavsiye edilir. Beklenen: sistem Retrieve sorgusu yapar, sonuç `failure` olduğu için sipariş onaylanmaz.
* **`TC-NEG-26` – Tutar manipülasyonu:** İstemcide fiyatın değiştirilmesi tavsiye edilir. Beklenen: tutar sunucuda yeniden hesaplanır; Retrieve'deki `paidPrice` ile sipariş tutarı eşleşmezse sipariş onaylanmaz ve alarm üretilir.

## 3D Secure Test Senaryoları

3DS akışı iki adımlıdır: 3DS Başlatma banka doğrulama HTML'ini döner, kullanıcı doğruladıktan sonra banka callback URL'inize POST yapar ve siz 3DS Tamamlama (`/payment/3dsecure/auth` veya önerilen `/payment/v2/3dsecure/auth`) ile ödemeyi sonlandırırsınız. Sandbox'ta SMS şifresi her zaman `283126`'dır. Checkout Form kullanılıyorsa 3DS adımları form içinde yönetilir; aynı senaryoların CF Sorgulama sonucuna bakılarak test edilmesi tavsiye edilir.

| Test ID     | Senaryo                                 | Test verisi                      | Nasıl test edilir                                                                         | Beklenen sonuç                                                                          |
| ----------- | --------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `TC-3DS-01` | Başarılı 3DS doğrulama                  | `5528790000000008`, SMS `283126` | Init → banka sayfası → SMS girişi → callback → Auth akışının izlenmesi tavsiye edilir     | Callback'te `status=success`, `mdStatus=1`; Auth yanıtı `success`; sipariş `PAID`       |
| `TC-3DS-02` | Yanlış SMS kodu                         | Aynı kart, SMS `000000`          | Doğrulama sayfasında yanlış kod girilmesi tavsiye edilir                                  | Doğrulama başarısız; Auth çağrılmaz; sipariş `PAYMENT_FAILED`                           |
| `TC-3DS-03` | `mdStatus = 0`                          | `4131111111111117`               | Tam akışın çalıştırılması tavsiye edilir                                                  | Callback'te `mdStatus=0`; sistem Auth çağırmaz ve ödemeyi reddeder                      |
| `TC-3DS-04` | `mdStatus = 4`                          | `4141111111111115`               | Tam akışın çalıştırılması tavsiye edilir                                                  | `mdStatus=4`; yalnızca 1 kabul edildiği için ödeme başarısız sayılır                    |
| `TC-3DS-05` | 3DS başlatma hatası                     | `4151111111111112`               | Init isteği gönderilmesi tavsiye edilir                                                   | Init `failure`; kullanıcıya hata mesajı; banka sayfası açılmaz                          |
| `TC-3DS-06` | Kullanıcı doğrulama sayfasını terk eder | Başarılı kart                    | Banka sayfasında sekmenin kapatılması tavsiye edilir                                      | İşlem `INIT_3DS` durumunda kalır; sipariş ödenmedi kalır; zaman aşımı temizliği çalışır |
| `TC-3DS-07` | Yanlış `paymentId` ile Auth             | Sahte `paymentId`                | Auth isteğinin manipüle edilmesi tavsiye edilir                                           | `5087` – Ödeme kaydı bulunamadı                                                         |
| `TC-3DS-08` | v2 Auth tutar uyuşmazlığı               | Init'tekinden farklı `paidPrice` | `/payment/v2/3dsecure/auth`'a farklı tutar gönderilmesi tavsiye edilir                    | `failure`; sipariş onaylanmaz                                                           |
| `TC-3DS-09` | Callback iki kez gelir                  | Başarılı kart                    | Callback isteğinin tekrar gönderilmesi (replay) tavsiye edilir                            | Auth bir kez çağrılır; ikinci istek mevcut sonucu döner (bkz. 11.9)                     |
| `TC-3DS-10` | Banka kartı ile 3DS                     | `5890040000000016`               | Tam akışın çalıştırılması tavsiye edilir                                                  | `success`; Non-3DS'de alınan `10217` hatası burada alınmaz                              |
| `TC-3DS-11` | Mobil tarayıcı / WebView                | Başarılı kart                    | iOS Safari, Android Chrome ve uygulama içi WebView'da tam akışın denenmesi tavsiye edilir | Banka sayfası doğru açılır; callback sonrası oturum kaybolmaz                           |

**Ek kontroller:** Callback endpoint'inin yalnızca POST kabul etmesi; Auth yanıtındaki `signature` değerinin doğrulanması (İmza Yanıtının Doğrulanması); `fraudStatus` değeri `0` (incelemede) ise ürünün sevk edilmemesi tavsiye edilir.

## &#x20;İptal ve İade Senaryoları

İptal (`/payment/cancel`) aynı gün, `paymentId` ile ve yalnızca tam tutar için yapılır; iade (`/payment/refund`) 365 gün içinde `paymentTransactionId` ile tam veya kısmi olarak yapılır. İade V2 (`/v2/payment/refund`) aynı işlemi `paymentId` üzerinden yapar. Kaynak: İptal ve İade.

| Test ID     | Senaryo                                  | Nasıl test edilir                                                                                   | Beklenen sonuç                                                                                    |
| ----------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `TC-REF-01` | Aynı gün tam iptal                       | Başarılı bir ödeme yapılıp aynı gün `paymentId` ile cancel gönderilmesi tavsiye edilir              | `success`; `price` = ödeme tutarı; sipariş `CANCELLED`; stok geri alındı                          |
| `TC-REF-02` | Tam iade (kalem bazında)                 | Her `paymentTransactionId` için kalemin `paidPrice` tutarı kadar refund gönderilmesi tavsiye edilir | Her kalem `success`; sipariş `REFUNDED`                                                           |
| `TC-REF-03` | Kısmi iade                               | 3 kalemli sepette yalnızca 1 kalemin iade edilmesi tavsiye edilir                                   | Yalnız o kalem iade edildi; sipariş `PARTIALLY_REFUNDED`                                          |
| `TC-REF-04` | Ardışık kısmi iadeler                    | Aynı kalemin iki parçada iade edilmesi tavsiye edilir (ör. 40 + 60)                                 | İkisi de `success`; toplam iade = kalem tutarı                                                    |
| `TC-REF-05` | Fazla iade                               | Kalan iade edilebilir tutardan fazla `price` gönderilmesi tavsiye edilir                            | `failure`; sistemde iade kaydı oluşmaz                                                            |
| `TC-REF-06` | İade V2                                  | `paymentId` ve tutar ile `/v2/payment/refund` çağrılması tavsiye edilir                             | `success`; iyzico kalemi kendisi seçer; kalem kayıtlarınız Retrieve ile eşleştirilir              |
| `TC-REF-07` | İptal/iade edilemeyen ödeme              | `5406670000000009` kartıyla ödeme yapılıp sonra iptal ve iade denenmesi tavsiye edilir              | Ödeme `success`, iptal ve iade `failure`; operasyon ekibine bildirim                              |
| `TC-REF-08` | Yanlış `paymentId` ile iptal             | Var olmayan bir `paymentId` kullanılması tavsiye edilir                                             | `5086` – Ödeme kaydı bulunamadı                                                                   |
| `TC-REF-09` | Zaten iptal edilmiş ödemeyi tekrar iptal | `TC-REF-01`'den sonra ikinci bir cancel gönderilmesi tavsiye edilir                                 | `failure`; tutar ikinci kez iade edilmez                                                          |
| `TC-REF-10` | Başarısız ödemeye iade                   | `failure` olan ödemenin kalemine refund gönderilmesi tavsiye edilir                                 | `failure` veya istek sisteminizde engellenir                                                      |
| `TC-REF-11` | `reason` alanı                           | `reason: BUYER_REQUEST` + `description` gönderilmesi tavsiye edilir                                 | `success`; neden panelde görünür                                                                  |
| `TC-REF-12` | Aynı gün iade (iptal yerine)             | Ödeme günü refund gönderilmesi tavsiye edilir                                                       | Bankaya bağlı olarak `10223` (gün sonu yapılmalı) dönebilir; sistem bu durumda iptale yönlendirir |

**Kontrol noktaları:** İade/iptal sonrası Retrieve sorgusunun güncel durumu göstermesi; muhasebe kaydı ve müşteri bildiriminin oluşturulması; yanıttaki `retryable` alanı `true` ise yeniden deneme mantığının çalışması, `false` ise manuel incelemeye düşmesi tavsiye edilir.&#x20;

## Webhook ve Asenkron Olay Testleri

iyzico, ödeme denemesinden 10–15 saniye sonra webhook URL'inize JSON POST gönderir; 2xx yanıt alana kadar 15 dakikada bir, 3 kez daha dener. İmza `X-IYZ-SIGNATURE-V3` header'ında gelir (V1 ve V2 artık desteklenmiyor) ve hesapta webhook imza özelliğinin açılması için <entegrasyon@iyzico.com> ile iletişime geçilmesi gerekir.

### Hazırlık

{% stepper %}
{% step %}

## Webhook URL'ini tanımlayın

Sandbox panelinde Ayarlar > Firma Ayarları > İşyeri Bildirimleri alanına HTTPS webhook URL'inin girilmesi tavsiye edilir (abonelik kullanılıyorsa abonelik bildirim URL'inin de girilmesi önerilir).
{% endstep %}

{% step %}

## Gelen istekleri loglayın

Webhook endpoint'inizin gelen ham body'yi ve header'ları logladığından emin olunması tavsiye edilir.
{% endstep %}

{% step %}

## İmza doğrulamasını uygulayın

İmza doğrulamasının kullanılan formata göre uygulanması tavsiye edilir:

* **Direct format (Non-3DS / 3DS):** `secretKey + iyziEventType + paymentId + paymentConversationId + status`
* **HPP format (Checkout Form / PWI):** `secretKey + iyziEventType + iyziPaymentId + token + paymentConversationId + status`
* Her iki formatta da HMACSHA256 kullanılır ve sonuç hex olarak karşılaştırılır.
  {% endstep %}
  {% endstepper %}

| Test ID    | Senaryo                             | Nasıl test edilir                                                                               | Beklenen sonuç                                                                                                    |
| ---------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `TC-WH-01` | Başarılı ödeme bildirimi            | `TC-POS-01`'in çalıştırılıp 15 sn beklenmesi tavsiye edilir                                     | `status: SUCCESS` webhook'u alındı; imza doğrulandı; endpoint 2xx döndü; sipariş zaten `PAID` ise durum değişmedi |
| `TC-WH-02` | Başarısız ödeme bildirimi           | `TC-NEG-01`'in çalıştırılması tavsiye edilir                                                    | `status: FAILURE` alındı; sipariş `PAYMENT_FAILED`                                                                |
| `TC-WH-03` | Callback gelmeden webhook gelir     | Callback endpoint'inin geçici olarak kapatılıp ödeme yapılması tavsiye edilir                   | Sipariş webhook + Retrieve ile `PAID` oldu; kullanıcı döndüğünde doğru durumu görür                               |
| `TC-WH-04` | Geçersiz imza                       | Webhook'un Postman ile sahte imzayla gönderilmesi tavsiye edilir                                | İstek reddedilir (ör. 401), sipariş değişmez, güvenlik logu oluşur                                                |
| `TC-WH-05` | İmza header'ı yok                   | Header'sız POST gönderilmesi tavsiye edilir                                                     | İstek reddedilir                                                                                                  |
| `TC-WH-06` | Tekrar deneme (retry)               | Endpoint'in 500 dönecek şekilde ayarlanması, ödeme yapılması, sonra düzeltilmesi tavsiye edilir | iyzico tekrar gönderir; düzeltme sonrası 2xx; olay bir kez işlenir                                                |
| `TC-WH-07` | Aynı bildirim iki kez               | Aynı payload'ın iki kez gönderilmesi tavsiye edilir                                             | İkincisi 2xx alır ama işlenmez (`iyziReferenceCode` / `paymentId` ile tekilleştirme)                              |
| `TC-WH-08` | Sıra dışı olaylar                   | Önce `SUCCESS`, ardından eski tarihli `INIT_THREEDS` gönderilmesi tavsiye edilir                | Sipariş `PAID`'den geriye düşmez (`iyziEventTime` / durum önceliği)                                               |
| `TC-WH-09` | Ara durumlar                        | 3DS'te sayfanın terk edilmesi tavsiye edilir (`TC-3DS-06`)                                      | `INIT_THREEDS` gibi ara durumlar siparişi `PAID` yapmaz                                                           |
| `TC-WH-10` | Bilinmeyen sipariş                  | Sistemde olmayan `paymentConversationId` ile gönderilmesi tavsiye edilir                        | 2xx dönülür, uyarı loglanır, hata fırlatılmaz                                                                     |
| `TC-WH-11` | Yanıt süresi                        | Endpoint'te ağır iş varken yanıt süresinin ölçülmesi tavsiye edilir                             | Endpoint hızlıca 2xx döner; işleme kuyrukta asenkron yapılır                                                      |
| `TC-WH-12` | Abonelik bildirimi (kullanılıyorsa) | Sandbox'ta abonelik başlatılması tavsiye edilir                                                 | `subscription.order.success` / `failure` alınır; abonelik imza formatı ile doğrulanır                             |

{% hint style="info" %}
Webhook tek başına gerçek kaynak değildir. Bildirim alındıktan sonra sonucun Ödeme Sorgulama veya CF Sorgulama ile teyit edilmesi tavsiye edilir. Gece çalışan bir mutabakat işinin `PENDING` kalan siparişleri sorgulayarak kapatması ve bu işin de test edilmesi önerilir.
{% endhint %}

## Idempotency ve Mükerrer İstek Testleri

iyzico servislerinin çoğu idempotent değildir; aynı ödeme isteği iki kez gönderilirse iki ayrı çekim oluşabilir. Bu yüzden mükerrer korumanın kendi tarafınızda kurulması ve test edilmesi tavsiye edilir. iyzico'nun eşleştirme için önerdiği alanlar: sizin ürettiğiniz `conversationId` / `basketId`, iyzico'nun ürettiği `token` ve `paymentId.`

**Beklenen tasarım (testlerin dayandığı kurallar):**

* Her sipariş için tek bir ödeme denemesi kaydı ve benzersiz `conversationId` olması; aynı sipariş için açık bir deneme varken yenisinin başlatılmaması tavsiye edilir.
* Callback ve webhook işleyicilerinin aynı `paymentId` / `token` için yalnızca bir kez durum değiştirmesi tavsiye edilir.
* Zaman aşımından sonra ödeme isteğinin körü körüne tekrar gönderilmemesi; önce sorgulama yapılması tavsiye edilir.

| Test ID     | Senaryo                    | Nasıl test edilir                                                                        | Beklenen sonuç                                                                                                |
| ----------- | -------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `TC-IDM-01` | Çift tıklama               | "Öde" butonuna hızlıca iki kez basılması tavsiye edilir                                  | Tek istek iyzico'ya gider; buton ilk tıklamada kilitlenir; tek çekim                                          |
| `TC-IDM-02` | Paralel istek              | Aynı sipariş için iki ödeme isteğinin eşzamanlı gönderilmesi tavsiye edilir (script ile) | Biri işlenir, diğeri reddedilir veya mevcut sonucu döner; panelde tek ödeme                                   |
| `TC-IDM-03` | Sayfa yenileme / geri tuşu | Ödeme sonrası callback sayfasının yenilenmesi, tarayıcıda geri gidilmesi tavsiye edilir  | Yeni ödeme başlamaz; sipariş durumu sayfası gösterilir                                                        |
| `TC-IDM-04` | Timeout sonrası tekrar     | İstemci timeout'u sonrası sistemin retry yapmasının tetiklenmesi tavsiye edilir          | Retry öncesi Ödeme Sorgulama yapılır; ödeme zaten varsa yeni istek gönderilmez                                |
| `TC-IDM-05` | Callback replay            | Başarılı callback'in aynı parametrelerle tekrar gönderilmesi tavsiye edilir              | 3DS Auth / CF Retrieve bir kez işlenir; sipariş ve stok bir kez güncellenir                                   |
| `TC-IDM-06` | Webhook + callback yarışı  | Webhook ve callback'in aynı anda tetiklenmesi tavsiye edilir                             | Tek durum geçişi; tek e-posta; tek muhasebe kaydı                                                             |
| `TC-IDM-07` | Aynı iade iki kez          | Aynı kalem için iade isteğinin iki kez gönderilmesi tavsiye edilir                       | Sisteminiz ikincisini engeller veya iyzico kalan tutar kontrolüyle reddeder; toplam iade kalem tutarını aşmaz |
| `TC-IDM-08` | `conversationId` tekrarı   | İki farklı siparişte aynı `conversationId`'nin zorla kullanılması tavsiye edilir         | Mükerrer `conversationId`  gönderilmesi hata vermez. Tekillik kontrol edilmez                                 |
| `TC-IDM-09` | Aynı Checkout Form token'ı | İlk başarılı ödemeden sonra aynı token ile formun tekrar açılması tavsiye edilir         | Her token bir forma özeldir token bilgisi ile ödeme işlemi tetiklenememektedir                                |

**Doğrulama yöntemi:** Her testten sonra sandbox merchant panelinde ve Raporlama Servisi ile ilgili `basketId` / `conversationId` için yalnızca tek bir başarılı ödeme olduğunun kontrol edilmesi tavsiye edilir.

## Regresyon Testleri

Ödeme koduna, bağımlılıklara (iyzipay SDK sürümü) veya sepet/sipariş modülüne dokunan her değişiklikte sandbox'a karşı otomatik bir regresyon setinin çalıştırılması; set kırmızıysa yayın yapılmaması tavsiye edilir.

**Regresyonu tetikleyen değişiklikler:**

* iyzipay SDK veya HTTP istemcisi sürüm güncellemesi (örnek kod linkleri ilgili docs.iyzico.com sayfalarında yer alır).
* iyzico tarafında duyurulan değişiklikler (ör. webhook imzasının V3'e geçmesi, 3DS Auth v2 endpoint'i, HMACSHA256 kimlik doğrulama).
* Fiyat hesaplama, taksit, kampanya, para birimi veya sepet yapısı değişiklikleri.
* Callback/webhook URL'leri, sunucu, proxy veya TLS konfigürasyonu değişiklikleri.

| Katman                        | Kapsam                                                         | Ne zaman çalışır                               | Süre hedefi |
| ----------------------------- | -------------------------------------------------------------- | ---------------------------------------------- | ----------- |
| Smoke (`TC-REG-SMOKE`)        | `TC-POS-01`, `TC-NEG-01`, `TC-3DS-01`, `TC-REF-01`, `TC-WH-01` | Her pull request ve her deploy sonrası         | < 5 dk      |
| Tam regresyon (`TC-REG-FULL`) | 11.4–11.9'daki tüm otomatikleştirilebilir senaryolar           | Gece ve sürüm adayı (release candidate) öncesi | < 45 dk     |
| Manuel regresyon              | 3DS banka sayfası, mobil/WebView, Checkout Form görünümü       | Büyük sürümler ve SDK güncellemesi             | 1 iş günü   |

**Otomasyon notları:** 3DS banka sayfasının sandbox'ta tarayıcı otomasyonuyla (Playwright/Cypress) SMS `283126` girilerek geçilmesi; her koşumda yeni `conversationId` üretilmesi; testlerin sandbox hız sınırlarına takılmamak için paralel koşum sayısının sınırlandırılması tavsiye edilir (Limitler).

## Test Kanıtları ve Hata Yönetimi

Her test senaryosu için kanıtın, başka bir kişinin sonucu iyzico paneli ve loglardan yeniden doğrulayabileceği şekilde saklanması tavsiye edilir.

**Toplanacak kanıt:**

* Test ID, tarih/saat, ortam, test eden kişi ve uygulama sürümü (commit/build no).
* iyzico request ve response JSON'u (kart numarası ilk 6 + son 4 hane dışında maskeli; CVC asla loglanmamalıdır).
* `conversationId`, `paymentId`, `paymentTransactionId`, `token` değerleri.
* Ekran görüntüsü veya video: ödeme formu, 3DS sayfası, sonuç sayfası, sandbox merchant panelindeki işlem detayı.
* Webhook için alınan ham payload, header'lar ve endpoint'in döndüğü HTTP kodu.

**Hata (defect) kaydı:**

| Alan                             | İçerik                                                                               |
| -------------------------------- | ------------------------------------------------------------------------------------ |
| Başlık                           | Test ID + kısa açıklama (ör. "TC-WH-07: mükerrer webhook ikinci e-posta gönderiyor") |
| Adımlar / beklenen / gerçekleşen | Test senaryosundan kopyalanır                                                        |
| Kanıt                            | Yukarıdaki kanıt paketi                                                              |
| Önem derecesi                    | S1–S4 (aşağıda)                                                                      |
| Kaynak                           | Sizin kodunuz / iyzico / banka / test verisi                                         |

| Derece      | Tanım                                                                   | Örnek                                            | Canlıya engel mi?   |
| ----------- | ----------------------------------------------------------------------- | ------------------------------------------------ | ------------------- |
| S1 – Kritik | Para kaybı, çift çekim, ödenmemiş siparişin onaylanması, güvenlik açığı | Sahte callback ile sipariş onaylandı             | Evet                |
| S2 – Yüksek | Ana akış çalışmıyor, geçici çözüm yok                                   | 3DS sonrası sipariş `PENDING` kalıyor            | Evet                |
| S3 – Orta   | Akış çalışıyor ama hatalı mesaj/durum var                               | Yetersiz bakiyede genel hata mesajı gösteriliyor | Hayır, plan gerekir |
| S4 – Düşük  | Görsel veya metin sorunu                                                | Buton hizası bozuk                               | Hayır               |

iyzico kaynaklı olduğu düşünülen hataların; `conversationId`, `paymentId`, istek zamanı ve request/response ile birlikte <entegrasyon@iyzico.com> adresine iletilmesi tavsiye edilir (Hata Kodları, SSS – Hata Mesajları).

## Kullanıcı Kabul Testleri (UAT)

UAT, iş birimi ve operasyon ekibinin gerçek kullanım senaryolarını staging ortamında (sandbox anahtarlarıyla) uygulayıp "bu akışı müşteriye açabiliriz" onayını vermesidir. Teknik testler tamamlanmadan UAT'ın başlatılmaması tavsiye edilir.

**Katılımcılar:** Ürün sahibi, finans/muhasebe, müşteri hizmetleri, QA (kolaylaştırıcı).

| Test ID     | Kullanıcı senaryosu                                 | Kim test eder      | Kabul kriteri                                                                    |
| ----------- | --------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------- |
| `TC-UAT-01` | Müşteri kredi kartıyla tek çekim alışveriş yapar    | Ürün sahibi        | Akış anlaşılır; onay sayfası ve e-postası doğru tutarı gösterir                  |
| `TC-UAT-02` | Müşteri taksitli ödeme seçer                        | Ürün sahibi        | Taksit seçenekleri ve vade farkı doğru gösterilir                                |
| `TC-UAT-03` | Müşteri kartı reddedilir, başka kartla tekrar dener | Müşteri hizmetleri | Hata mesajı anlaşılır; ikinci denemede sepet kaybolmaz                           |
| `TC-UAT-04` | 3DS doğrulaması mobilde yapılır                     | Ürün sahibi        | Banka sayfası açılır, dönüşte sonuç sayfası görünür                              |
| `TC-UAT-05` | Müşteri hizmetleri siparişi iptal eder              | Müşteri hizmetleri | Admin panelinden iptal/iade yapılabilir; müşteriye bildirim gider                |
| `TC-UAT-06` | Kısmi iade (bir ürünün iadesi)                      | Müşteri hizmetleri | Yalnızca seçilen ürün tutarı iade edilir                                         |
| `TC-UAT-07` | Gün sonu mutabakatı                                 | Finans             | Sistem raporu ile sandbox merchant paneli / raporlama servisi toplamları eşleşir |
| `TC-UAT-08` | Şüpheli işlem (`fraudStatus = 0`)                   | Operasyon          | Sipariş sevkiyata düşmez, inceleme kuyruğuna alınır                              |

**Canlı doğrulama (production smoke test):** Canlı anahtarlarla deploy sonrası gerçek bir kartla düşük tutarlı (ör. 1 TRY) bir ödeme yapılması, webhook alımının doğrulanması ve aynı gün iptal edilmesi tavsiye edilir. Sandbox test kartları canlıda çalışmaz. iyzico'nun canlıya geçiş adımları için: Entegrasyon Kontrol Listesi.

## Test Onay (Sign-Off) Kriterleri

Entegrasyonun, aşağıdaki kriterlerin tümü karşılandığında ve imza tablosu doldurulduğunda canlıya alınması tavsiye edilir.

**Çıkış kriterleri:**

* 11.4–11.9'daki senaryoların %100'ünün çalıştırılmış olması; kapsam dışı bırakılanların gerekçesiyle listelenmesi.
* Kritik senaryoların (tüm `TC-POS`, `TC-3DS-01..05`, `TC-REF-01..03`, `TC-WH-01..04`, tüm `TC-IDM`) %100'ünün Pass olması.
* Açık S1 ve S2 hatasının bulunmaması; S3 hataları için tarihli çözüm planının olması.
* Regresyon setinin (smoke + full) son build'de yeşil olması.
* Yanıt imzası ve webhook `X-IYZ-SIGNATURE-V3` doğrulamasının aktif olması ve test edilmiş olması.
* Loglarda tam kart numarası veya CVC bulunmadığının kontrol edilmesi.
* Canlı API anahtarlarının, canlı base URL'in (`https://api.iyzipay.com`) ve canlı webhook URL'inin konfigüre edilmesi; sandbox anahtarının canlı konfigürasyonda bulunmaması.
* UAT senaryolarının (`TC-UAT-01..08`) iş birimi tarafından onaylanmış olması.
* Canlı smoke testin (ödeme + webhook + iptal) başarılı olması.
* Geri dönüş (rollback) planı ve canlı izleme/alarm (ödeme hata oranı, `PENDING` sipariş sayısı) hazır olması.
