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. Списъкът също така съдържа няколко криптовалути.