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.

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).

Payment Service link: “https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/Payment” You can see all related variables from the Postman collection.

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

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

<?php

// Step 1: Query Installments with PaymentInstallments API
$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' => '118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==',
        'amount' => '100.00',
        'cardNumber' => '4546711234567894',
        'hosturl' => 'https://yoursite.com',
        'iscardvalid' => 'false' // Use false to query with BIN only
    ),
));

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

if ($httpCode == 200) {
    $installmentData = json_decode($response, true);
    $encodedValue = $installmentData['EncodedValue']; // This will be used in payment
    echo "Installments retrieved successfully\n";
    echo "EncodedValue: " . $encodedValue . "\n";
} else {
    echo "Error retrieving installments: " . $response . "\n";
}

// Step 2: Make Payment with EncodedValue from installments
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' => '2',
            'amount' => '100.00',
            'sx' => '118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==',
            'clientRefCode' => '789456|AB76',
            'successUrl' => 'https://yoursite.com/success',
            'failUrl' => 'https://yoursite.com/fail',
            'cardHolderName' => 'John Doe',
            'month' => '12',
            'year' => '2026',
            'cvv' => '123',
            'cardNumber' => '4546711234567894',
            'use3D' => 'true',
            'transactionType' => 'SALES',
            'hosturl' => 'https://yoursite.com',
            'rnd' => time(), // Random value for security
            'hashData' => 'your_calculated_hash_here',
            'environment' => 'TEST'
        ),
    ));

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

    if ($paymentHttpCode == 200) {
        echo "Payment request sent successfully\n";
        echo "Response: " . $paymentResponse . "\n";

        // If use3D is true, the response will contain HTML form for 3D secure
        // You need to display this form to the user
        if (strpos($paymentResponse, '<form') !== false) {
            echo "3D Secure form received. Display this form to user:\n";
            // Save or display the HTML form
            file_put_contents('3d_form.html', $paymentResponse);
        }
    } else {
        echo "Error in payment: " . $paymentResponse . "\n";
    }
}

?>

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.IO;

class Program
{
    private static readonly HttpClient client = new HttpClient();

    static async Task Main(string[] args)
    {
        // Step 1: Query Installments
        var installmentData = new List<KeyValuePair<string, string>>
        {
            new KeyValuePair<string, string>("sx", "118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw=="),
            new KeyValuePair<string, string>("amount", "100.00"),
            new KeyValuePair<string, string>("cardNumber", "4546711234567894"),
            new KeyValuePair<string, string>("hosturl", "https://yoursite.com"),
            new KeyValuePair<string, string>("iscardvalid", "false")
        };

        var installmentContent = new FormUrlEncodedContent(installmentData);

        try
        {
            var installmentResponse = await client.PostAsync("https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/PaymentInstallments", installmentContent);
            var installmentResponseString = await installmentResponse.Content.ReadAsStringAsync();

            if (installmentResponse.IsSuccessStatusCode)
            {
                var installmentResult = JsonConvert.DeserializeObject<dynamic>(installmentResponseString);
                string encodedValue = installmentResult.EncodedValue;
                Console.WriteLine("Installments retrieved successfully");
                Console.WriteLine($"EncodedValue: {encodedValue}");

                // Step 2: Make Payment with EncodedValue
                var paymentData = new List<KeyValuePair<string, string>>
                {
                    new KeyValuePair<string, string>("EncodedValue", encodedValue),
                    new KeyValuePair<string, string>("installmentNo", "2"),
                    new KeyValuePair<string, string>("amount", "100.00"),
                    new KeyValuePair<string, string>("sx", "118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw=="),
                    new KeyValuePair<string, string>("clientRefCode", "789456|AB76"),
                    new KeyValuePair<string, string>("successUrl", "https://yoursite.com/success"),
                    new KeyValuePair<string, string>("failUrl", "https://yoursite.com/fail"),
                    new KeyValuePair<string, string>("cardHolderName", "John Doe"),
                    new KeyValuePair<string, string>("month", "12"),
                    new KeyValuePair<string, string>("year", "2026"),
                    new KeyValuePair<string, string>("cvv", "123"),
                    new KeyValuePair<string, string>("cardNumber", "4546711234567894"),
                    new KeyValuePair<string, string>("use3D", "true"),
                    new KeyValuePair<string, string>("transactionType", "SALES"),
                    new KeyValuePair<string, string>("hosturl", "https://yoursite.com"),
                    new KeyValuePair<string, string>("rnd", DateTimeOffset.Now.ToUnixTimeSeconds().ToString()),
                    new KeyValuePair<string, string>("hashData", "your_calculated_hash_here"),
                    new KeyValuePair<string, string>("environment", "TEST")
                };

                var paymentContent = new FormUrlEncodedContent(paymentData);
                var paymentResponse = await client.PostAsync("https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/Payment", paymentContent);
                var paymentResponseString = await paymentResponse.Content.ReadAsStringAsync();

                if (paymentResponse.IsSuccessStatusCode)
                {
                    Console.WriteLine("Payment request sent successfully");
                    Console.WriteLine($"Response: {paymentResponseString}");

                    // If use3D is true, the response will contain HTML form for 3D secure
                    if (paymentResponseString.Contains("<form"))
                    {
                        Console.WriteLine("3D Secure form received. Display this form to user:");
                        File.WriteAllText("3d_form.html", paymentResponseString);
                    }
                }
                else
                {
                    Console.WriteLine($"Error in payment: {paymentResponseString}");
                }
            }
            else
            {
                Console.WriteLine($"Error retrieving installments: {installmentResponseString}");
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Exception: {ex.Message}");
        }
    }
}

import requests
import json
import time

def main():
    # Step 1: Query Installments
    installment_url = "https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/PaymentInstallments"

