Ana içeriğe geç

secure-payment

POST /api/{team}/gateway/secure-payment

3D Secure ile işlenecek bir ödeme başlatır. Kart verisi bu isteğin gövdesinde gönderilir. Yanıt ödemenin sonucu değildir: başarılı yanıt, müşterinin yönlendirileceği result.redirect_url adresini döner. Sonuç, dönüşten sonra retrieve-payments ile alınır. Akış: Secure (3D) Ödeme rehberi.

Kimlik doğrulama​

X-Api-Key: key_...
X-Timestamp: 1790932530
X-Signature: <imza>
Content-Type: application/json

Ayrıntılar: Kimlik Doğrulama ve İmza. Uç, ödeme sınırına (dakikada 60) tabidir.

İstek​

{
"transaction": {
"reference": "SIP-10231",
"amount": "450.00",
"installment_number": 1,
"ip": "85.105.10.20",
"callback_url": "https://magazam.com/odeme/donus"
},
"customer": {
"reference": "musteri-88",
"billing_address": {
"firstname": "Ahmet",
"lastname": "Yılmaz",
"email": "[email protected]",
"phone": "05551112233",
"address": "Kızılırmak Mah. Dumlupınar Blv. No:3",
"district": "Çankaya",
"province": "Ankara",
"country": "TR"
}
},
"card": {
"holder_name": "AHMET YILMAZ",
"number": "5400360000000003",
"security_code": "000",
"expiry_month": "12",
"expiry_year": "2030"
}
}

transaction​

AlanTipZorunluAçıklama
referencestringevetÖdemenin sizin sisteminizdeki referansı. En çok 255 karakter, en az bir rakam.
amountstringevetKarttan çekilecek tutar: "450", "450.5" ya da "450.50". Sıfırdan büyük, en fazla 10000000.00.
base_amountstringhayırSatılan tutar (vade farkı hariç). Sıfırdan büyük, amount değerinden büyük olamaz. Gönderilmezse amount. Bkz. Taksit ve Kur Çevirisi.
currencystringhayırTRY, USD, EUR, GBP. Gönderilmezse TRY. Ödeme hesabının bu para biriminde işlem alması gerekir.
installment_numberintegerevet1–12. 1'den büyük değer yalnızca TRY ile istenip TRY olarak çekilen ödemede kabul edilir.
ipstringevetMüşterinin IP adresi (IPv4 ya da IPv6).
callback_urlstringevetDönüş POST'unun gönderileceği adres. https ile başlayan, herkese açık bir adres; en çok 2048 karakter. Sandbox'ta http ve localhost da kabul edilir.
payment_provider_tokenstring (UUID)hayırÖdeme hesabı. Gönderilmezse ödeme hesabı seçimi uygulanır. saved_card_token ile birlikte gönderilmez.
saved_card_tokenstring (UUID)hayırKayıtlı kartla ödeme. Gönderilirse card ve payment_provider_token gönderilmez; ödeme kartın saklandığı hesaptan alınır. Bkz. Kayıtlı Kartlar.

customer​

Zorunlu. billing_address altındaki sekiz kişi alanı (firstname, lastname, email, phone, address, district, province, country) zorunludur; reference isteğe bağlıdır. Kart saklanacaksa ya da kayıtlı kartla ödeniyorsa reference gönderilir. Alanlar: customer nesnesi.

Varsayılan Ödeyen açıksa customer, billing_address ve sekiz kişi alanının her biri isteğe bağlıdır. Gönderilmeyen alanlar ödeme sağlayıcısına varsayılan ödeyenin bilgisiyle gider; reference için yukarıdaki koşul değişmez.

card​

transaction.saved_card_token gönderilmediğinde zorunludur.

AlanTipZorunluAçıklama
holder_namestringevetKart sahibinin adı. En çok 255 karakter.
numberstringevetKart numarası. Rakam ve boşluk; boşluklar çıkarıldıktan sonra 12–19 hane.
security_codestringevet3–4 rakam.
expiry_monthstringevet"01"–"12".
expiry_yearstringevet4 rakam: "2030".
should_savebooleanhayırtrue ise ödeme başarılı olduğunda kart saklanır. customer.reference gerekir; Kayıtlı Kartlar modülünün açık olması ve ödeme hesabının kart saklaması gerekir.

SDK örnekleri​

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.

use Gurmehub\Odemehub\Request\{Address, Card, PaymentCustomer, SecurePayment};

$payment = $client->securePayment(new SecurePayment(
reference: 'SIP-10231',
amount: '450.00',
installmentNumber: 1,
ip: $_SERVER['REMOTE_ADDR'],
customer: new PaymentCustomer(
reference: 'musteri-88',
billingAddress: new Address(
firstname: 'Ahmet', lastname: 'Yılmaz',
email: '[email protected]', phone: '05551112233',
address: 'Kızılırmak Mah. Dumlupınar Blv. No:3',
district: 'Çankaya', province: 'Ankara', country: 'TR',
),
),
callbackUrl: 'https://magazam.com/odeme/donus',
card: new Card(
holderName: 'AHMET YILMAZ',
number: '5400360000000003',
expiryMonth: '12',
expiryYear: '2030',
securityCode: '000',
),
));

