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. Ödemenin sonucu, dönüşten sonra retrieve-payment ile alınır. Akış: Secure (3D) Ödeme rehberi.

Kimlik doğrulama

X-Api-Key: key_...
X-Signature: <gövdenin HMAC-SHA256 imzası>
Content-Type: application/json

Ayrıntılar: Kimlik Doğrulama ve İmza.

İstek

{
  "transaction": {
    "channel_token": "6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14",
    "channel_reference": "SIP-10231",
    "amount": "450.00",
    "installment_number": 1,
    "ip": "85.105.10.20",
    "callback_url": "https://magazam.com/odeme/donus"
  },
  "customer": {
    "channel_reference": "musteri-88",
    "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": "Türkiye"
  },
  "card": {
    "holder_name": "AHMET YILMAZ",
    "number": "5400360000000003",
    "security_code": "000",
    "expiry_month": "12",
    "expiry_year": "2030"
  }
}

`transaction`

Alan	Tip	Zorunlu	Açıklama
`channel_token`	string (UUID)	evet	Çalışma alanınıza ait kanalın token'ı.
`channel_reference`	string	evet	Ödemenin sizin sisteminizdeki kimliği. En çok 255 karakter, en az bir rakam.
`amount`	string	evet	Karttan çekilecek tutar: `"450"` ya da `"450.00"`.
`base_amount`	string	hayır	Satılan tutar (vade farkı hariç). `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 desteklemesi gerekir.
`installment_number`	integer	evet	1–12. `TRY` dışındaki para birimlerinde (ya da kur çevirisiyle `TRY` dışında çekilecek ödemede) `1` olmalıdır.
`ip`	string	evet	Müşterinin IP adresi (geçerli IPv4/IPv6).
`callback_url`	string	evet	Dönüş POST'unun gönderileceği adres. `http`/`https`, en çok 2048 karakter. Bkz. Dönüş POST'u.
`payment_provider_token`	string (UUID)	hayır	Ödeme hesabı. Gönderilmezse ödeme hesabı seçimi uygulanır. `saved_card_token` ile birlikte gönderilemez.
`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. Alanlar: customer nesnesi.

`card`

transaction.saved_card_token gönderilmediğinde zorunludur; gönderildiğinde card gönderilmez.

Alan	Tip	Zorunlu	Açıklama
`holder_name`	string	evet	Kart sahibinin adı. En çok 255 karakter.
`number`	string	evet	Kart numarası, 12–19 karakter.
`security_code`	string	evet	3–4 karakter.
`expiry_month`	string	evet	2 karakter: `"04"`.
`expiry_year`	string	evet	4 karakter: `"2030"`.
`should_save`	boolean	hayır	`true` ise ödeme başarılı olduğunda kart saklanır. Planın kayıtlı kartları kapsaması ve ödeme hesabının kart saklaması gerekir.

SDK örnekleri

PHP
Node.js
Python
Java
cURL

use Gurmehub\Odemehub\Request\{Card, Customer, SecurePayment};

$payment = $client->securePayment(new SecurePayment(
    channelReference: 'SIP-10231',
    amount: '450.00',
    installmentNumber: 1,
    ip: $_SERVER['REMOTE_ADDR'],
    customer: new Customer(
        channelReference: 'musteri-88',
        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: 'Türkiye',
    ),
    callbackUrl: 'https://magazam.com/odeme/donus',
    card: new Card(
        holderName: 'AHMET YILMAZ',
        number: '5400360000000003',
        securityCode: '000',
        expiryMonth: '12',
        expiryYear: '2030',
    ),
));

if ($payment->result->successful) {
    header('Location: '.$payment->redirectUrl);
}

const payment = await client.securePayment({
    channelReference: 'SIP-10231',
    amount: '450.00',
    installmentNumber: 1,
    ip: req.ip,
    customer: {
        channelReference: 'musteri-88',
        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: 'Türkiye',
    },
    callbackUrl: 'https://magazam.com/odeme/donus',
    card: {
        holderName: 'AHMET YILMAZ',
        number: '5400360000000003',
        securityCode: '000',
        expiryMonth: '12',
        expiryYear: '2030',
    },
});

if (payment.result.successful) {
    res.redirect(payment.redirectUrl!);
}

from odemehub.request import Card, Customer, SecurePayment

payment = client.secure_payment(SecurePayment(
    channel_reference="SIP-10231",
    amount="450.00",
    installment_number=1,
    ip=request.remote_addr,
    customer=Customer(
        channel_reference="musteri-88",
        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="Türkiye",
    ),
    callback_url="https://magazam.com/odeme/donus",
    card=Card(
        holder_name="AHMET YILMAZ",
        number="5400360000000003",
        security_code="000",
        expiry_month="12",
        expiry_year="2030",
    ),
))

