Test Etme

Bu uçları kim çağırır?Dış API (s2s)

Taban yol: /api/v1/wallet
Kimlik: Ed25519 istek imzası — X-Key-Id, X-Date, X-Nonce, Digest (body varsa), X-Signature. Zaman penceresi ±5 dk, nonce tek kullanımlık, anahtarda IP allow-list olabilir.
Yetki: Anahtarınız cüzdan ürününü ve çağrının gerektirdiği cüzdan iznini taşımalıdır; izni olmayan çağrı 403 WALLET_INSUFFICIENT_SCOPE alır. Uç başına izinler: Anahtar izinleri.
Çapraz yüzey: Bu uçlar zaten s2s yüzeyindedir — kendi sunucunuzdan imzalı olarak çağırabilirsiniz.

Cüzdan entegrasyonunu iki katmanda sınayın: önce imzalama ve sözleşme, sonra para akışı.

TEST ve LIVE anahtarları

API anahtarlarınızın bir ortamı vardır: TEST veya LIVE. Ortam anahtarın kimliğine gömülüdür ve karıştırılamaz.

⚠️

TEST anahtarıyla LIVE bir kaynağa (ya da tersi) erişmeye çalışmak reddedilir. "Yanlışlıkla canlıda test ettim" durumu bu ayrımla engellenir — ortamı istekte belirtmezsiniz, anahtar belirler.

Panelden her iki ortam için ayrı anahtar üretin ve uygulamanızda ortam değişkeniyle seçin. Aynı anahtarı iki ortamda kullanmaya çalışmayın.

Katman 1 — imzalama ve sözleşme

Para hareketine geçmeden önce imzanızın doğru olduğunu kanıtlayın:

`ping` ile başlayın

GET /api/v1/wallet/ping

Body taşımaz ve Idempotency-Key gerektirmez; anahtarınızda bir kurulum izni (wallet:program:manage veya wallet:enduser:manage) bulunmalıdır. 200 alana kadar başka bir şey denemeyin.

Query string'li bir uç deneyin

GET /api/v1/wallet/operations?limit=1

Bu, kanonik string'in ikinci satırına query string'i de koyduğunuzu doğrular — en sık yapılan imza hatası budur.

Body'li bir uç deneyin

POST /api/v1/wallet/wallets/lookup

Bu da Digest header'ınızın doğru olduğunu kanıtlar: body boşluksuz JSON olarak gider ve digest tam olarak o metin üzerinden hesaplanır.

Hata kodlarının anlamı: Kimlik Doğrulama.

Katman 2 — kapalı devre para akışı

Aşağıdaki senaryolar bağlı bir dış sağlayıcı gerektirmez ve uçtan uca sınanabilir:

Senaryo	Ne doğrular
Kullanıcı oluşturun → aynı telefonla tekrar oluşturun	Telefon tekilleştirmesi
Hesap açın → bakiye okuyun	Hesap/para birimi modeli
Kart yükleme başlatın → formu açın → tamamlayın	Yükleme akışı ve webhook
Aynı `Idempotency-Key` ile yüklemeyi tekrar gönderin	Idempotency davranışı
W2W quote → init → complete	Transfer akışı, OTP, `integrityHash`
`complete`'i yanlış `nonce` ile deneyin	Doğrulama kapısı
Bakiyeden fazla transfer deneyin	`sufficientBalance` ve red davranışı
Limit üstü transfer deneyin	`limitBlocked` davranışı
Cüzdanla ödeme → müşteri onayı	Ödeme akışı
QR üretin → parse → ödeyin	QR akışı
Webhook imzasını doğrulayın	İmza hesabınız

Idempotency testini mutlaka yapın: aynı anahtarla ikinci isteği gönderdiğinizde ikinci bir operasyon oluşmamalı, ilk yanıt dönmelidir. Bu davranışı doğrulamadan canlıya çıkmak, ağ hatası anında çifte para hareketi riski demektir.

Simülatörler ve senaryolar

Dış sağlayıcı uçlarının arkasında deterministik simülatörler durur. Amaçları mutlu yolu göstermek değil, hata yollarını sınatmaktır: zaman aşımı, geç onay, tekrar ve asılı kalma senaryolarını gerçek bir kuruma bağlanmadan üretebilirsiniz.

Beş simülatör vardır:

