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",
"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
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
reference | string | evet | Ödemenin sizin sisteminizdeki referansı. En çok 255 karakter, en az bir rakam. |
amount | string | evet | Karttan çekilecek tutar: "450", "450.5" ya da "450.50". Sıfırdan büyük, en fazla 10000000.00. |
base_amount | string | hayır | Satı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. |
currency | string | hayır | TRY, USD, EUR, GBP. Gönderilmezse TRY. Ödeme hesabının bu para biriminde işlem alması gerekir. |
installment_number | integer | evet | 1–12. 1'den büyük değer yalnızca TRY ile istenip TRY olarak çekilen ödemede kabul edilir. |
ip | string | evet | Müşterinin IP adresi (IPv4 ya da IPv6). |
callback_url | string | evet | Dö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_token | string (UUID) | hayır | Ödeme hesabı. Gönderilmezse ödeme hesabı seçimi uygulanır. saved_card_token ile birlikte gönderilmez. |
saved_card_token | string (UUID) | hayır | Kayı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.
| Alan | Tip | Zorunlu | Açıklama |
|---|---|---|---|
holder_name | string | evet | Kart sahibinin adı. En çok 255 karakter. |
number | string | evet | Kart numarası. Rakam ve boşluk; boşluklar çıkarıldıktan sonra 12–19 hane. |
security_code | string | evet | 3–4 rakam. |
expiry_month | string | evet | "01"–"12". |
expiry_year | string | evet | 4 rakam: "2030". |
should_save | boolean | hayır | true 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
Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.
- PHP
- Node.js
- Python
- Java
- cURL
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',
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);
}
const payment = await client.securePayment({
reference: 'SIP-10231',
amount: '450.00',
installmentNumber: 1,
ip: req.ip,
customer: {
reference: 'musteri-88',
billingAddress: {
firstname: 'Ahmet',
lastname: 'Yılmaz',
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: {
holderName: 'AHMET YILMAZ',
number: '5400360000000003',
securityCode: '000',
expiryMonth: '12',
expiryYear: '2030',
},
});
if (payment.redirectUrl !== null) {
res.redirect(payment.redirectUrl);
}
from odemehub.request import Address, Card, PaymentCustomer, SecurePayment
payment = client.secure_payment(SecurePayment(
reference="SIP-10231",
amount="450.00",
installment_number=1,
ip=request.remote_addr,
customer=PaymentCustomer(
reference="musteri-88",
billing_address=Address(
firstname="Ahmet", lastname="Yılmaz",
address="Kızılırmak Mah. Dumlupınar Blv. No:3",
district="Çankaya", province="Ankara", country="TR",
),
),
callback_url="https://magazam.com/odeme/donus",
card=Card(
holder_name="AHMET YILMAZ",
number="5400360000000003",
expiry_month="12",
expiry_year="2030",
security_code="000",
),
))
if payment.redirect_url is not None:
return redirect(payment.redirect_url)
import com.odemehub.request.Address;
import com.odemehub.request.Card;
import com.odemehub.request.PaymentCustomer;
import com.odemehub.request.SecurePayment;
var payment = client.securePayment(SecurePayment.builder()
.reference("SIP-10231")
.amount("450.00")
.installmentNumber(1)
.ip(request.getRemoteAddr())
.customer(PaymentCustomer.builder()
.reference("musteri-88")
.billingAddress(Address.builder()
.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")
.build())
.build())
.callbackUrl("https://magazam.com/odeme/donus")
.card(Card.builder()
.holderName("AHMET YILMAZ")
.number("5400360000000003")
.securityCode("000")
.expiryMonth("12")
.expiryYear("2030")
.build())
.build());
if (payment.getRedirectUrl() != null) {
return "redirect:" + payment.getRedirectUrl();
}
URI_PATH="/api/$ODEMEHUB_TEAM/gateway/secure-payment"
BODY='{"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"}}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')
curl -X POST "https://sandbox.odemehub.com$URI_PATH" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $ODEMEHUB_API_KEY" \
-H "X-Timestamp: $TIMESTAMP" \
-H "X-Signature: $SIGNATURE" \
--data-raw "$BODY"
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",
"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.
| Alan | Tip | Açıklama |
|---|---|---|
result.successful | boolean | true: 3D işlemi başlatıldı. Ödemenin alındığını göstermez. |
result.message | string | null | successful false ise nedeni. |
result.redirect_url | string | null | Müş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, conversion | object | Ödeme yanıtı. transaction.token iade, iptal ve sorguda kullanılır. |
saved_card | null | Yalnı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ı
| Kod | Durum |
|---|---|
200 | İstek işlendi; sonuç result.successful içinde. |
401 | API anahtarı ya da imza geçersiz. |
403 | Çalışma alanı işlem yapamıyor ya da Api modülü kapalı. |
422 | Doğrulama hatası. |
429 | İstek sınırı aşıldı. |
Hatalar
422 ile dönen uca özel mesajlar:
| Alan | Mesaj |
|---|---|
transaction.amount | Tutar 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_amount | Satı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.reference | Referans en az bir rakam içermelidir (ör. SIP1); bankaya giden sipariş numarası bu rakamlarla kurulur. |
transaction.installment_number | Türk Lirası dışındaki ödemelerde taksit yapılamaz; taksit sayısı 1 olmalıdır. |
transaction.currency | Bu ödeme hesabı <para birimi> ile ödeme almıyor. |
transaction.currency | Güncel kur bilgisi alınamadığı için ödeme şu an alınamıyor. (kur çevirisi uygulanacak ödemede) |
transaction.payment_provider_token | Bu ödeme hesabı 3D Güvenli ödeme desteklemiyor. / Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok. |
transaction.callback_url | Adres https ile başlayan geçerli bir adres olmalı. / Adres herkese açık bir adres olmalı. |
transaction.saved_card_token | Kayı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.number | Kart 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_month | Son kullanma ayı 01 ile 12 arasında iki haneli olmalıdır (ör. 05). |
card.expiry_year | Son kullanma yılı dört haneli olmalıdır (ör. 2030). |
card.should_save | Kart 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.