if ($payment->redirectUrl !== null) {
header('Location: '.$payment->redirectUrl);
}

Yanıt​

Başlatma başarılı:

{
"result": {
"successful": true,
"message": null,
"redirect_url": "https://sandbox.odemehub.com/gateway/secure/0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d"
},
"transaction": {
"token": "0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d",
"reference": "SIP-10231",
"status": "redirected_to_secure_page",
"payment_status": "unpaid",
"security_type": "secure",
"amount": "450.00",
"base_amount": "450.00",
"currency": "TRY",
"installment_number": 1,
"is_test": false,
"created_at": "2026-10-02T09:15:30.000000Z",
"order": null,
"payment_link": null,
"link_payment": null,
"subscription": null
},
"customer": {
"reference": "musteri-88",
"billing_address": {
"firstname": "Ahmet",
"lastname": "Yılmaz",
"email": "[email protected]",
"phone": "05551112233",
"address": "Kızılırmak Mah. Dumlupınar Blv. No:3",
"district": "Çankaya",
"province": "Ankara",
"country": "TR"
}
},
"conversion": null
}

Başlatma başarısızsa (sağlayıcı 3D oturumunu açmadı) yanıt yine 200'dür: result.successful false, result.message sağlayıcının mesajı, result.redirect_url null. Diğer alanlar aynı biçimdedir.

AlanTipAçıklama
result.successfulbooleantrue: 3D işlemi başlatıldı. Ödemenin alındığını göstermez.
result.messagestring | nullsuccessful false ise nedeni.
result.redirect_urlstring | nullMüşterinin yönlendirileceği adres; yalnızca successful true iken dolu. Adres bir kez açılır; 15 dakika içinde açılmayan ödemenin süresi dolar.
transaction, customer, conversionobjectÖdeme yanıtı. transaction.token iade, iptal ve sorguda kullanılır.
saved_cardnullYalnızca card.should_save: true gönderildiyse bulunur. Kart ödeme tamamlanınca saklandığı için bu yanıtta null'dır; saklanan kart retrieve-payments yanıtında döner.

HTTP durum kodları​

KodDurum
200İstek işlendi; sonuç result.successful içinde.
401API anahtarı ya da imza geçersiz.
403Çalışma alanı işlem yapamıyor ya da Api modülü kapalı.
422Doğrulama hatası.
429İstek sınırı aşıldı.

Hatalar​

422 ile dönen uca özel mesajlar:

AlanMesaj
transaction.amountTutar 100 veya 100.10 biçiminde olmalıdır; kuruş basamağı noktayla ayrılır. / Tutar sıfırdan büyük olmalıdır. / … en fazla 10.000.000,00 olabilir.
transaction.base_amountSatılan tutar 100 veya 100.10 biçiminde olmalıdır; kuruş basamağı noktayla ayrılır. / Satılan tutar sıfırdan büyük olmalıdır. / Satılan tutar, çekilecek tutardan fazla olamaz.
transaction.referenceReferans en az bir rakam içermelidir (ör. SIP1); bankaya giden sipariş numarası bu rakamlarla kurulur.
transaction.installment_numberTürk Lirası dışındaki ödemelerde taksit yapılamaz; taksit sayısı 1 olmalıdır.
transaction.currencyBu ödeme hesabı <para birimi> ile ödeme almıyor.
transaction.currencyGüncel kur bilgisi alınamadığı için ödeme şu an alınamıyor. (kur çevirisi uygulanacak ödemede)
transaction.payment_provider_tokenBu ödeme hesabı 3D Güvenli ödeme desteklemiyor. / Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.
transaction.callback_urlAdres https ile başlayan geçerli bir adres olmalı. / Adres herkese açık bir adres olmalı.
transaction.saved_card_tokenKayıtlı kartla ödemede kart bilgisi gönderilmez. / Kayıtlı kartla ödemede ödeme hesabı gönderilmez; ödeme kartın saklandığı hesaptan alınır.
transaction.saved_card_tokenÇalışma alanınızda Kayıtlı Kartlar modülü kapalı. / Böyle bir kayıtlı kart bulunamadı. / Kayıtlı kart bu müşteriye ait değil. / Kayıtlı kart bu ortamda saklanmamış. / Kartın kayıtlı olduğu ödeme hesabı silinmiş. / Bu ödeme hesabı kayıtlı kartla ödeme desteklemiyor.
card.numberKart numarası yalnızca rakamlardan oluşmalıdır. / Kart numarası 12 ile 19 hane arasında olmalıdır. / Kart numarası geçersiz; lütfen kontrol edin.
card.expiry_monthSon kullanma ayı 01 ile 12 arasında iki haneli olmalıdır (ör. 05).
card.expiry_yearSon kullanma yılı dört haneli olmalıdır (ör. 2030).
card.should_saveKart saklamak için müşteri referansı (customer.reference) gönderilmelidir. / Çalışma alanınızda Kayıtlı Kartlar modülü kapalı. / Bu ödeme hesabı kart saklamayı desteklemiyor.

Kayıtlı kart bu müşteriye ait değil., customer.reference değeri kartın saklandığı müşterinin referansıyla aynı olmadığında döner. Genel hata biçimi: Hatalar.