AxtonPay API

Загальна інформація

API кінцева точка

https://mp.axtonpay.com/api/v1/private/checkout

Content-type

API приймає HTTP запити з 2 типами вмісту: 'application/x-www-form-urlencoded', 'application/json'.

Заголовок HTTP повинен відповідати змісту POST тіла.

Скорочення та визначення

• {PID} - Ідентифікатор рахунку-фактури, зазвичай це унікальна 8-символьна алфавітно-цифрова послідовність.
• Shop - Ваш вебсайт, який приймає платежі через сервіс AxtonPay

Алгоритм роботи з API

Звичайна послідовність дій для отримання оплати:

• створіть рахунок-фактуру ('/api/v1/private/checkout/payment/create'), відповідь API поверне URL рахунку-фактури ('invoice_url'),
• надішліть покупцю цей рахунок-фактуру для здійснення оплати,
• чекай на AxtonPay повідомлення від сервера, які будуть надходити на 'server_notification_url',
• після отримання будь-якого повідомлення від AxtonPay, перевірте дійсність його підпису і, бажано, надішліть підтвердження отримання до AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• якщо статус рахунку-фактури змінюється, виконуйте дії, що відповідають цьому статусу (наприклад, запросити повну інформацію про рахунок-фактуру, відправити товари, створити звернення до служби підтримки тощо).

Якщо ви встановите порожній або недійсний 'server_notification_url' під час створення рахунку, сервіс не зможе надсилати сповіщення про зміни статусу; у таких випадках вам слід самостійно перевіряти рахунок через певні проміжки часу ('/api/v1/private/checkout/payment/get/{PID}').

Авторизація запитів

Щоб авторизувати запит, необхідно обчислити хеш із рядка, сформованого особливим чином. Рядок складається шляхом конкатенації (склеювання) аргументів URL (QUERY_STRING) та тіла POST запиту (REQUEST_BODY). Важливо, щоб всі компоненти були взяті саме в тій формі, в якій вони будуть передані на сервер. Аргументи URL (QUERY_STRING) слід брати з URL як один рядок, не змінюючи порядок аргументів і не пропускаючи жодного елемента. Тіло POST запиту (REQUEST_BODY) також повинно використовуватися без жодних змін, включаючи не видаляти з нього лапки, пробіли, дужки та розриви рядків.

У випадках порожнього POST тіла запиту та порожніх аргументів URL, той компонент просто буде порожнім рядком.

Послідовність даних у запиті на підпис: QUERY_STRING спочатку, потім POST дані. Не слід вставляти між ними жодних сполучних знаків, просто об’єднайте два текстові рядки.

Ще раз, кожен символ має значення. Не слід додавати або видаляти навіть пробіл чи символ нового рядка. Прямо використовуйте дані, отримані від сервера.

Хеш SHA-256 з ключем 'Secret key' береться з отриманого рядка і використовується як другий аргумент функції hash_hmac().

Обов'язково передати параметр 'time', що містить поточний POSIX timestamp (Unix time).

Цей підпис дійсний протягом 24 годин. Якщо значення параметра 'time' відрізняється від поточного часу сервера більш ніж на 24 години (вперед або назад), запит не буде виконаний, навіть якщо підпис обчислено без помилок.

Якщо панель торговця прийняла запит з певним підписом, той підпис не може бути використаний повторно, навіть для надсилання запиту з тими ж параметрами (це включає параметр 'time').

Отриманий хеш передається в заголовку HTTP 'Sign'.

На додаток до обчисленого підпису, запит також повинен містити заголовок 'Api-Key', що містить використаний API ключ. Приклад:

$headers = [
      'Api-Key: ' . $the_api_key,
      'Sign: ' . $signature_sha256
    ];

Ви можете підписати запит, надісланий до AxtonPay, будь-яким дійсним ключем, що належить цьому оформленню замовлення. Однак AxtonPay завжди використовує ключ, який ви обрали в панелі торговця.

Приклад обчислення підпису:

/* 
Imagine there is the POST request:
URI: '/api/v1/private/checkout/payment/create?time=1735084500.3561'
POST body: '[email protected]&shop_payment_id=INVOICE-1746&pms=all&amount=19.95&currency=USD'
So there are HTTP query string and request body:
*/ 
$the_query_string = 'time=1735084500.3561';
$the_request_body = '[email protected]&shop_payment_id=INVOICE-1746&pms=all&amount=19.95&currency=USD';

// • A pair of 'API key' and 'Secret key' gathered from the admin panel
$the_api_key = 'key1';
$the_api_secret = 'secret1';

// • Concatenation:
$string_for_sha = $the_query_string . $the_request_body;
// Value: '[email protected]&shop_payment_id=INVOICE-1746&pms=all&amount=19.95&currency=USD'

// • Calculating the HTTP header 'Sign'
// hash method is SHA-256
$signature_sha256 = hash_hmac("sha256", $string_for_sha, $the_api_secret); 
// '31ca271a15e45802e07b7559a5f520656c050dda79e6fa46d52a15fc51d193cd'

/* • Signed HTTP request:
  Method: POST
  URI: '/api/v1/private/checkout/payment/create?time=1735084500.3561'
  HTTP header 'Api-Key': 'key1'
  HTTP header 'Sign': '31ca271a15e45802e07b7559a5f520656c050dda79e6fa46d52a15fc51d193cd'
  POST body: '[email protected]&shop_payment_id=INVOICE-1746&pms=all&amount=19.95&currency=USD'
*/

Зверніть увагу на пробіли та розриви рядків у іншому прикладі:

/* 
Imagine there is the POST request:
URI: '/api/v1/private/checkout/payment/create?shop_name=Very%20useful%20service'
POST body: '{
  "shop_user_id": "[email protected]",
  "shop_payment_id": "INVOICE-1746",
  "shop_payment_desc": "Premium service
(1 month)",

  "pms": "all",
  "amount": "19.95",
  "currency": "USD",
  "time": "1735084500.3561"
}'

Attention! It's important to keep the raw data 'as is', including all tabulations, whitespaces, and line breaks. 
For example, the signature becomes invalid if your software formats json, adds or removes spaces. 

So there are such HTTP query string and POST request body:
*/ 
$the_query_string = 'shop_name=Very%20useful%20service';
$the_request_body = '{
  "shop_user_id": "[email protected]",
  "shop_payment_id": "INVOICE-1746",
  "shop_payment_desc": "Premium service
(1 month)",

  "pms": "all",
  "amount": "19.95",
  "currency": "USD",
  "time": "1735084500.3561"
}';

// • A pair of 'API key' and 'Secret key' gathered from the merchant panel
$the_api_key = 'key1';
$the_api_secret = 'secret1';

// • Concatenation:
//
// hash method is SHA-256 (HTTP query string + request body)
$string_for_sha = $the_query_string . $the_request_body;
/* Value: 'shop_name=Very%20useful%20service{
  "shop_user_id": "[email protected]",
  "shop_payment_id": "INVOICE-1746",
  "shop_payment_desc": "Premium service
(1 month)",

  "pms": "all",
  "amount": "19.95",
  "currency": "USD",
  "time": "1735084500.3561"
}'
*/

// • Calculating the HTTP header 'Sign'

$signature_sha256 = hash_hmac("sha256", $string_for_sha, $the_api_secret); 
// 'ef15476f28b379e4b137a2dcd9ed495332e4766004ac3610bb92a69ba2303c28'

/* • Signed HTTP request:
  Method: POST
  URI: '/api/v1/private/checkout/payment/create'
  HTTP header 'Api-Key': 'key1'
  HTTP header 'Sign': 'ef15476f28b379e4b137a2dcd9ed495332e4766004ac3610bb92a69ba2303c28'
  POST body: '{
  "shop_user_id": "[email protected]",
  "shop_payment_id": "INVOICE-1746",
  "shop_payment_desc": "Premium service
(1 month)",

  "pms": "all",
  "amount": "19.95",
  "currency": "USD",
  "time": "1735084500.3561"
}' 
*/

Python приклад складання рядка для обчислення підпису:

