Skip to content
Documentation

API Documentation - Installment Information Belongs to Pay N Kolay

In the usage of this API, installments are called first. To call installments, the variables sx, amount, cardNumber, hosturl, iscardvalid are sent as form-data in the Body via POST to “https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/PaymentInstallments”.

To query installments with only the BIN number (first 8 digits of the card), the iscardvalid parameter should be sent as “false” or not sent at all.

Click to download Postman collection. You can see example codes in Postman Code snippet.

image

The EncodedValue amount information and installment information INSTALLMENT from the PaymentInstallments service are sent to the Payment Service along with other variables as form-data in the Body via POST (EncodedValue, installmentNo, amount, sx, clientRefCode, successUrl, failUrl, amount, installmentNo, cardHolderName, month, year, cvv, cardNumber, EncodedValue, use3D, transactionType, hosturl, rnd, hashData, environment).

image

  • If the transaction is not 3D, payment is taken at this stage. The transaction is completed.

When Response Return Parameters POSTed to the Payment service, if 3D is true, a 3D form will come. You can run this form on screen as follows:

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

  • When the incoming 3D form is printed on screen, the relevant bank’s 3D secure window opens and 3D secure password entry is expected.
3D Secure Window