Ana içeriğe geç

Secure (3D) Ödeme

3D Secure ödeme iki uç ve bir dönüş isteğinden oluşur:

  1. Başlatma — Sunucunuz secure-payment çağırır. Kart verisi bu isteğin gövdesindedir. Başarılı yanıt result.redirect_url ve transaction.token döner.
  2. Yönlendirme — Müşterinin tarayıcısını result.redirect_url adresine yönlendirirsiniz. Bu adres gateway'e aittir ve sağlayıcının 3D Secure formunu sunar. Adres bir kez açılır; 15 dakika içinde açılmazsa ödemenin süresi dolar.
  3. Dönüş — 3D Secure adımı bitince gateway ödemeyi tamamlar ve tarayıcı callback_url adresinize bir form POST eder: transaction_token, reference, successful. Bkz. Dönüş POST'u. Panelde transaction.* olaylarına adres tanımladıysanız gateway sunucusu da o adrese webhook gönderir.
  4. Sonuç — Sunucunuz transaction_token ile retrieve-payments çağırır. Ödemenin durumunu yalnızca bu imzalı yanıttaki result.successful değerine göre değiştirin.

1. Başlatma​

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak. customer ve card nesnelerinin tam hâli: secure-payment.

use Gurmehub\Odemehub\Request\SecurePayment;

$payment = $client->securePayment(new SecurePayment(
reference: 'SIP-10231',
amount: '450.00',
installmentNumber: 1,
ip: $_SERVER['REMOTE_ADDR'],
customer: $customer,
callbackUrl: 'https://magazam.com/odeme/donus',
card: $card,
));

if (! $payment->result->successful) {
// $payment->result->message
return;
}

// transaction.token dönüşte eşleştirmek için saklanır
$_SESSION['transaction_token'] = $payment->transaction->token;

header('Location: '.$payment->redirectUrl);
exit;

result.successful: true ödemenin alındığını göstermez; yalnızca 3D Secure işleminin başlatıldığını gösterir. false ise redirect_url null'dır ve ödeme başlatılmamıştır.

2. Yönlendirme​

result.redirect_url bir gateway adresidir (https://sandbox.odemehub.com/gateway/secure/{transaction.token}). Tarayıcıyı bu adrese yönlendirin (HTTP 302 ya da bağlantı).

DurumDavranış
Adres 15 dakika içinde açıldıSağlayıcının 3D Secure formu sunulur.
Adres 15 dakika içinde açılmadıÖdemenin süresi dolar (transaction.status: expired). Adres sonradan açılırsa tarayıcı doğrudan callback_url adresine successful=0 ile gönderilir.
Adres ikinci kez açıldıForm yeniden sunulmaz (404).

3. Dönüş​

callback_url adresinize application/x-www-form-urlencoded bir POST gelir:

AlanAçıklama
transaction_tokenÖdemenin token'ı. Sakladığınız transaction.token ile eşleştirin.
referenceÖdemenin reference değeri.
successful"1" ya da "0". İmzasızdır; sonuç olarak kullanılmaz.

Bu istek müşterinin tarayıcısından, gateway'in sayfasından gönderilen bir formdur. Ayrıntılar: Dönüş POST'u.

4. Sonuç​

use Gurmehub\Odemehub\Request\RetrievePayments;

$payment = $client->retrievePayments(RetrievePayments::byToken($_POST['transaction_token']))->payments[0] ?? null;

if ($payment?->isSuccessful()) {
// ödendi
} else {
// $payment?->errorMessage
}

retrieve-payments yanıtı ödemeyi bütünüyle taşır: status, payment_status, amount, currency, installment_number, ret nedeni (error_message) ve diğerleri. Bkz. İşlem nesnesi. Token'la sorulan ödeme listede tek kayıttır; token çalışma alanınıza ait değilse liste boştur.

Kayıtlı kartla ve kart saklayarak​

  • Kayıtlı kartla ödemede card yerine transaction.saved_card_token gönderin; akış aynıdır. Bkz. Kayıtlı Kartlar.
  • Kartı saklamak için card.should_save: true gönderin. Kart ödeme tamamlandığında saklanır; token'ı retrieve-payments yanıtının saved_card alanında döner.

Kontrol listesi​

  • transaction.token değerini başlatma yanıtından saklayın; iade, iptal ve sorguda kullanılır.
  • redirect_url adresine 15 dakika içinde yönlendirin.
  • Ödemenin durumunu dönüş formundaki successful alanına göre değil, retrieve-payments yanıtına göre değiştirin.
  • Dönüş işleyicisi aynı transaction_token ile birden fazla kez çağrılabilir.
  • Müşteri sekmeyi kapatırsa dönüş gelmez: panelde Ödeme Ayarları → Webhook sayfasında transaction.* webhook'u tanımlayın ya da sonucu retrieve-payments ile transaction.token ya da yalnızca referansınız varsa reference göndererek sorun.