💰Payment

Good to know: Before you begin, make sure you have obtained the login and password from the administrator. These credentials are required to authenticate and successfully execute the API requests.

Test Payment Cards

Cards	Authorization
2200112611773794	3Ds 2.0
4439970000000007	3Ds 2.0
5136914521003242	3Ds 1.0
4047300000007550	without 3Ds

CVC – any value , ExpirationDate > current day

When paying with test cards without 3ds, an error may occur

The use of this method assumes mandatory compliance of the merchant's system with PCI DSS requirements.

Creating a new payment

To initiate a payment, please send a POST request to the following endpoint: https://{url}.finipay.kg/api/v1.1.0/payment. Make sure to include Basic Authentication in the request headers using the login and password provided by the administrator.

{
    "orderNumber": "898321246",
    "description": "your order description",
    "amount": 500.00,
    "currency": "EUR",
    "pan": "4439970000000007",
    "cvc": "525",
    "expiryYear": 2023,
    "expiryMonth": "06",
    "name": "Test Testov", //order: Firstname and Lastname
    "language": "en",
    "returnUrl": "https://your_service_url_to_receive_post_requests",
    "callbackUrl": "https://your_callback_url",
    "ip": "31.134.91.22",
    "email": "[e-mail]"
}

Create payment.

POST https://{url}.finipay.kg/api/v1.1.0/payment

Creates a new payment.

Request Body

Name	Type	Description
orderNumber*	string	The unique number of transaction
description*	string	The description of transaction
amount*	decimal	Min value = 1
currency*	string	Example: "EUR", "USD", 3 symbols
pan*	string	Full card number, pan length must between 13 to 20!
expiryMonth*	string	length = 2, example: "06"
expiryYear*	integer	length = 4, example: 2023
cvc*	string	CVC Code, length = 3
language*	string	length = 2, example: "en"
name*	string	Cardholder name, Firstname should be placed first, then Lastname
returnUrl	string	URl of the page that user will be redirected to after successful payment
callbackUrl*	string	Your callback service
ip*	string	IP address of payer
email	string	Email of payer

* - Required 

⚠️ Recommendations for Order Number generation

To avoid failures in data transmission, storage and encryption, it is strongly recommended to exclude special characters from the order number.

Unacceptable characters for the order number:

! @ # $ % ^ & * ( ) _ + { } [ ] | \ : ; “ ' < > , . ? / ~ \n \t 😀 漢字 💥

Note: Only:

 - Latin letters (A-Z, a-z),
 - numerals (0-9),
 - hyphen - and underscore _ (if necessary and if supported by the system).

Examples of valid order numbers:
 - ORDER-123456
 - user_789_order

Examples of invalid numbers:
 - ORDER#123! ❌
 - order😀漢字💥 ❌

Response

110: Created

If the card is involved in 3ds 2.0
{
    "code": "110",
    "message": "CREATED",
    "data": {
        "amount": 400.00,
        "currency": "USD",
        "name": "Test Testov",
        "orderNumber": "89832138",
        "description": "Payment Description",
        "ConfirmationUrl": "https://example.com/.."
    }
}

If the card is not involved in 3ds 2.0
{
    "code": "110",
    "message": "CREATED",
    "data": {
        "amount": 400.00,
        "currency": "USD",
        "name": "Test Testov",
        "orderNumber": "89832138",
        "description": "Payment Description",
        "status": "Success"
    }
}

1: Error

{
    "code": "1",
    "message": "ERROR",
    "data": null
}

400: Bad Request

{
    "timestamp": "2025-04-30T11:29:24.153+00:00",
    "status": 400,
    "error": "Bad Request",
    "path": "/api/v1.1.0/payment"
}

112: DUPLCATED_ORDER_ID

{
    "code": "112",
    "message": "Транзакция с данным id уже существует в системе",
    "data": null
}

93: UNSUPPORTED_CARD_TYPE

{
    "code": "93",
    "message": "Карта не поддерживается. Разрешены только VISA и MasterCard",
    "data": null
}

135: SERVICE_ERROR

{
    "code": "135",
    "message": "SERVICE_ERROR",
    "data": null
}

By following this link you can find more status codes that can appear in the responses

✅Status Codes

You need to open the page that comes in the response (the value from the confirmation Url field). Where the otp entry page opens

after the payment is completed, the client returns to returnUrl in this format : returnUrl?OrderNumber=89832138&statusCode=200.

redirect: https://example.com/?OrderNumber=89832138&statusCode=200

Code samples:

Here are the code snippets for making a POST request to the specified endpoint using different programming languages. Please make sure to replace 'your_username' and 'your_password' with your actual credentials.

PHP

<?php

