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.

Query parameters:

• 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. Также в списке есть несколько криптовалют.