MagicPay ödeme API referansı

API Referansı

3D Secure, sunucu tarafı durum sorgusu, webhook olayları, iadeler ve Payguru V2 için güncel yöntemleri ve alanları resmî kaynaklarla eşleştirin.

Kimlik doğrulama ve yanıt sözleşmesi

İşlem yolları aynı ödeme yaşam döngüsünü izler; kimlik doğrulama başlıklarını ve her işlemin yanıt alanlarını ayrı eşleyin.

Başlamadan önce

Test API adresi https://trdev.magicpay.ai, test paneli https://trdev-ui.magicpay.ai. API anahtarınızı ve secret değerinizi oluşturun, sanal POS bağlantınızı ekleyin. Anahtarları yalnız sunucuda tutun; test kartı bilgilerini teknik ekipten alın.

Uygulama notu: Ortamlar sayfasında canlı API/panel bağlantılarının etiketleriyle hedefleri uyuşmuyor; Authentication sayfasında V1 başlıkları iki yazımla veriliyor. Canlı adresi ve V1 imza çıktı biçimini teknik ekiple doğrulayın. Başlatma şemasındaki redirectUrl tarayıcı dönüşü, callbackUrl webhook içindir; tamamlama sayfasının giriş cümlesi bu ayrımla çelişiyor.

Kaynakta gösterilen başlık yazımları

Authentication tablosu
x-api-key
x-rnd-key
x-auth-version: V1
x-signature
Aynı sayfanın listesi
x_api_key
x_rnd_key
x_auth_version
x_signature

Kaynak; tam URL, API anahtarı, secret ve her isteğe özel rastgele değerin sırasıyla birleştirilip SHA-256 özetinin alınmasını tarif ediyor. Çıktı kodlaması ve ayraç ayrıntıları verilmediği için burada çalıştırılabilir imza uygulaması sunulmuyor.

Resmî referans

Ödeme sonucu ile doğrulama HTML’ini ayırın

Başlatma yanıtı htmlContent ve paymentId döndürür. Tamamlama ve sorguda paymentStatus üst seviyededir; örnekler data sarmalayıcısı içermez. Aşağıdaki JSON, tam yanıtın yalnız ilgili alanlarını gösterir.

Tamamlama yanıtı alanları
{
  "paymentStatus": "SUCCESS",
  "isThreeDS": true
}
Resmî referans
Sorgu yanıtı alanları · başarılı işlem kesiti
{
  "id": 123,
  "paymentStatus": "SUCCESS",
  "paidPrice": 55.0,
  "currency": "TRY"
}

Yeni referansta tamamlama ve sorgu yanıtları paymentStatus alanını üst seviyede kullanır. SUCCESS ve FAILURE ayrımını sipariş, tutar ve para birimiyle birlikte değerlendirin; belirsiz sonuçta tekrar tahsilat başlatmayın.

Resmî referans

Payguru işlemleri: V2 imza

Payguru işlem uçları x-auth-version: V2 kullanır. HTTP metodu, tam URL, ham gövdenin SHA-256 özeti, API anahtarı, Unix saniye damgası ve rastgele değer satır sonlarıyla birleştirilir. MagicPay secret ile HMAC-SHA256 sonucu küçük harfli hex olarak üretilir. V1 imzasını V2 yerine kullanmayın; zaman farkı en çok 300 saniye, rastgele değer her istekte yeni olmalıdır.

Resmî referans

Webhook ile sonuç takibi

Üye İşyeri Ayarları içinden API_AUTH, THREEDS_VERIFY, REFUND ve REFUND_TX gibi olayları seçin. Bildirimde eventType, eventTime, eventTimeStamp, status ve bankOrderId ile eşleşen payloadId bulunur. Tekrarlanan bildirimleri aynı siparişe ikinci kez uygulamayın; doğrulanmamış bir bildirimi ödeme kanıtı saymayın.

Resmî referans

Kaynak kontrolü: 10 Kasım 2026

Resmî MagicPay SDK paketleri

Sunucu uygulamanızın diline uygun paketi seçin. Kurulum komutları ve paket kayıtları aşağıda; dört SDK aynı resmî kaynak deposunda geliştirilir.

Python

magicpay · PyPI

Doğrulanan sürüm: 0.1.0

Kurulum komutu · Python
pip install magicpay

PHP

magicpay/magicpay-php · Packagist

Doğrulanan sürüm: 0.1.0

Kurulum komutu · PHP
composer require magicpay/magicpay-php

.NET

MagicPay · NuGet

Doğrulanan sürüm: 0.1.0

Kurulum komutu · .NET
dotnet add package MagicPay

Rust

magicpay · crates.io

Doğrulanan sürüm: 0.1.0

Kurulum komutu · Rust
cargo add magicpay

API anahtarınızı ve secret değerinizi sunucuda tutun. Yapılandırma ve kullanım için seçtiğiniz paketin README dosyasını ve resmî API referansını inceleyin; bu sayfa paket kurmaz veya API isteği göndermez.

Paket kaynakları kontrol edildi: 11 Kasım 2026

API referansının kapsamı

Güncel 3DS akışı

redirectUrl, üst seviyedeki paymentId ve sunucudan sonuç doğrulama.

Belgeli bildirimler

Webhook olayları ve gövde alanları; doğrulama sonucuyla tahsilatı ayırma.

Ürüne göre kimlik doğrulama

Genel API V1 ve Payguru V2 HMAC kapsamını ayrı değerlendirme.

Ö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ı

İlgili çözümler ve kaynaklar

Sık Sorulan Sorular

HTTP yanıtı ile ödeme sonucunu nasıl ayırırım?

Güncel 3DS sorgu örneklerinde üst seviyedeki paymentStatus SUCCESS veya FAILURE değerini taşır; iade örnekleri üst seviyedeki status alanını kullanır. HTTP başarısı veya tarayıcı dönüşü tek başına tahsilat kanıtı değildir. Sipariş kararını sunucuda doğrulanan işlem sonucuna göre verin.

redirectUrl ile callbackUrl arasındaki fark nedir?

Başlatma tablosu ve akış rehberi redirectUrl alanını tarayıcı dönüşü, isteğe bağlı callbackUrl alanını sunucu bildirimi için kullanır. Tamamlama sayfasındaki callbackUrl ifadesi bu kaynaklarla çelişir; teknik ekiple doğrulayın. htmlContent ve paymentId başlatma yanıtında üst seviyededir; tamamlama paymentId kullanır.

Webhook ve Payguru imzasını nereden doğrularım?

Genel webhook kaynağında olaylar ve payload alanları vardır; genel bildirim doğrulama ve tekrar sözleşmesini ayrıca doğrulatın. Payguru API isteklerinin V2 HMAC-SHA256 sözleşmesi Authentication ve Payguru kaynaklarında yer alır; bu API imzasını webhook imzası yerine kullanmayın.