if payment.result.successful:
    return redirect(payment.redirect_url)

import com.odemehub.request.Card;
import com.odemehub.request.Customer;
import com.odemehub.request.SecurePayment;

var payment = client.securePayment(SecurePayment.builder()
    .channelReference("SIP-10231")
    .amount("450.00")
    .installmentNumber(1)
    .ip(request.getRemoteAddr())
    .customer(Customer.builder()
        .channelReference("musteri-88")
        .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("Türkiye")
        .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.getResult().isSuccessful()) {
    return "redirect:" + payment.getRedirectUrl();
}

BODY='{"transaction":{"channel_token":"6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14","channel_reference":"SIP-10231","amount":"450.00","installment_number":1,"ip":"85.105.10.20","callback_url":"https://magazam.com/odeme/donus"},"customer":{"channel_reference":"musteri-88","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":"Türkiye"},"card":{"holder_name":"AHMET YILMAZ","number":"5400360000000003","security_code":"000","expiry_month":"12","expiry_year":"2030"}}'
SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://odeme.gurmehub.com/api/$ODEMEHUB_TEAM/gateway/secure-payment" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt

Başlatma başarılı:

{
  "result": {
    "successful": true,
    "message": null,
    "redirect_url": "https://odeme.gurmehub.com/gateway/secure/0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d"
  },
  "transaction": {
    "token": "0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d",
    "channel_token": "6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14",
    "channel_reference": "SIP-10231"
  },
  "customer": {
    "channel_reference": "musteri-88"
  },
  "conversion": null
}

Başlatma başarısız (sağlayıcı reddetti; yine 200):

{
  "result": {
    "successful": false,
    "message": "<sağlayıcının mesajı>",
    "redirect_url": null
  },
  "transaction": { "token": "0b8f6c2d-3e41-4a7b-9c5d-1e2f3a4b5c6d", "channel_token": "6f1c2e7a-4b3d-4c8e-9a61-2f5d7b0c3e14", "channel_reference": "SIP-10231" },
  "customer": { "channel_reference": "musteri-88" },
  "conversion": null
}

Alan	Tip	Açıklama
`result.successful`	boolean	`true`: 3D işlemi başlatıldı. Ödemenin alındığı anlamına gelmez.
`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 sunulur; 15 dakika içinde açılmayan ödemenin süresi dolar.
`transaction.token`	string	Ödemenin token'ı. `retrieve-payment`, `refund-payment` ve `cancel-payment` bu değeri alır.
`transaction.channel_token`	string	Ödemenin kanalı.
`transaction.channel_reference`	string	Gönderdiğiniz `channel_reference`.
`customer.channel_reference`	string	Müşterinin `channel_reference` değeri.
`conversion`	object \| null	Ödeme kur çevirisiyle başka para biriminde çekilecekse `{amount, currency, rate}`; değilse `null`. Bkz. Taksit ve Kur Çevirisi.
`saved_card`	object \| 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-payment` 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.
`422`	Doğrulama hatası.

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.`
`transaction.base_amount`	`Satılan tutar, çekilecek tutardan fazla olamaz.`
`transaction.channel_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.`
`transaction.payment_provider_token`	`Ödeme hesabı belirtilmedi ve çalışma alanınızın varsayılan ödeme hesabı yok.`
`transaction.saved_card_token`	`Kayıtlı kartla ödemede kart bilgisi gönderilmez.`
`transaction.saved_card_token`	`Kayıtlı kartla ödemede ödeme hesabı gönderilmez; ödeme kartın saklandığı hesaptan alınır.`
`transaction.saved_card_token`	`Böyle bir kayıtlı kart bulunamadı.` / `Kayıtlı kart bu müşteriye ait değil.` / `Kayıtlı kartın saklandığı ödeme hesabı silinmiş.` / `Kayıtlı kart bu ortamda saklanmamış.` / `Bu ödeme hesabı kayıtlı kartla ödeme desteklemiyor.` / `Çalışma alanınızın planı kayıtlı kartları kapsamıyor.`
`card.should_save`	`Çalışma alanınızın planı kayıtlı kartları kapsamıyor.` / `Bu ödeme hesabı kart saklamayı desteklemiyor.`

Genel hata biçimi: Hatalar.

Kimlik doğrulama​

İstek​

transaction​

customer​

card​

SDK örnekleri​

Yanıt​

HTTP durum kodları​

Hatalar​