İçeriğe geç
Dokümantasyonu

API Dokümanı - Taksit Bilgisi Paynkolay'a Ait

Bu API’nin kullanımında önce taksitler çağırılır. Taksitleri çağırmak için sx, amount, cardNumber, hosturl, iscardvalid değişkenleri “https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/PaymentInstallments” adresine Body’de form-data olarak POST edilir.

Sadece BIN numarası ile (kartın ilk 8 hanesi ile) taksit sorgulamak için iscardvalid parametresi “false” olarak gönderilmeli, ya da hiç gönderilmemelidir.

Postman collection’ını indirmek için tıklayınız. Örnek kodları Postman Code sinppet’inde görebilirsiniz.

image

PaymentInstallments servisinden gelen EncodedValue tutar bilgisi AUTHORIZATION_AMOUNT ve taksit bilgisi INSTALLMENT diğer değişkenlerle birlikte Payment Servis’ine Body’de form-data olarak POST edilir. (EncodedValue, installmentNo, amount, sx, clientRefCode, successUrl, failUrl, amount, installmentNo, cardHolderName, month, year, cvv, cardNumber, EncodedValue, use3D, transactionType, hosturl, rnd, hashData, environment).

image

  • İşlem 3D değilse bu aşamada ödeme alınır. İşlem sonlanır.

Response Dönüş Parametreleri Payment servisine POST edildiğinde, 3D true ise 3D formu gelecektir. Bu formu şu şekilde ekranda çalıştırabilirsiniz:

example.php
<?php


// --- Helper Function ---
function getClientIpAddress(): string
{
    $headers = [
        'HTTP_CLIENT_IP',
        'HTTP_X_FORWARDED_FOR',
        'HTTP_X_FORWARDED',
        'HTTP_X_CLUSTER_CLIENT_IP',
        'HTTP_FORWARDED_FOR',
        'HTTP_FORWARDED',
        'REMOTE_ADDR'
    ];


    foreach ($headers as $header) {
        if (isset($_SERVER[$header])) {
            $ipList = explode(',', $_SERVER[$header]);
            $ip = trim($ipList[0]);
            if (filter_var($ip, FILTER_VALIDATE_IP)) {
                return $ip;
            }
        }
    }
    return 'UNKNOWN';
}


// --- Configuration & Data Preparation ---


// 1. Credentials & URLs
$sx = "118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==";
$merchantSecretKey = "_YckdxUbv4vrnMUZ6VQsr";
$customerKey = "";
$successUrl = "https://paynkolay.com.tr/test/success";
$failUrl = "https://paynkolay.com.tr/test/fail";


// 2. Transaction Data
$amount = "6.00";
$clientRefCode = "789456|AB76";
$rnd = date("d-m-Y H:i:s");
$cardHolderIP = getClientIpAddress();
$merchantCustomerNo="1234567890";


// 3. Hash Calculation
$hashstr = $sx . "|" . $clientRefCode . "|" . $amount . "|" . $successUrl . "|" . $failUrl . "|" . $rnd . "|" . $customerKey . "|" . $merchantSecretKey;


$hash = mb_convert_encoding($hashstr, 'UTF-8');
$hashedBytes = hash("sha512", $hash, true);
$hashDataV2 = base64_encode($hashedBytes);


// --- Step 1: Query Installments ---


$curl = curl_init();


curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/PaymentInstallments',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => array(
        'sx' => $sx,
        'amount' => $amount,
        'cardNumber' => '4546711234567894',
        'hosturl' => 'https://yoursite.com',
        'iscardvalid' => 'false'
    ),
));


$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);


$encodedValue = null;
$selectedInstallmentCount = null;


if ($httpCode == 200) {
    $installmentData = json_decode($response, true);


    // CHANGED: Access the first item in the PAYMENT_BANK_LIST array
    // We use [0] to get the first installment option ("Tek Çekim" / Installment: 1)
    $firstOption = $installmentData['PAYMENT_BANK_LIST'][0] ?? null;


    if ($firstOption) {
        $encodedValue = $firstOption['EncodedValue'] ?? null;
        $selectedInstallmentCount = $firstOption['INSTALLMENT'] ?? '1'; // Default to 1 if missing
    } else {
        echo "Error: PAYMENT_BANK_LIST is empty or invalid.\n";
    }


} else {
    echo "Error retrieving installments. HTTP Code: $httpCode. Response: " . htmlspecialchars($response) . "\n";
}


// --- Step 2: Make Payment ---


if (isset($encodedValue)) {
    $paymentCurl = curl_init();


    curl_setopt_array($paymentCurl, array(
        CURLOPT_URL => 'https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/Payment',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => array(
            'EncodedValue' => $encodedValue,
            'installmentNo' => $selectedInstallmentCount, // Dynamically set from the selected option
            'amount' => $amount,
            'sx' => $sx,
            'clientRefCode' => $clientRefCode,
            'successUrl' => $successUrl,
            'failUrl' => $failUrl,
            'cardHolderName' => 'John Doe',
            'month' => '12',
            'year' => '2026',
            'cvv' => '123',
            'cardNumber' => '4546711234567894',
            'use3D' => 'true',
            'transactionType' => 'SALES',
            'cardHolderIP' => $cardHolderIP,
            'rnd' => $rnd,
            'hashDatav2' => $hashDataV2,
            'environment' => 'API',
            'merchantCustomerNo' => $merchantCustomerNo
        ),
    ));


    $paymentResponse = curl_exec($paymentCurl);
    $paymentHttpCode = curl_getinfo($paymentCurl, CURLINFO_HTTP_CODE);
    curl_close($paymentCurl);


    if ($paymentHttpCode == 200) {
        // Decode JSON response
        $json = json_decode($paymentResponse, true);
        if (isset($json['BANK_REQUEST_MESSAGE'])) {
            echo $json['BANK_REQUEST_MESSAGE'];
        } else {
            echo "BANK_REQUEST_MESSAGE not found in response.\n";
        }
    } else {
        echo "Error in payment. HTTP Code: $paymentHttpCode. Response: " . htmlspecialchars($paymentResponse) . "\n";
    }
}
?>

image

  • Gelen 3D formu ekrana basıldığında ilgili bankanın 3D secure penceresi açılır ve burada 3D secure şifresi girilmesi beklenir.
3D Secure Window