Secure (3D) Ödeme
3D Secure ödeme iki uç ve bir dönüş isteğinden oluşur:
- Başlatma — Sunucunuz
secure-paymentçağırır. Kart verisi bu isteğin gövdesindedir. Başarılı yanıtresult.redirect_urlvetransaction.tokendöner. - Yönlendirme — Müşterinin tarayıcısını
result.redirect_urladresine 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. - Dönüş — 3D Secure adımı bitince gateway ödemeyi tamamlar ve tarayıcı
callback_urladresinize bir formPOSTeder:transaction_token,reference,successful. Bkz. Dönüş POST'u. Paneldetransaction.*olaylarına adres tanımladıysanız gateway sunucusu da o adrese webhook gönderir. - Sonuç — Sunucunuz
transaction_tokenileretrieve-paymentsçağırır. Ödemenin durumunu yalnızca bu imzalı yanıttakiresult.successfuldeğerine göre değiştirin.
1. Başlatma
Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak. customer ve card nesnelerinin tam hâli: secure-payment.
- PHP
- Node.js
- Python
- Java
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;
const payment = await client.securePayment({
reference: 'SIP-10231',
amount: '450.00',
installmentNumber: 1,
ip: req.ip,
callbackUrl: 'https://magazam.com/odeme/donus',
customer,
card,
});
if (!payment.result.successful) {
// payment.result.message
return;
}
req.session.transactionToken = payment.transaction.token;
res.redirect(payment.redirectUrl!);
from odemehub.request import SecurePayment
payment = client.secure_payment(SecurePayment(
reference="SIP-10231",
amount="450.00",
installment_number=1,
ip=request.remote_addr,
customer=customer,
callback_url="https://magazam.com/odeme/donus",
card=card,
))
if not payment.result.successful:
... # payment.result.message
session["transaction_token"] = payment.transaction.token
return redirect(payment.redirect_url)
import com.odemehub.request.SecurePayment;
var payment = client.securePayment(SecurePayment.builder()
.reference("SIP-10231")
.amount("450.00")
.installmentNumber(1)
.ip(request.getRemoteAddr())
.callbackUrl("https://magazam.com/odeme/donus")
.customer(customer)
.card(card)
.build());
if (!payment.getResult().isSuccessful()) {
// payment.getResult().getMessage()
}
session.setAttribute("transactionToken", payment.getTransaction().getToken());
return "redirect:" + payment.getRedirectUrl();
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ı).
| Durum | Davranış |
|---|---|
| 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:
| Alan | Açı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ç
- PHP
- Node.js
- Python
- Java
use Gurmehub\Odemehub\Request\RetrievePayments;
$payment = $client->retrievePayments(RetrievePayments::byToken($_POST['transaction_token']))->payments[0] ?? null;
if ($payment?->isSuccessful()) {
// ödendi
} else {
// $payment?->errorMessage
}
const [payment] = (await client.retrievePayments({ token: req.body.transaction_token })).payments;
if (payment?.isSuccessful()) {
// ödendi
} else {
// payment?.errorMessage
}
from odemehub.request import RetrievePayments
payments = client.retrieve_payments(RetrievePayments(token=request.form["transaction_token"])).payments
if payments and payments[0].is_successful():
... # ödendi
else:
... # payments[0].error_message
import com.odemehub.request.RetrievePayments;
var payments = client.retrievePayments(RetrievePayments.byToken(transactionToken)).getPayments();
if (!payments.isEmpty() && payments.get(0).isSuccessful()) {
// ödendi
} else {
// payments.get(0).getErrorMessage()
}
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
cardyerinetransaction.saved_card_tokengönderin; akış aynıdır. Bkz. Kayıtlı Kartlar. - Kartı saklamak için
card.should_save: truegönderin. Kart ödeme tamamlandığında saklanır; token'ıretrieve-paymentsyanıtınınsaved_cardalanında döner.
Kontrol listesi
transaction.tokendeğerini başlatma yanıtından saklayın; iade, iptal ve sorguda kullanılır.redirect_urladresine 15 dakika içinde yönlendirin.- Ödemenin durumunu dönüş formundaki
successfulalanına göre değil,retrieve-paymentsyanıtına göre değiştirin. - Dönüş işleyicisi aynı
transaction_tokenile 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 sonucuretrieve-paymentsiletransaction.tokenya da yalnızca referansınız varsareferencegöndererek sorun.