    installment_data = {
        'sx': '118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==',
        'amount': '100.00',
        'cardNumber': '4546711234567894',
        'hosturl': 'https://yoursite.com',
        'iscardvalid': 'false'  # Use false to query with BIN only
    }

    try:
        installment_response = requests.post(installment_url, data=installment_data)

        if installment_response.status_code == 200:
            installment_result = installment_response.json()
            encoded_value = installment_result['EncodedValue']
            print("Installments retrieved successfully")
            print(f"EncodedValue: {encoded_value}")

            # Step 2: Make Payment with EncodedValue
            payment_url = "https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/Payment"

            payment_data = {
                'EncodedValue': encoded_value,
                'installmentNo': '2',
                'amount': '100.00',
                'sx': '118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==',
                'clientRefCode': '789456|AB76',
                'successUrl': 'https://yoursite.com/success',
                'failUrl': 'https://yoursite.com/fail',
                'cardHolderName': 'John Doe',
                'month': '12',
                'year': '2026',
                'cvv': '123',
                'cardNumber': '4546711234567894',
                'use3D': 'true',
                'transactionType': 'SALES',
                'hosturl': 'https://yoursite.com',
                'rnd': str(int(time.time())),  # Random value for security
                'hashData': 'your_calculated_hash_here',
                'environment': 'TEST'
            }

            payment_response = requests.post(payment_url, data=payment_data)

            if payment_response.status_code == 200:
                print("Payment request sent successfully")
                print(f"Response: {payment_response.text}")

                # If use3D is true, the response will contain HTML form for 3D secure
                if '<form' in payment_response.text:
                    print("3D Secure form received. Display this form to user:")
                    with open('3d_form.html', 'w', encoding='utf-8') as f:
                        f.write(payment_response.text)
            else:
                print(f"Error in payment: {payment_response.text}")

        else:
            print(f"Error retrieving installments: {installment_response.text}")

    except requests.exceptions.RequestException as e:
        print(f"Request exception: {e}")
    except json.JSONDecodeError as e:
        print(f"JSON decode error: {e}")
    except Exception as e:
        print(f"Exception: {e}")

if __name__ == "__main__":
    main()

const axios = require('axios');
const qs = require('querystring');
const fs = require('fs');

async function main() {
    try {
        // Step 1: Query Installments
        const installmentUrl = 'https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/PaymentInstallments';

        const installmentData = {
            'sx': '118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==',
            'amount': '100.00',
            'cardNumber': '4546711234567894',
            'hosturl': 'https://yoursite.com',
            'iscardvalid': 'false' // Use false to query with BIN only
        };

        const installmentResponse = await axios.post(installmentUrl, qs.stringify(installmentData), {
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            }
        });

        if (installmentResponse.status === 200) {
            const installmentResult = installmentResponse.data;
            const encodedValue = installmentResult.EncodedValue;
            console.log('Installments retrieved successfully');
            console.log(`EncodedValue: ${encodedValue}`);

            // Step 2: Make Payment with EncodedValue
            const paymentUrl = 'https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/Payment';

            const paymentData = {
                'EncodedValue': encodedValue,
                'installmentNo': '2',
                'amount': '100.00',
                'sx': '118591467|bScbGDYCtPf7SS1N6PQ6/+58rFhW1WpsWINqvkJFaJlu6bMH2tgPKDQtjeA5vClpzJP24uA0vx7OX53cP3SgUspa4EvYix+1C3aXe++8glUvu9Oyyj3v300p5NP7ro/9K57Zcw==',
                'clientRefCode': '789456|AB76',
                'successUrl': 'https://yoursite.com/success',
                'failUrl': 'https://yoursite.com/fail',
                'cardHolderName': 'John Doe',
                'month': '12',
                'year': '2026',
                'cvv': '123',
                'cardNumber': '4546711234567894',
                'use3D': 'true',
                'transactionType': 'SALES',
                'hosturl': 'https://yoursite.com',
                'rnd': Math.floor(Date.now() / 1000).toString(), // Random value for security
                'hashData': 'your_calculated_hash_here',
                'environment': 'TEST'
            };

            const paymentResponse = await axios.post(paymentUrl, qs.stringify(paymentData), {
                headers: {
                    'Content-Type': 'application/x-www-form-urlencoded'
                }
            });

            if (paymentResponse.status === 200) {
                console.log('Payment request sent successfully');
                console.log(`Response: ${paymentResponse.data}`);

                // If use3D is true, the response will contain HTML form for 3D secure
                if (paymentResponse.data.includes('<form')) {
                    console.log('3D Secure form received. Display this form to user:');
                    fs.writeFileSync('3d_form.html', paymentResponse.data);
                }
            } else {
                console.log(`Error in payment: ${paymentResponse.data}`);
            }

        } else {
            console.log(`Error retrieving installments: ${installmentResponse.data}`);
        }

    } catch (error) {
        if (error.response) {
            console.log(`HTTP Error ${error.response.status}: ${error.response.data}`);
        } else {
            console.log(`Exception: ${error.message}`);
        }
    }
}

main();

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