string_for_hash_calculation = f'{request.query_params.urlencode()}{request.data.urlencode()}'

Параметри

API приймає всі параметри як у QUERY_STRING, так і в тілі POST запиту.

Булеві змінні

API очікує отримати '0' або '1' у булевих змінних, але через неявне перетворення типів будь-який текстовий рядок буде розглядатися як '1', навіть слово 'false'. Отже, щоб явно встановити значення 'FALSE' для булевої змінної, потрібно передати їй або значення '0', або порожній рядок.

Десятковий роздільник

У числах як десятковий роздільник використовується лише десяткова крапка.

Регістр символів у параметрах

З кількома винятками всі параметри чутливі до регістру.

URL зворотного виклику

У панелі адміністратора AxtonPay на сторінці налаштувань оформлення замовлення можна встановити URL-адреси магазину для отримання сервер-серверних повідомлень від AxtonPay, а також URL-адреси для перенаправлення покупця після сплати або скасування рахунку, а також у разі помилки.

Ці URL-адреси можна змінити в запиті на створення рахунку.

Методи AxtonPay API

Створення рахунку: /api/v1/private/checkout/payment/create

Метод /api/v1/private/checkout/payment/create ініціює створення рахунку-фактури.

Якщо успішно, метод поверне посилання ('invoice_url'), на яке слід передати клієнта для оплати.

Власні параметри рахунка:

