# Payment

{% hint style="info" %}
**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.
{% endhint %}

## Test Payment Cards

<table><thead><tr><th width="367">Cards</th><th>Authorization</th></tr></thead><tbody><tr><td>2200112611773794</td><td>3Ds 2.0</td></tr><tr><td>4439970000000007</td><td>3Ds 2.0</td></tr><tr><td>5136914521003242</td><td>3Ds 1.0</td></tr><tr><td>4047300000007550</td><td>without 3Ds</td></tr></tbody></table>

**CVC – any value , ExpirationDate > current day**

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

{% hint style="info" %}
The use of this method assumes mandatory compliance of the merchant's system with PCI DSS requirements.
{% endhint %}

## Creating a new payment

To initiate a payment, please send a <mark style="color:green;">POST</mark> 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.

```json5
{
    "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": "test.testov@email.com"
}

```

## Create payment.

<mark style="color:green;">`POST`</mark> `https://{url}.finipay.kg/api/v1.1.0/payment`

Creates a new payment.

#### Request Body

| Name                                          | Type    | Description                                                              |
| --------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| orderNumber<mark style="color:red;">\*</mark> | string  | The unique number of transaction                                         |
| description<mark style="color:red;">\*</mark> | string  | The description of transaction                                           |
| amount<mark style="color:red;">\*</mark>      | decimal | Min value = 1                                                            |
| currency<mark style="color:red;">\*</mark>    | string  | Example: "EUR", "USD", 3 symbols                                         |
| pan<mark style="color:red;">\*</mark>         | string  | Full card number, pan length must between 13 to 20!                      |
| expiryMonth<mark style="color:red;">\*</mark> | string  | length = 2, example: "06"                                                |
| expiryYear<mark style="color:red;">\*</mark>  | integer | length = 4, example: 2023                                                |
| cvc<mark style="color:red;">\*</mark>         | string  | CVC Code, length = 3                                                     |
| language<mark style="color:red;">\*</mark>    | string  | length = 2, example: "en"                                                |
| name<mark style="color:red;">\*</mark>        | 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<mark style="color:red;">\*</mark> | string  | Your callback service                                                    |
| ip<mark style="color:red;">\*</mark>          | 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

{% tabs %}
{% tab title="110: Created" %}
```json5
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"
    }
}
```
{% endtab %}

{% tab title="1: Error" %}
```json
{
    "code": "1",
    "message": "ERROR",
    "data": null
}
```
{% endtab %}

{% tab title="400: Bad Request " %}
```json5
{
    "timestamp": "2025-04-30T11:29:24.153+00:00",
    "status": 400,
    "error": "Bad Request",
    "path": "/api/v1.1.0/payment"
}
```
{% endtab %}

{% tab title="112: DUPLCATED_ORDER_ID" %}
```json
{
    "code": "112",
    "message": "Транзакция с данным id уже существует в системе",
    "data": null
}
```
{% endtab %}

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

{% tab title="135: SERVICE_ERROR" %}
<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "code": "135",
    "message": "SERVICE_ERROR",
    "data": null
}
</code></pre>
{% endtab %}
{% endtabs %}

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

{% content-ref url="../status-codes" %}
[status-codes](../status-codes)
{% endcontent-ref %}



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

<figure><img src="https://2518184870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW9ICrIOe2QJxCbO3qOJi%2Fuploads%2FkoiltK5rfM7BmPyADLsy%2Fimage.png?alt=media&#x26;token=2494123c-49f3-4baa-b4ca-3c3d426a171b" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://2518184870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FW9ICrIOe2QJxCbO3qOJi%2Fuploads%2Fujk6IlmUB8JxFmGATgn5%2Fimage.png?alt=media&#x26;token=a16e107d-14d6-4146-b956-c4d2b5adcab4" alt=""><figcaption></figcaption></figure>

#### **redirect: https://example.com/?OrderNumber=**&#x38;983213&#x38;**\&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.

{% tabs %}
{% tab title="PHP" %}
```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' => 'test.testov@email.com'
];

$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;
}

?>
```
{% endtab %}

{% tab title="C#" %}
```csharp
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 = "test.testov@email.com"
        };

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

```
{% endtab %}

{% tab title="Axios(node.js)" %}
```javascript
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: 'test.testov@email.com'
};

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

```
{% endtab %}

{% tab title="Java" %}
```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\": \"test.testov@email.com\"\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();
    }
}
```
{% endtab %}
{% endtabs %}

**Callbacks**

{% content-ref url="../callbacks" %}
[callbacks](../callbacks)
{% endcontent-ref %}

