Ödemeler

3D Secure Ödeme

Kart sahibi, bankasının 3D Secure ekranında doğrulanır. Chargeback riskini en aza indiren en güvenli ödeme yöntemidir.

POST /api/payment/pay3d X-Api-Key

Ödeme Akışı

Kart bilgileriyle /api/payment/pay3d çağrısı yaparsınız.
Yanıtta gelen redirectHtml içeriğini kullanıcının tarayıcısında render edersiniz; kullanıcı bankanın 3D ekranına yönlenir.
Kullanıcı SMS/şifre ile doğrular.
YucePay banka sonucunu alır, ödemeyi sonuçlandırır ve kullanıcıyı successUrl / failUrl adresinize yönlendirir.
Sonucu ayrıca webhook ile de alırsınız (payment.succeeded / payment.failed).

İstek Gövdesi

Alan	Tip		Açıklama
idempotencyKey	string	zorunlu	Tekrarlanan istekleri önler. Her ödeme için benzersiz.
amount	decimal	zorunlu	Toplam tutar (0.01–999999.99). products toplamı ile eşleşmeli.
currency	string	opt	TRY, USD, EUR, GBP — varsayılan TRY
installment	int	opt	Taksit sayısı (1–36), varsayılan 1
cardNo	string	zorunlu	13–19 haneli kart numarası
cardHolderName	string	zorunlu	Kart üzerindeki isim
expireMonth	string	zorunlu	MM (01–12)
expireYear	string	zorunlu	YY veya YYYY
cvv	string	zorunlu	3–4 haneli güvenlik kodu (saklanmaz)
successUrl	string	opt	3D başarılı dönüş adresi
failUrl	string	opt	3D başarısız dönüş adresi
clientIp	string	opt	Kart sahibinin IP adresi (fraud kontrolü)
orderNumber	string	opt	Sizin sipariş referansınız
products	array	zorunlu	Sepet kalemleri. Tutar doğrulaması için kullanılır.

products[]

id	string	Ürün/SKU kimliği
name	string	Ürün adı
amount	decimal	Ürün tutarı
category	string	Kategori (opsiyonel)

amount alanı, products dizisindeki tutarların toplamına eşit olmalıdır. Aksi halde istek AMOUNT_MISMATCH hatası ile reddedilir.

Yanıt

Başarılı yanıtta data.redirectHtml içeriğini kullanıcının tarayıcısında render edin. Bu form, kullanıcıyı otomatik olarak bankanın 3D Secure ekranına gönderir.

data.paymentId	guid	YucePay ödeme kimliği
data.paymentReferenceNumber	string	İnsan-okunur referans numarası
data.redirectHtml	string	Tarayıcıda render edilecek 3D yönlendirme formu
data.status	string	Beklemede → 3D sonrası Başarılı / Başarısız

Olası Hatalar

IDEMPOTENCY_KEY_REQUIRED	idempotencyKey gönderilmedi
AMOUNT_MISMATCH	amount ≠ products toplamı
NO_ACTIVE_BANK	Şirket için aktif banka entegrasyonu yok
COMPANY_INACTIVE	Şirket aktif değil

Önceki← Kimlik Doğrulama Sonraki3Dsiz Direkt Ödeme →

POST /api/payment/pay3d

curl -X POST https://api.yucepay.com/api/payment/pay3d \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ord-2026-0001",
    "amount": 149.90,
    "currency": "TRY",
    "installment": 1,
    "cardNo": "4111111111111111",
    "cardHolderName": "AHMET YILMAZ",
    "expireMonth": "12",
    "expireYear": "28",
    "cvv": "123",
    "clientIp": "88.240.10.5",
    "successUrl": "https://magaza.com/odeme/basarili",
    "failUrl": "https://magaza.com/odeme/hata",
    "orderNumber": "SIP-10432",
    "products": [
      { "id": "SKU-1", "name": "Kablosuz Kulaklık", "amount": 149.90 }
    ]
  }'

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-Api-Key", "pk_live_xxxxxxxxxxxxxxxx");

var body = new {
    idempotencyKey = "ord-2026-0001",
    amount = 149.90m,
    currency = "TRY",
    installment = 1,
    cardNo = "4111111111111111",
    cardHolderName = "AHMET YILMAZ",
    expireMonth = "12",
    expireYear = "28",
    cvv = "123",
    clientIp = "88.240.10.5",
    successUrl = "https://magaza.com/odeme/basarili",
    failUrl = "https://magaza.com/odeme/hata",
    orderNumber = "SIP-10432",
    products = new[] { new { id = "SKU-1", name = "Kablosuz Kulaklık", amount = 149.90m } }
};

var res = await http.PostAsJsonAsync(
    "https://api.yucepay.com/api/payment/pay3d", body);
var json = await res.Content.ReadAsStringAsync();
// data.redirectHtml içeriğini tarayıcıda render edin

<?php
$ch = curl_init('https://api.yucepay.com/api/payment/pay3d');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'X-Api-Key: pk_live_xxxxxxxxxxxxxxxx',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'idempotencyKey' => 'ord-2026-0001',
    'amount'         => 149.90,
    'currency'       => 'TRY',
    'installment'    => 1,
    'cardNo'         => '4111111111111111',
    'cardHolderName' => 'AHMET YILMAZ',
    'expireMonth'    => '12',
    'expireYear'     => '28',
    'cvv'            => '123',
    'clientIp'       => '88.240.10.5',
    'successUrl'     => 'https://magaza.com/odeme/basarili',
    'failUrl'        => 'https://magaza.com/odeme/hata',
    'orderNumber'    => 'SIP-10432',
    'products'       => [['id' => 'SKU-1', 'name' => 'Kablosuz Kulaklık', 'amount' => 149.90]],
  ]),
]);
$response = curl_exec($ch);

const res = await fetch('https://api.yucepay.com/api/payment/pay3d', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'pk_live_xxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    idempotencyKey: 'ord-2026-0001',
    amount: 149.90,
    currency: 'TRY',
    installment: 1,
    cardNo: '4111111111111111',
    cardHolderName: 'AHMET YILMAZ',
    expireMonth: '12',
    expireYear: '28',
    cvv: '123',
    clientIp: '88.240.10.5',
    successUrl: 'https://magaza.com/odeme/basarili',
    failUrl: 'https://magaza.com/odeme/hata',
    orderNumber: 'SIP-10432',
    products: [{ id: 'SKU-1', name: 'Kablosuz Kulaklık', amount: 149.90 }],
  }),
});
const data = await res.json();
// data.data.redirectHtml içeriğini tarayıcıda render edin

{
  "success": true,
  "message": "3D doğrulama başlatıldı",
  "data": {
    "paymentId": "9c8f2e1a-4b7d-4a10-9f2c-1a2b3c4d5e6f",
    "paymentReferenceNumber": "PAY-20260819-0001",
    "redirectHtml": "<form action=\"https://banka.../3d\" method=\"post\">...</form>",
    "status": "Beklemede"
  },
  "errorCode": null,
  "timestamp": "2026-08-19T10:30:45Z"
}