Simülatör	Neyi taklit eder	Senaryo seçicisi
TestBank	Banka entegrasyonu (çekim, IBAN transferi, IBAN toplu ödeme, IBAN sahiplik doğrulaması)	Hedef IBAN'ın son 4 hanesi
TestATM	ATM / QR nakit çekim ağı	Nakit çekim kod kimliğinin son 4 hanesi
TestBiller	Fatura kurumu (sorgulama + ödeme)	Abone numarasının son 4 hanesi
TestIssuer	Kart ihraççısı (kart basma + otorizasyon)	Aşağıdaki nota bakın — kart numarası DEĞİL
TestExchange	Kripto swap kuru	Senaryo yok — sabit, deterministik bir fiyat tablosu

Simülatörü programınıza bağlama

Simülatörler panelde birinci sınıf entegrasyon olarak durur: Entegrasyonlar ekranında kartlarını görür ve programınıza tıpkı gerçek bir kurum gibi bağlarsınız. Ayrı bir "test ortamı" ya da ikinci bir hesap yoktur — bağlarsınız, çalışır.

Panel kartı	Kategori	Neyi açar
Test Bankası	Banka entegrasyonu	Havale ile yükleme, bankaya çekim, IBAN transferi, IBAN hedefli toplu ödeme
Test ATM Ağı	ATM ağı	ATM ve QR ile nakit çekim
Test Fatura Kurumu	Fatura kurumu	Fatura sorgulama ve ödeme
Test Kart İhraççısı	Kart ihraççısı	Kart basma, otorizasyon, settle, dondurma/iptal
Test Borsa	Kripto	Fiat↔kripto swap