• time (обов'язково) - POSIX timestamp (Unix time)
• amount (обов'язково) - сума до сплати (ціна продукту або послуги, яку магазин хоче отримати)
• currency (обов'язково) - 3-літерний код валюти за ISO 4217-alpha, без урахування регістру
• pms (обов'язково) - методи оплати, відображені на сторінці рахунку. Якщо ви хочете дозволити всі методи оплати, значення - 'all'; якщо ви хочете дозволити лише деякі з них, перелікуйте їхні числові ідентифікатори через кому.
• pm - ідентифікатор обраного способу оплати. Важливо, що якщо передається параметр 'pm', рахунок буде створено в "прозорому режимі", тобто покупець не побачить сторінку рахунку, а одразу перейде до платіжної системи.
• extra_data - асоціативний масив, що містить будь-які додаткові дані; ці дані повертаються до сховища в повному обсязі
• shop_user_id - ідентифікатор користувача в магазині, він повертається до магазину у незмінному вигляді
• shop_payment_id - ідентифікатор платежу в магазині, він повертається до магазину в незмінній формі
• shop_name - назва магазину (відображається на сторінці рахунку)
• shop_payment_desc - опис замовлення (відображається на сторінці рахунку)
• shop_payment_remark - ваші нотатки щодо цього платежу (це поле для будь-яких нотаток щодо платежу, які AxtonPay нікуди не передає; вони видимі лише у списку платежів; вони не надсилаються назад до магазину)
• valid_time - інтервал часу, протягом якого рахунок-фактуру можна сплатити; у секундах
• view_time - часовий інтервал, протягом якого рахунок-фактура доступний для перегляду через зовнішнє посилання; у секундах; зворотний відлік починається після закінчення періоду 'valid_time'
• server_notification_method - метод надсилання сповіщень сервер-сервер про статуси платежів до магазину; допустимі значення: POST, GET

Деякі налаштування для рахунку-фактури встановлюються на сторінці налаштувань оформлення замовлення. Але значення, передані в запиті, будуть мати пріоритет над цими налаштуваннями.

Параметри оформлення замовлення, які можна змінити для цього рахунку:

• customer_success_url - посилання, на яке покупець буде перенаправлений, якщо рахунок успішно сплачено (тобто якщо статус рахунку 'paid' або 'overpaid').
• customer_cancel_url - посилання, на яке покупець буде перенаправлений у разі скасування платежу
• customer_fail_url - посилання, на яке покупець буде перенаправлений у разі помилки при оплаті
• server_notification_url - посилання для надсилання сервер-сервер повідомлень про статуси платежів до магазину

Примітка: Щоб відповідати вашій власній політиці конфіденційності, зазвичай не потрібно включати особисті дані ваших клієнтів у властивості рахунку-фактури. Наприклад, у параметрі "shop_user_id" краще вказувати абстрактний ідентифікатор клієнта замість його електронної пошти або номера телефону. Також у "shop_payment_desc" краще взагалі не включати дані клієнта, оскільки вони і так уже знають про себе все; натомість можна написати якусь інформацію про оплачений товар або послуги, або навіть просто вказати тип дії, наприклад, "Покупка" або "Поповнення балансу".

Усі посилання обов'язково передаються разом із протоколом.

Приклад запиту:

<?php
// API credentials - get it from settings of the checkout
$api_key = 'API_KEY';
$api_secret = 'API_SECRET';
// API endpoint
$api_endpoint = 'https://mp.axtonpay.com/api/v1/private/checkout';
// Current POSIX timestamp
$time = time();
// API method URL
$api_url = $api_endpoint . '/payment/create';

// Prepare POST parameters
$post_data = [
    'amount' => 4.99,
    'currency' => 'USD',
    'pms' => 'all', // visible payment methods; either 'all' or comma-separated list of selected GUIDs
    // 'pm' => '92807385', // define the certain payment method if you do not want payer to see the list of all possible payment methods

    // Below parameters are optional
    'extra_data' => ['param1'=>'value 1', 'param2'=>'value 2'],

    'shop_user_id' => '[email protected]',
    'shop_payment_id' => 'TEST-333-' . $time,
    'shop_name' => 'TEST-333 web shop',
    'shop_payment_desc' => 'TEST-333 payment description visible to payer',
    'shop_payment_remark' => 'TEST-333 payment remark for admin',

    'customer_success_url' => 'https://example.com/?status=paid-or-overpaid&once=TEST-333-' . $time, 
    'customer_cancel_url' => 'https://example.com/?status=cancelled-by-payer&once=TEST-333-' . $time,
    'customer_fail_url' => 'https://example.com/?status=error&once=TEST-333-' . $time,
    'server_notification_url' => 'https://example.com/?for=server-to-server-notificataions',
    'server_notification_method' => 'POST',
	
    'valid_time' => 60*60*24*7, // seconds
    'view_time'  => 60*60*24*21, // seconds, clock starts after ending of 'valid_time' period
];

// Prepare GET parameters
$query_string = 'time=' . $time;

// Build the request body
$request_body = json_encode($post_data); // Encode as JSON
// $request_body = http_build_query($post_data);

// Concatenate QUERY_STRING and REQUEST_BODY
$string_for_sha = $query_string . $request_body;

// Calculate the signature
$signature = hash_hmac('sha256', $string_for_sha, $api_secret);

// Prepare HTTP headers
$headers = [
    'Api-Key: ' . $api_key,
    'Sign: ' . $signature,
    'Content-Type: application/json'
];

// Initialize cURL
$ch = curl_init($api_url . '?' . $query_string);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request_body);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

// Execute the request
$response = curl_exec($ch);

// Close cURL
curl_close($ch);
?>

Приклад успішної відповіді під час запиту на створення рахунку:

{
    "status": "ok",
    "data": "invoice created",
    "pid": "HNQ5CAHM",
    "test": false,
    "created_at": "2025-12-27T08:14:55.000000Z",
    "invoice_url": "https:\/\/27375212.b88pay.com\/i\/HNQ5CAHM"
}

Отримання інформації про рахунок-фактуру: /api/v1/private/checkout/payment/get/{PID}

Щоб отримати необхідну інформацію, потрібно викликати метод /api/v1/private/checkout/payment/get/{PID}, вказавши PID рахунку в кінці URL.

Параметри запиту:

• time (обов'язково) - POSIX timestamp (Unix time)

Приклад рядка для створення підпису:

// Full URL:
https://mp.axtonpay.com/api/v1/private/checkout/payment/get/GIKR3XPY?time=1766837343

// String for signature calculation: 
time=1766837343

Приклад відповіді:

{
    "status": "ok",
    "data": {
        "pid": "HNQ5CAHM",
        "checkout_guid": 34677320,
        "created_at": "2025-12-27 12:07:21",
        "updated_at": "2025-12-27 12:07:34",
        "data": {
            "ip": "1.2.3.4",
            "pms": "all",
            "extra_data": {
                "param1": "val1",
                "param2": "val2",
                "server_notification_url": "https:\/\/example.com\/?for=server-to-server-notificataions"
            },
            "redirect_url": "\/wait\/HNQ5CAHM",
            "customer_fail_url": "https:\/\/example.com\/?status=error&id=TEST-333-1766837240",
            "allow_change_amount": false,
            "customer_cancel_url": "https:\/\/example.com\/?status=cancelled-by-payer&id=TEST-333-1766837240",
            "customer_success_url": "https:\/\/example.com\/?status=paid-or-overpaid&id=TEST-333-1766837240"
        },
        "payment_status": 0,
        "amount": "4.99",
        "filled": "0.00",
        "currency_id": 5,
        "transparent": 1,
        "expires_at": "2026-01-03 12:07:21",
        "invisible_at": "2026-01-26 12:07:21",
        "paid_at": null,
        "confirmed_at": null,
        "shop_name": "TEST-333 web shop",
        "shop_user_id": "[email protected]",
        "shop_payment_id": "TEST-333-1766837240",
        "shop_payment_desc": "TEST-333 payment description visible to payer",
        "shop_payment_remark": "TEST-333 payment remark for merchant",
        "payment_method_id": 92807385,
        "gateway_id": 40056646,
        "payment_option_id": 297,
        "txid": null,
        "account_from": null,
        "account_to": "TEnYvbfg9YqJeaVtVHAwEvG2kmAJcTzxTh",
        "payment_option_amount": "17.865973",
        "payment_option_filled": "0.000000",
        "payment_option_currency_id": 317,
        "exchange_rates_expires_at": "2025-12-27 12:27:33",
        "test": false,
        "initiator": "api",
        "initiator_info": null,
        "payment_option": {
            "id": 297,
            "gateway_id": 40056646,
            "pm": "trx",
            "currency_id": 317,
            "name": "Tron",
            "icon": "crypto\/tron.png",
            "min_invoice": null,
            "max_invoice": null
        },
        "payment_option_currency": {
            "id": 317,
            "name": "Tron",
            "code": "TRX",
            "minor_unit": 6
        },
        "currency": {
            "id": 5,
            "name": "United States dollar",
            "code": "USD",
            "minor_unit": 2
        },
        "invoice_url": "https:\/\/27375212.b88pay.com\/i\/HNQ5CAHM"
    }
}

Порівняння запитаної суми та сплаченої суми

Відповідь містить кілька різних сум (у валюті, в якій був виставлений рахунок):

• "amount" - рахована сума,
• "filled" - сплачено частину рахунку
• "total_filled" - скільки клієнт заплатив загалом, включаючи комісії.

Якщо "filled = amount", тоді за це платять саме стільки, скільки потрібно.

Якщо "filled > amount", є переплата.

Якщо "filled < amount", рахунок не сплачено повністю (недоплата).

Рахунок-фактура: обробка повідомлення від AxtonPay про зміну статусу

Кожного разу, коли змінюється статус рахунку-фактури, AxtonPay надсилає повідомлення server_notification_url (використовуючи server_notification_method)

Приклад даних:

{
    "pid": "U5IB4WIO",
    "status": "3",
    "shop_user_id": "3q23g",
    "shop_payment_id": "h76r5",
    "amount": "240.00000000",
    "filled": "0.00000000",
    "fee": "0",
    "total_filled": "0.00000000",
    "currency": "DASH",
    "test": "0"
}

У відповідь на це сповіщення AxtonPay очікує отримати HTTP code 200, що підтверджує його успішне отримання. Інакше AxtonPay спробує ще 12 разів із поступово збільшуваними інтервалами, після чого статус сповіщення змінюється на 'error' (але це не впливає на статус самого рахунку-фактури).

Можливі значення статусу:

• 0 - pending
• 1 - paid
• 2 - error
• 3 - cancelled by customer
• 4 - underpaid
• 5 - overpaid
• 8 - expired

Статуси успішної оплати 1 (paid) та 5 (overpaid); у разі їх отримання ви можете перевести оплачену покупку клієнту або поповнити баланс. Для оплат зі статусом 5 (overpaid), у разі поповнення балансу, ви можете поповнити баланс на суму фактично отриманого платежу, але у разі продажу товарів/послуг та значної переплати доцільно звернутися до платника та домовитися з ним, як вчинити з переплатою.

Статус частково успішно - 4 (underpaid); у разі отримання цього статусу можливо поповнити баланс на суму фактично отриманого платежу. Однак цей статус не можна вважати успішним для продажу товарів/послуг.

Усі інші статуси - 0 (pending), 2 (error), 3 (canceled by customer) означають повну відсутність оплати; у разі їх отримання жодні дії щодо поповнення балансу або продажу товарів/послуг не повинні виконуватися.

Перевірка підпису

Щоб упевнитися, що сповіщення надіслано саме AxtonPay, необхідно перевірити підпис отриманого сповіщення перед тим, як довіряти йому. Перевірка схожа на підписання власних запитів, лише додається останній крок, коли потрібно порівняти обчислений підпис із отриманим HTTP-заголовком 'Sign'.

Основні кроки після отримання повідомлення про зміну статусу платежу є наступними:

• візьміть весь рядок аргументів (QUERY_STRING) з отриманого повідомлення,
• візьміть всю POST data (REQUEST_BODY) з отриманого повідомлення,
• обчисліть підпис, використовуючи ті QUERY_STRING + REQUEST_BODY та відповідний 'Secret key',
• порівняйте обчислений підпис із тим, що отримано в HTTP-заголовку 'Sign',
• якщо підписи однакові, повідомлення дійсно надійшло від AxtonPay;
• якщо підписи відрізняються, це може бути спробою шахрайства з боку платника.

Приклад рядка для генерації підпису:

// Full URL:
https://EXAMPLE.COM?time=1737027838.1237

// POST body: 
pid=ABCD5678&status=1&shop_user_id=&shop_payment_id=&amount=25.00000000&filled=25.00000000&fee=0&total_filled=25.00000000&currency=RDD&test=0

// String for signature calculation: 
time=1737027838.1237pid=ABCD5678&status=1&shop_user_id=&shop_payment_id=&amount=25.00000000&filled=25.00000000&fee=0&total_filled=25.00000000&currency=RDD&test=0

Підтвердження того, що магазин обробив інформацію про оплату: /api/v1/private/checkout/payment/confirm/{PID}

Цей запит надсилається до AxtonPay у відповідь на отримане від нього повідомлення. Функціонально це підтвердження того, що магазин успішно отримав і обробив отримане повідомлення.

Щоб надіслати запит, викликайте метод /api/v1/private/checkout/payment/confirm/{PID}, зазначивши pid рахунку в кінці URL.

Параметри запиту:

• time (обов'язково) - POSIX timestamp (Unix time)
• status (обов'язково, ціле число) - номер статусу платежу, для якого магазин надсилає підтвердження

Якщо переданий статус відповідає поточному статусу цього рахунку в системі, AxtonPay відповість 'OK', а якщо не відповідає, він відповість помилкою.

Приклад рядка для генерації підпису:

// Full URL:
https://mp.axtonpay.com/api/v1/private/checkout/payment/confirm/ABCD5678?time=1737011414

// POST body: 
{"status":"1"}

// String for signature calculation:
time=1737011414{"status":"1"}

Приклад відповіді, якщо поточний статус оплати залишається тим самим:

{
    "status": "ok",
    "data": "\"Paid\" status notification is confirmed"
}

Приклад відповіді, якщо поточний статус оплати відрізняється від того, що був зазначений у запиті:

{
    "status": "error",
    "message": "Something went wrong"
}

Коди валют

Валюти, які можна використовувати для створення рахунку-фактури.

Більшість використовуваних кодів валют належать до фіатних валют, і вони рівні ISO 4217. Також у списку є кілька криптовалют.