Ödeme bağlantısını sipariş kuralları ve kullanıcı arayüzünden ayırarak kurun. Bu rehber, güncel 3DS başlatma ve tamamlama akışını, sonuç sorgusunu, webhook bildirimlerini, iadeleri ve Payguru kimlik doğrulamasını birlikte açıklar. Her bölümdeki alanları ilgili resmî kaynaktan kontrol edin; örnek yanıtı tüm ürünlere uygulanacak tek bir şema saymayın.
1. Sunucu adaptörünü ve ortamı hazırlayın
HTTP iletişimi, kimlik doğrulama, yanıt çözümleme ve ödeme referanslarını sunucu adaptöründe yönetin; sipariş kararlarını iş katmanında, gösterimi arayüzde tutun. Test API tabanı https://trdev.magicpay.ai, test paneli https://trdev-ui.magicpay.ai adresidir. API Key ve Secret Key oluşturup gerekli Sanal POS kaydını hazırlayın; ortamları, zaman aşımını ve erişim yetkilerini ayrı yapılandırın. Başlatmadan önce sipariş referansını, yanıt geldiğinde paymentId değerini kalıcı kaydedin. Loglarda yalnız referans, işlem adı, süre ve arındırılmış sonuç tutun; kart verisi, CVC, gizli anahtar, imza ve 3DS HTML içeriğini kaydetmeyin. Ortamlar sayfası test kartı listesi sunmaz; onaylı veriyi teknik ekiple belirleyin.
2. 3D Secure başlatma alanlarını eşleştirin
POST /payment/v1/card-payments/3ds-init için zorunlu alanlar price, paidPrice, installment, bankOrderId, currency, redirectUrl, items ve additionalParams olarak listelenir. Tutarı, para birimini ve kalemleri sunucudaki siparişle eşleştirin; paidPrice değeri price değerinden büyük olmamalıdır. callbackUrl, etkin bildirimlerin gönderileceği isteğe bağlı sunucu adresidir; tarayıcı dönüşü redirectUrl ile ayrılır. Başarılı başlatma örneğinde htmlContent ve paymentId üst seviyededir, paymentStatus INITIAL değerindedir. htmlContent ile banka doğrulama ekranını sunun ve paymentId değerini tamamlama için saklayın. Başlatmayı tahsilat başarısı saymayın. buyerMemberId alıcıyı, items içindeki subMerchantMemberId satıcıyı temsil eder; bu kimlikleri birbirinin yerine kullanmayın.
3. Kullanıcı dönüşünü ve tamamlamayı ayırın
Resmî akış, OTP sonrası kullanıcıyı redirectUrl adresindeki bekleme ekranına getirir; sunucu POST /payment/v1/card-payments/3ds-complete çağrısını paymentId ile yapar. Başarılı tamamlama örneğinde paymentStatus SUCCESS ve isThreeDS üst seviyededir. Yanıtı sunucuda okuyun, siparişle eşleştirin ve sonucu kalıcı kaydettikten sonra teslimat kararı verin. Yinelenen dönüşler uygulamada ikinci teslimat oluşturmamalıdır. Dar uygulama notu: Tamamlama sayfasının giriş metni tarayıcı dönüşüne callbackUrl derken başlatma tablosu ve akış sayfası redirectUrl kullanır; başlatma tablosunda callbackUrl sunucu bildirimidir. Bu adlandırma çelişkisini teknik ekiple netleştirin; yalnız tarayıcı dönüşüne veya URL parametresine güvenerek siparişi tamamlamayın.
4. Ödeme durumunu sunucudan sorgulayın
GET /payment/v1/card-payments/{id}, bilinen paymentId ile mevcut ödemeyi sorgular. Güncel örneklerde id, paymentStatus ve isThreeDS üst seviyededir; ödeme sonucu SUCCESS veya FAILURE olarak gösterilir. HTTP yanıtını iş sonucundan ayırın ve her işlem için kendi yanıt modelini kurun. Başlatmadaki INITIAL tahsilat değildir; bilinmeyen veya bekleyen durumları inceleme akışında tutun. Tamamlama yanıtı kaybolursa yeni ödeme açmadan önce bilinen ödemeyi sunucudan sorgulayın. Kimlik bilinmiyorsa sipariş referansını ve son gözlenen aşamayı koruyup operasyon incelemesine yönlendirin. Ağ zaman aşımını otomatik ret saymayın; tekrar deneme kararını mevcut işlemle uzlaştırdıktan sonra verin.
5. Webhook olaylarını siparişle ilişkilendirin
Webhook ve Callback Bildirim Ayarları artık olay listesini ve POST gövdesini açıklar. API_AUTH, API_VERIFY_AND_AUTH, CHECKOUTFORM_AUTH, THREEDS_VERIFY, REFUND, REFUND_TX, PAYOUT_COMPLETED, WALLET_CREATED ve WALLET_TX_CREATED olayları listelenir. Gövde alanları eventType, eventTime, eventTimeStamp, status ve payloadId şeklindedir; payloadId istekte gönderilen banka sipariş referansına karşılık gelir. Panelde gerekli olayları açın, alıcıyı sunucuda çalıştırın ve gelen referansı yerel siparişle eşleştirin. THREEDS_VERIFY doğrulama sonucudur, tek başına tahsilat kanıtı değildir. Genel bildirim sayfası imza doğrulama veya teslimat-tekrar sözleşmesini belirtmez; bu ayrıntıları doğrulatın ve ödeme kararını sunucu durum sorgusuyla destekleyin. Hoppa webhook imzasını veya Payguru API imzasını genel webhook sözleşmesi yerine kullanmayın.
6. Tam ve kısmi iadeyi ayrı yönetin
POST /payment/v1/refunds, paymentId ile kalan iade edilebilir tutarın tamamını iade eder. refundReason ve refundReasonDescription isteğe bağlıdır; neden verilmezse OTHER kullanılır. Kısmi iade için POST /payment/v1/refund-transactions çağrısında paymentTransactionId ve refundPrice zorunludur; tutar sıfırdan büyük ve kalan iade edilebilir tutarı aşmayacak şekilde doğrulanmalıdır. Bu uçta refundDestinationType isteğe bağlıdır ve varsayılanı PROVIDER olarak belgelenir. Güncel iade yanıtlarında status üst seviyede SUCCESS veya FAILURE değerindedir. Ödeme, ödeme işlemi ve iade kimliklerini ayrı saklayın; HTTP yanıtını iadenin tamamlandığına tek başına kanıt saymayın. Belirsiz yanıtta tekrar iade başlatmadan önce sonucu uzlaştırın; ürünün iade kısıtlarını da kontrol edin.
7. Payguru için V2 HMAC sözleşmesini kullanın
Genel API ve 3DS çağrılarında V1 desteği sürer; Payguru işlem uçları için x-auth-version: V2 kullanılır. Authentication kaynağı V2 için x-api-key, x-rnd-key, x-timestamp ve x-signature başlıklarını; MagicPay gizli anahtarıyla HMAC-SHA256 imzasını tanımlar. İmzalanacak metin sırasıyla büyük harf HTTP yöntemi, sorgu dahil tam HTTPS URL, ham gövdenin küçük harf hex SHA-256 özeti, API anahtarı, Unix saniye zaman damgası ve rastgele değerden oluşur; alanlar satır sonuyla ayrılır. İmza küçük harf hex biçimindedir. Boş gövdenin de özeti alınır; saat farkı en fazla 300 saniyedir ve rastgele değer tekrar kullanılmaz. Payguru servis anahtarını kullanmayın. Hesaptan Öde ve Para Transferi dev işlemleri gerçek ücret doğurabilir; ödeme/iadede bekleyen sonucu tamamlanmış saymayın.
8. Kabul testlerini ve kaynak çelişkilerini kapatın
Başarılı ve başarısız ödeme, yarıda kalan OTP, tekrarlanan tarayıcı dönüşü, geciken bildirim, bozuk yanıt, zaman aşımı ve kaybolan iade yanıtını ayrı test edin. Her senaryoda sipariş kararını, kurtarma adımını ve gizli veri içermeyen kanıtı kaydedin. Uygulamanın tekrar güvenli davranmasını doğrulayın; bunu API genelinde idempotency garantisi olarak sunmayın. Authentication tablosundaki tireli başlıklar ile aynı sayfadaki alt çizgili adlar tutarsızdır; kabul edilen yazımı ve test vektörünü teknik ekiple doğrulayın. Ortamlar sayfasındaki canlı API/panel metinleri ve bağlantı hedefleri ters eşleşir; canlı adresi tahmin etmeyin. Test kabulü, yayın onayı, izleme sorumluluğu ve geri dönüş planını ayrı kapatın. Güncel belgelerde ayrı bir non-3DS kart ödeme oluşturma sayfası yoktur; burada böyle bir doğrudan çağrı önerilmez.
Resmi API kaynakları
- Test API ve panel ortamları
- V1 ve Payguru V2 kimlik doğrulama
- 3DS başlatma alanları ve yanıtı
- 3DS tarayıcı ve sunucu akışı
- 3DS tamamlama ve paymentId
- Ödeme sorgusu ve paymentStatus
- Webhook olayları ve payload alanları
- Ödeme düzeyinde tam iade
- İşlem düzeyinde kısmi iade
- Payguru ürünleri ve V2 işlemleri