Senaryoların hepsi açıktır — açılacak bir anahtar, istenecek bir ayar yoktur. Aşağıdaki tablolardaki her senaryo, entegrasyonu bağladığınız anda çalışır. Senaryo seçimi istek verinizle yapılır (IBAN'ın son 4 hanesi, abone numarası, senaryo ipucu alanı); bu, bir ortam ayarı değil sizin kontrolünüzdedir.

⚠️

Bağlamadığınız kategori çalışmaz, sessizce simüle de edilmez — istek açık bir hatayla reddedilir. Bu bilinçlidir: "bağlı sağlayıcım yokken işlem başarılı göründü" durumu, canlıya çıktığınızda paranın gerçekte hiç hareket etmediğini geç fark etmeniz demektir.

Bu entegrasyonlar gerçek kurumlar gibi bağlanır ve gerçek kod yolunu koşturur, ama gerçek para taşımaz, gerçek kart basmaz, dışarıya emir iletmezler — adlarındaki "Test" bunu söyler.

TestBank

Son 4	Davranış
`0001`	SUCCESS — kabul edilir, mutabakata geçer
`0002`	REJECT — banka reddi
`0003`	TIMEOUT — gönderim zaman aşımına uğrar; banka referansı yoktur, durum bilinmez
`0004`	LATE_APPROVE — kabul edilir, bir süre beklemede kalır, sonra mutabık olur
`0005`	DUPLICATE — tekrarlı gönderim senaryosu
`0006`	HUNG — kabul edilir ama hiç sonuçlanmaz, kalıcı olarak beklemede kalır

IBAN sahiplik doğrulaması ayrı bir eksendir ve kendi son-4 değerlerini kullanır:

Son 4	Davranış
`0007`	Hesap sahibi üçüncü şahıs (kullanıcının kendisi değil)
`0008`	Sahiplik doğrulanamaz
diğer	Hesap kullanıcının kendisine ait

0006 (HUNG) simülatörün kendisi tarafından AWAITING_RECON yapılmaz — simülatör sonsuza dek "beklemede" der ve operasyonu AWAITING_RECON'a çeken, tüketici tarafındaki bekleme eşiğidir. Test ederken beklemeniz gereken de tam olarak budur: bu senaryo AWAITING_RECON kuyruğunuzun ve müdahale ekranınızın çalıştığını kanıtlar.

0007 / 0008 yalnız sahiplik doğrulama yolunu etkiler; para gönderim senaryolarının tablosuna girmezler.

TestATM

Son 4	Davranış
`0001`	DISPENSE_OK — para verildi
`0002`	DECLINE — ATM reddi
`0003`	TIMEOUT — onay zaman aşımı; durum bilinmez
`0004`	LATE_DISPENSE — önce beklemede, sonra verildi
`0005`	DUPLICATE — tekrarlı onay

TestBiller

Son 4	Davranış
`0001`	SUCCESS — kabul, sonra onaylandı
`0002`	REJECT — kurum reddi
`0003`	TIMEOUT — zaman aşımı; durum bilinmez
`0004`	LATE_CONFIRM — kabul, bir süre beklemede, sonra onay
`0005`	DUPLICATE — tekrarlı ödeme
`0006`	HUNG — kabul edilir, hiç sonuçlanmaz
`0009`	Borç yok — fatura sorgulaması "bulunamadı" döner

⚠️

0009 yalnız sorgulama ucunu etkiler. Aynı abone numarasıyla doğrudan ödeme çağırırsanız simülatör başarılı yanıt verir. Yani 0009 "bu aboneye ödeme yapılamaz" senaryosu değil, "sorgulamada borç çıkmaz" senaryosudur.

TestIssuer

Son 4	Davranış
`0002`	AUTH_DECLINE — otorizasyon reddi
`0003`	ISSUE_FAIL — kart basımı reddedilir
diğer	APPROVE — basım ve otorizasyon başarılı

Senaryoyu iki yoldan seçebilirsiniz — önerilen yol açık ipucudur:

{ "providerScenarioHint": "ISSUE_FAIL" }

Geçerli değerler: APPROVE, ISSUE_FAIL, AUTH_DECLINE. İpucu gönderdiğinizde son-4 kuralı hiç devreye girmez; ne sınadığınız istekte açıkça yazar.

⚠️

İpucu göndermezseniz TestIssuer senaryoyu kart numarasından okumaz: kart basımında Idempotency-Key içindeki rakamların son 4'ü, otorizasyonda ise ağ otorizasyon referansının son 4 rakamı kullanılır. Bu yüzden ipucu alanını kullanmak hem daha okunaklı hem daha az kırılgandır.

İki senaryo iki farklı yolu etkiler ve çapraz kullanım etkisizdir: basım sırasında AUTH_DECLINE çözülse bile kart basılır, otorizasyon sırasında ISSUE_FAIL çözülse bile otorizasyon onaylanır.

TestExchange

TestExchange'in senaryosu yoktur. Sabit ve deterministik bir fiyat tablosu, sabit bir marj ve sıfır kayma ile çalışır; kotasyon ile onay her zaman aynı kuru verir ve dışarıya hiçbir emir iletilmez. Kur mantığınızı ve yuvarlamayı sınamak için uygundur; bir borsa entegrasyonunun hata yollarını sınamak için değildir.

Kripto uçları (swap ve kripto transfer) varsayılan olarak kapalıdır; kapalıyken WALLET_CRYPTO_DISABLED döner. Ortamınızda açılması için hesap yöneticinizle iletişime geçin. Açık olduğunda kripto işlemleri diğer para çıkışlarıyla aynı risk, yaptırım, limit ve step-up kontrollerinden geçer.

Gelen havale/EFT simülasyonu

Havale ile yükleme uçtan uca sınanabilir: kullanıcıya özel yatırma talimatını üretir, sonra "o talimata para geldi" olayını kendiniz tetiklersiniz.

POST /api/v1/wallet/bank-integrations/inbound-credits

Bu çağrı anahtarınızda wallet:bank-payout:operate izni gerektirir.

Alan	Tip	Zorunlu	Açıklama
`programId`	string	✅
`railId`	string	✅	Programa bağlı banka entegrasyonunun kodu (ör. `TESTBANK`)
`amount`	string	✅	Minor-unit
`currency`	string	✅
`rawReference`	string	✅	Havale açıklaması — yatırma referansı bu alandan eşleştirilir
`senderName` · `senderIban`	string	—	Gönderen bilgisi
`creditedIban`	string	—	Sanal IBAN modunda paranın düştüğü hesap
`receiptNumber`	string	—	Banka satır kimliği. Boş = üretilir; aynısını ikinci kez gönderirseniz mükerrer satır davranışını sınarsınız

{ "status": "success", "code": "SUCCESS", "data": { "receiptNumber": "SIM-3f9c…", "railId": "TESTBANK", "valueDate": "2026-08-13T00:41:13.402Z" } }

Enjekte ettiğiniz satır gerçek yolun aynısından geçer: gelen para tarayıcısı onu ekstreden okur, referansı talimatlarla eşleştirir ve ya cüzdana kredi geçer ya da askıda fon kuyruğuna düşürür. Yani sınadığınız şey üretimde koşacak kodun kendisidir.

Sınamaya değer üç senaryo:

Ne gönderirsiniz	Ne kanıtlarsınız
`rawReference` içinde geçerli bir yatırma referansı + `senderName`	Eşleşme → cüzdana kredi + `wallet.topup.completed` webhook'u
`rawReference` içinde tanınmayan bir metin	Askıda fon kuyruğu ve müdahale ekranınız
Doğru referans ama `senderName` boş	Üçüncü şahıs incelemesi — para otomatik kredilenmez
Aynı `receiptNumber` ile ikinci kez	Mükerrer satır tekilleştirmesi — çift kredi olmamalı

⚠️

Üçüncü sıra sürpriz gibi görünebilir ama bilinçlidir: referansı bilen herkes parayı o cüzdana sokabilseydi, referansı sızan bir kullanıcının hesabına başkasının parası yönlendirilebilirdi. Gönderenin hesap sahibi olduğu kurulamadığında sistem otomatik kredilemez, operatör incelemesine bırakır. Entegrasyonunuzu kurarken bu senaryoyu da geçin — canlıda karşılaşacaksınız.

⚠️

Bu uç yalnız gelen para simülasyonunu destekleyen bir banka entegrasyonuna bağlı programlarda çalışır. Gerçek bir sağlayıcıya bağlıysanız WALLET_INBOUND_SIMULATION_NOT_SUPPORTED ile reddedilir — gerçek bir bankaya "bana para geldi say" dedirtilemez, o yüzden bu yetenek üretimde kendiliğinden ölüdür. Bağlama yoksa WALLET_BANK_RAIL_NOT_BOUND döner.

Simülatörle sınanamayanlar

🚫

Aşağıdaki iki konu bugün uçtan uca denenemez. Entegrasyon planınızı bunları deneyebileceğinizi varsayarak kurmayın.

1. Gerçek kart basımı

TestIssuer gerçek bir kart üretmez: opak bir kart tokeni, deterministik bir sözde son-4 ve maskeli bir görünüm döner. Ham PAN hiçbir zaman üretilmez ve hiçbir yanıtta yer almaz. Kart akışınızın durum makinesini ve otorizasyon reddini sınayabilirsiniz; basılmış bir kartı fiziksel veya sanal olarak kullanamazsınız.

2. TR Karekod birlikte çalışabilirliği

QR bugün kapalı devredir ve dışarıdan bir okuyucu yoktur. Ürettiğiniz kodu başka bir banka veya ödeme uygulamasıyla okutarak sınayamazsınız. Standart uyumu iddia edilmez — ayrıntı: Yol Haritası.

Simülatör neyi kanıtlar, neyi kanıtlamaz

Simülatörle sınadığınız şey sizin tarafınızdır: durum makineniz, kuyruklarınız, idempotency'niz, arayüzünüz. Kanıtlamadığı şey kurumun gerçek davranışıdır — gerçek bir bankanın red kodları, gerçek bir fatura kurumunun borç formatı, gerçek bir ATM ağının zamanlaması simülatörün ürettiğiyle birebir aynı olmayacaktır.

Pratikte bu ayrım şu anlama gelir: entegrasyonunuzu simülatörle bitirebilirsiniz, ama canlıya geçerken ilk gün gerçek sağlayıcının hata kodlarını haritalamak için bir pencere bırakın.

Bu akışlar için bugün yapabilecekleriniz:

İstek gövdelerinizi ve durum makinesi işleyişinizi sözleşmeye göre yazın.
BANK_PROCESSING, AWAITING_RECON, HELD durumlarını yukarıdaki senaryolarla gerçekten üretip arayüzünüzü test edin — bu durumları "başarısız" göstermediğinizden emin olun.
Webhook tüketicinizi bu olay tipleri için baştan hazırlayın.

Canlı öncesi kontrol listesi

Yaygın hatalar

Durum	Sebep	Çözüm
TEST anahtarı canlıda çalışmıyor	Ortam ayrımı	Doğru ortamın anahtarını kullanın
İmza yalnız bazı uçlarda tutmuyor	Query string imzalanmamış	Kanonik stringin 2. satırına tam path'i koyun
Idempotency testi ikinci işlem üretti	Anahtar yeniden üretilmiş	Anahtarı sabitleyin

Veri Saklama ve Hukuki Askı Genel Bakış