API Dokümanı - Taksit Bilgisi Pay N Kolay'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.

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

• Payment Servis linki: “https://paynkolaytest.nkolayislem.com.tr/Vpos/Payment/Payment” İlgili tüm değişkenleri Postman collection’ından görebilirsiniz.

• İş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:

PHP

example.php

<?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";
    }
}

?>

.NET C#

example.cs

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}");
        }
    }
}

Python

example.py

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

Node.js

example.js

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();

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