DOCS
Panel Giriş Başvurun

3DS

Taksit Bilgisi Size Ait

3D Secure ödemeyi PHP ile başlatın: isteği use3D=true ile gönderin, dönen banka formunu tarayıcıya basın ve sonucu callback adresinizde doğrulayın.

İstek ve Yanıt

Ödeme isteğinin yanıtı sonuç değil, bankanın 3D formudur (BANK_REQUEST_MESSAGE). Form tarayıcıya basılır, müşteri doğrulamayı tamamlar ve sonuç sunucunuza ayrı bir form POST olarak gelir.

1 → İstek · POST /Vpos/v1/Payment (form-data)
sx=SX_DEGERI
clientRefCode=ORDER-66e6f1a2b3c4d
successUrl=https://siteniz.com/payment/callback
failUrl=https://siteniz.com/payment/callback
amount=10.00
installmentNo=1
cardHolderName=Tuna Çınar
month=12
year=2026
cvv=001
cardNumber=4546711234567894
use3D=true
transactionType=SALES
cardHolderIP=85.100.20.15
hashDatav2=lunnRyNfDu6pdpNjjlFrlATE…
rnd=15-09-2026 14:25:11
environment=API
currencyNumber=949
1 ← Yanıt · JSON (kısaltılmış)
{
  "BANK_REQUEST_MESSAGE": "<form action="…banka 3D sayfası…" method="post">…</form>"
}
2 → Sonuç · POST https://siteniz.com/payment/callback
# form POST — JSON değil
RESPONSE_CODE=2
RESPONSE_DATA=İşlem Başarılı.
REFERENCE_CODE=IKSIRPF142277040
USE_3D=true
AUTH_CODE=345344
CLIENT_REFERENCE_CODE=ORDER-66e6f1a2b3c4d
TRANSACTION_AMOUNT=10.00
AUTHORIZATION_AMOUNT=10.00
INSTALLMENT=1
RND=1645700316156
hashDataV2=lunnRyNfDu6pdpNjjlFrlATE…

Sonuç adresinize geldiğinde siparişi onaylamadan önce hashDataV2 imzasını doğrulayın; ödeme yalnızca RESPONSE_CODE=2 ve geçerli bir AUTH_CODE ile başarılıdır — bkz. Ödeme Sonucu.

Sonuç alanları Ödeme Sonucu sayfasındaki belgelenmiş 3D dönüşünden kısaltılmıştır; değerler temsilidir.

3D Ödeme İsteği

Kart bilgileri formunuzdan gelen değerlerle imzalı isteği /Vpos/v1/Payment ucuna gönderin. Yanıtta dönen BANK_REQUEST_MESSAGE bir HTML formudur; tarayıcıya bastığınızda müşteri bankanın 3D doğrulama sayfasına yönlenir.

PHP — 3D ödeme isteği
<?php
// === 3D-ONLY FLOW — Paynkolay V1 ===

$merchantSecretKey = "SECRET_KEY";
$sx                = "SX_DEGERI";
$clientRefCode     = "ORDER-" . uniqid();
$amount            = "10.00";
$successUrl        = "https://siteniz.com/payment/callback"; // 3D sonucu buraya düşer
$failUrl           = "https://siteniz.com/payment/callback";
$rnd               = date("d-m-Y H:i:s");
$customerKey       = "";

// Hash: sx|clientRefCode|amount|successUrl|failUrl|rnd|customerKey|secretKey → SHA512 → Base64
$hashstr    = "$sx|$clientRefCode|$amount|$successUrl|$failUrl|$rnd|$customerKey|$merchantSecretKey";
$hashDataV2 = base64_encode(hash("sha512", mb_convert_encoding($hashstr, 'UTF-8'), true));

$postData = [
    'sx'              => $sx,
    'clientRefCode'   => $clientRefCode,
    'successUrl'      => $successUrl,
    'failUrl'         => $failUrl,
    'amount'          => $amount,
    'installmentNo'   => '1',
    'cardHolderName'  => $_POST['cardHolderName'],
    'month'           => $_POST['month'],
    'year'            => $_POST['year'],
    'cvv'             => $_POST['cvv'],
    'cardNumber'      => $_POST['cardNumber'],
    'use3D'           => 'true',              // ← 3D akışını açan tek satır
    'transactionType' => 'SALES',
    'cardHolderIP'    => $_SERVER['REMOTE_ADDR'],
    'hashDatav2'      => $hashDataV2,
    'rnd'             => $rnd,
    'environment'     => 'API',
    'currencyNumber'  => '949',
];

$curl = curl_init('https://paynkolaytest.nkolayislem.com.tr/Vpos/v1/Payment');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query($postData),
    CURLOPT_TIMEOUT        => 30,
]);
$response = curl_exec($curl);
curl_close($curl);

$data = json_decode($response, true);

// === 3D'ye özgü kısım: HTML formu tarayıcıya bas ===
if (!empty($data['BANK_REQUEST_MESSAGE'])) {
    header('Content-Type: text/html; charset=utf-8');
    echo $data['BANK_REQUEST_MESSAGE'];  // banka ACS'ye auto-submit olur
    exit;
}

echo "3D formu alınamadı: " . htmlspecialchars($response);

3D akışını açan tek fark use3D=true satırıdır; diğer alanlar Non-3DS isteğiyle aynıdır. SECRET_KEY ve SX_DEGERI yerine kendi bilgilerinizi yazın.

3D Callback

Bu adım olmadan 3D akışı eksik kalır. Banka doğrulama sonucunu successUrl / failUrl adresinize POST eder; siparişi onaylamadan önce gelen veriyi mutlaka doğrulayın.

PHP — payment/callback.php
<?php
// payment/callback.php — banka buraya POST eder
$params = $_POST;

// 1. Hash yanıtını doğrula (05-hash-response formülüyle) — atlanırsa sahte POST'la sipariş onaylatılabilir
// 2. RESPONSE_CODE / RESPONSE_DATA kontrol et
// 3. Şüphede kalırsan İşlem Doğrulama Servisi'nden (10-verification-service) teyit al
// 4. Siparişi ancak bu doğrulamalardan sonra COMPLETED yap
  1. 1Hash yanıtını doğrulayınGelen imzayı Ödeme Sonucu sayfasındaki formülle kontrol edin. Bu adım atlanırsa sahte bir POST ile sipariş onaylatılabilir.
  2. 2Sonuç kodunu kontrol edinRESPONSE_CODE ve RESPONSE_DATA alanlarıyla işlemin başarılı olup olmadığına bakın.
  3. 3Şüphede teyit alınEmin olamadığınız durumlarda İşlem Doğrulama Servisi ile işlemin durumunu sorgulayın.
  4. 4Siparişi tamamlayınSiparişi ancak bu doğrulamalardan sonra COMPLETED durumuna alın.

Son güncelleme: 15 Eylül 2026

v1 · Versiyonlar