Çift-yazma stratejisi öneririz. Mevcut gateway’inizi durdurmadan, kademeli olarak trafiğin %1 → %10 → %50 → %100’ünü Payven’e taşıyın. Yönlendirme kuralları ile A/B test yapabilirsiniz.
Kavram eşleştirmesi
| Sizin gateway | Payven karşılığı |
|---|---|
Craftgate: Payment + Card + Buyer | Payment (/api/v1/payments) + iç içe card + buyer |
Craftgate: paymentSource (web/mobile/marketplace) | Sanal POS: extra_properties.payment_source (opsiyonel) |
Craftgate: connectorName | Payven: connector_code (GARANTI, AKBANK, …) |
iyzico: paymentChannel (WEB/MOBILE_WEB/…) | Sanal POS: işlem normalde otomatik tespit edilir; gerekirse extra_properties.channel |
iyzico: paymentGroup (PRODUCT/LISTING/SUBSCRIPTION) | Sanal POS: description veya basket_items[] ile model |
iyzico: installmentInfo endpoint’i | Identity: BIN sorgu |
PayU: merchant, merchantPosId, salt | Identity OAuth (Bearer token) — POS bilgisi konfigürasyonda |
Param: Islem_Hash | Bizde HMAC yok — tüm güvenlik OAuth + IP whitelist üzerinden |
API alan eşleştirmesi (POST /payments)
| Sizin alan | Payven alanı | Not |
|---|---|---|
price (TL ondalık, örn. 150.00) | amount.amount (kuruş, örn. 15000) | Önemli: Payven kuruş cinsindendir |
paidPrice | yok — Payven amount.amount’i kullanır | Komisyon ayrımı yapmıyoruz |
currency: "TRY" | amount.currency: "TRY" | Aynı |
installment | installment | Aynı |
cardHolderName | card.holder_name | snake_case |
cardNumber | card.number | snake_case |
expireMonth | card.expire_month | snake_case |
expireYear | card.expire_year | 4 hane (2030), iki hane değil |
cvc / cvv | card.cvv | Aynı |
buyerEmail | buyer.email | İç içe |
buyerIp / ipAddress | buyer.ip_address | İç içe |
conversationId (iyzico) | external_id | Sizin sipariş ID’niz |
basketId | basket_id | Aynı |
callbackUrl (3DS) | callback_url (/payments/3d/init body’sinde) | Aynı |
merchantId | X-Merchant-Id header veya X-External-Merchant-Id header | Body’de değil header’da |
Yanıt eşleştirmesi
| Sizin alan | Payven alanı |
|---|---|
paymentId | transaction_id |
paymentStatus (SUCCESS/FAILURE) | HTTP status (2xx başarı, 422 banka reddi) + status enum |
errorCode (provider-spesifik) | code (Payven canonical) + provider_error_code (banka orijinali) |
authCode | extra_properties.auth_code |
hostReference / mdStatus (3DS) | extra_properties.host_reference, extra_properties.three_ds.eci |
Hata yapısı eşleştirmesi
Çoğu Türk gateway hatayı 200 OK + body’destatus: "FAILURE" ile döner. Payven RFC 9457 problem+json kullanır — HTTP status kodunu konuşturur:
| Senaryo | iyzico/Craftgate tipik | Payven |
|---|---|---|
| Banka reddi (yetersiz bakiye) | 200 OK + { status: "FAILURE", errorCode: "10051" } | 422 Unprocessable Entity + { code: "bank_declined", provider_error_code: "51" } |
| Validasyon hatası | 200 OK + { status: "FAILURE", errorCode: "100xxx" } | 422 Unprocessable Entity + { code: "validation_failed", errors: [...] } |
| Token geçersiz | 200 OK + body içinde error | 401 Unauthorized + { code: "invalid_token" } |
| Rate limit | 403/429 farklı providerlar | 429 Too Many Requests + Retry-After |
if (res.status === 200) koşulundan if (res.ok) veya if (res.status >= 200 && res.status < 300) koşuluna geçin. Hata yanıtını code alanı üzerinden okuyun, sayısal errorCode üzerinden değil.
Idempotency
| Provider | Yaklaşım |
|---|---|
| iyzico | conversationId ile dedupe (best-effort) |
| Craftgate | Idempotency-Key header desteği var |
| PayU | Yok (sipariş ID dupe kontrolü kendinize ait) |
| Payven | Idempotency-Key header zorunluk değil ama şiddetle önerilir — bkz. Idempotency |
Webhook eşleştirmesi
| Provider | Payven |
|---|---|
iyzico: paymentEventType | Payven: type (payment.completed, payment.failed, …) |
iyzico: transactionType: "AUTH" | Payven: tek event yapısı, type’tan ayırd ediyoruz |
Craftgate: eventType | Payven: type |
| HMAC imza farklı (her provider) | Payven: X-Payven-Signature: sha256=... + X-Payven-Timestamp (Stripe-benzeri) |
Geçiş sıralaması (önerilen)
Sandbox'ta paralel entegrasyon (1-3 gün)
Mevcut sisteminize dokunmadan, sandbox’ta Payven entegrasyonunu yapın. 3DS dahil tüm akışları test edin.
Production canary (1 gün)
Trafiğin %1’ini Payven’e yönlendirin (örn. belirli bir BIN, belirli bir bayi, belirli bir tutar aralığı). Yönlendirme kuralları ile yapılandırın.
Hata oranı + latency karşılaştırması (3-7 gün)
Payven
dashboard.payven.com.tr ile mevcut gateway dashboard’ını yan yana izleyin. Hata oranı, p95 latency, başarı oranı.Aşamalı geçiş %10 → %50 → %100
Her aşama 2-3 gün izleme — sorun çıkarsa yönlendirme kuralını geri alın.
Sık karşılaşılan tuzaklar
Hata kodu eşleştirme tablosu (örnek)
| Sizin sisteminizde | Payven code | Banka kodu (provider_error_code) |
|---|---|---|
iyzico 10051 (yetersiz bakiye) | insufficient_funds | 51 |
iyzico 10054 (kart süresi dolmuş) | card_expired | 54 |
iyzico 10005 (CVC hatalı) | invalid_cvv | 82 |
Craftgate BANK_DECLINED_NN | bank_declined | NN |
Param 99 (sistem hatası) | bank_system_error | 96 |
Yardım
Geçiş sırasında özel bir senaryoda takılırsanız: organizasyon kodunuz + işlemcorrelation_id ile destek ekibimize yazın. Onboarding ekibi tipik olarak 1-2 saat içinde yanıt verir.