$endpoint = 'https://{url}.finipay.kg/api/payment';
$username = 'your_username';
$password = 'your_password';

$data = [
    'orderNumber' => '89832199',
    'description' => 'a,dsfnakdfakjdf',
    'amount' => 250.78,
    'currency' => 'KZT',
    'pan' => '4405639704015096',
    'cvc' => '815',
    'expiryYear' => 2025,
    'expiryMonth' => '01',
    'name' => 'Test Testov',
    'language' => 'en',
    'returnUrl' => 'test',
    'callbackUrl' => 'your_callback_url',
    'ip' => '31.134.91.22',
    'email' => '[e-mail]'
];

$options = [
    'http' => [
        'header' => "Content-type: application/json\r\n",
        'method' => 'POST',
        'content' => json_encode($data),
        'header' => "Authorization: Basic " . base64_encode($username . ":" . $password) . "\r\n"
    ]
];

$context = stream_context_create($options);
$response = file_get_contents($endpoint, false, $context);

if ($response === false) {
    echo 'Error occurred while making the request.';
} else {
    echo $response;
}

?>

C#

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        string endpoint = "https://{url}.finipay.kg/api/payment";
        string username = "your_username";
        string password = "your_password";

        var data = new
        {
            orderNumber = "89832199",
            description = "a,dsfnakdfakjdf",
            amount = 250.78,
            currency = "KZT",
            pan = "4405639704015096",
            cvc = "815",
            expiryYear = 2025,
            expiryMonth = "01",
            name = "Test Testov",
            language = "en",
            returnUrl = "test",
            callbackUrl = "your_callback_url",
            ip = "31.134.91.22",
            email = "[e-mail]"
        };

        using (var httpClient = new HttpClient())
        {
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.ASCII.GetBytes($"{username}:{password}")));
            var json = Newtonsoft.Json.JsonConvert.SerializeObject(data);
            var content = new StringContent(json, Encoding.UTF8, "application/json");
            var response = await httpClient.PostAsync(endpoint, content);
            var responseContent = await response.Content.ReadAsStringAsync();
            Console.WriteLine(responseContent);
        }
    }
}

Axios(node.js)

const axios = require('axios');

const endpoint = 'https://{url}.finipay.kg/api/payment';
const username = 'your_username';
const password = 'your_password';

const data = {
    orderNumber: '89832199',
    description: 'a,dsfnakdfakjdf',
    amount: 250.78,
    currency: 'KZT',
    pan: '4405639704015096',
    cvc: '815',
    expiryYear: 2025,
    expiryMonth: '01',
    name: 'Test Testov',
    language: 'en',
    returnUrl: 'test',
    callbackUrl: 'your_callback_url',
    ip: '31.134.91.22',
    email: '[e-mail]'
};

axios.post(endpoint, data, {
    auth: {
        username: username,
        password: password
    },
    headers: {
        'Content-Type': 'application/json'
    }
})
.then(response => {
    console.log(response.data);
})
.catch(error => {
    console.log(error);
});

Java

import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class PaymentEndpointExample {
    public static void main(String[] args) throws IOException {
        String endpoint = "https://{url}.finipay.kg/api/payment";
        String username = "your_username";
        String password = "your_password";

        String requestBody = "{\n" +
                "    \"orderNumber\": \"89832199\",\n" +
                "    \"description\": \"a,dsfnakdfakjdf\",\n" +
                "    \"amount\": 250.78,\n" +
                "    \"currency\": \"KZT\",\n" +
                "    \"pan\": \"4405639704015096\",\n" +
                "    \"cvc\": \"815\",\n" +
                "    \"expiryYear\": 2025,\n" +
                "    \"expiryMonth\": \"01\",\n" +
                "    \"name\": \"Test Testov\",\n" +
                "    \"language\": \"en\",\n" +
                "    \"returnUrl\": \"test\",\n" +
                "    \"callbackUrl\": \"https://bridge.mydatacoin.io/api/v1/datasets/finipay\"\n" +
                "    \"ip\": \"31.134.91.22\",\n" +
                "    \"email\": \"[e-mail]\"\n" +
                "}";

        URL url = new URL(endpoint);
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setDoOutput(true);

        String auth = username + ":" + password;
        String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes(StandardCharsets.UTF_8));
        conn.setRequestProperty("Authorization", "Basic " + encodedAuth);
        conn.setRequestProperty("Content-Type", "application/json");

        conn.getOutputStream().write(requestBody.getBytes(StandardCharsets.UTF_8));

        int responseCode = conn.getResponseCode();

        if (responseCode == HttpURLConnection.HTTP_OK) {
            // Request succeeded, handle the response
            // ...
        } else {
            // Request failed
            // ...
        }

        conn.disconnect();
    }
}

Callbacks

📬Callbacks