AxtonPay API

Obecné informace

API koncový bod

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

Content-type

API přijímá HTTP požadavky se 2 typy obsahu: 'application/x-www-form-urlencoded', 'application/json'.

Hlavička HTTP by měla odpovídat obsahu POST těla.

Zkratky a definice

• {PID} - ID faktury, obvykle jde o unikátní 8-znakovou alfanumerickou sekvenci.
• Shop - Vaše webová stránka, která přijímá platby prostřednictvím služby AxtonPay

Algoritmus práce s API

Obvyklé postupy pro získání platby:

• vytvořit fakturu ('/api/v1/private/checkout/payment/create'), odpověď API vrátí URL faktury ('invoice_url'),
• pošlete kupujícího na tuto fakturu, aby provedl platbu,
• počkat na AxtonPay oznámení serveru, které přijdou na 'server_notification_url',
• po obdržení jakéhokoli oznámení od AxtonPay zkontrolujte platnost jeho podpisu a ideálně zašlete potvrzení o přijetí na AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• pokud je změněn stav faktury, proveďte akce odpovídající tomuto stavu (např. požádejte o úplné informace o faktuře, odešlete zboží, vytvořte tiket pro tým podpory atd.).

Pokud při vytváření faktury nastavíte prázdný nebo neplatný 'server_notification_url', služba nemůže odesílat oznámení o změnách stavu; v takovém případě byste měli fakturu sami kontrolovat v určitých intervalech ('/api/v1/private/checkout/payment/get/{PID}').

Autorizace požadavků

Pro autorizaci požadavku je nutné vypočítat hash ze řetězce vytvořeného speciálním způsobem. Řetězec se skládá spojením (lepením) argumentů URL (QUERY_STRING) a těla POST požadavku (REQUEST_BODY). Je důležité, aby všechny součásti byly vzaty přesně v takové podobě, v jaké budou odeslány na server. Argumenty URL (QUERY_STRING) by měly být vzaty z URL jako jediný řádek, bez změny pořadí argumentů a bez vynechání jakýchkoli prvků. Tělo POST požadavku (REQUEST_BODY) by mělo být také použito bez jakýchkoli úprav, včetně zachování uvozovek, mezer, závorek a zalomení řádků.

V případech prázdného POST těla požadavku a v případě prázdných argumentů URL bude tato složka jednoduše prázdný řetězec.

Pořadí dat v žádosti o podpis: QUERY_STRING nejprve, poté POST data. Mezi nimi byste neměli vkládat žádné spojovací znaky, jen spojte dva textové řetězce.

Ještě jednou, každý symbol je významný. Neměli byste přidávat ani odebírat ani jeden mezerník nebo znak nového řádku. Použijte pouze surová data přijatá serverem.

Z výsledného řetězce je odebrán SHA-256 hash s klíčem 'Secret key' a použit jako druhý argument funkce hash_hmac().

Je povinné předat parameter 'time' obsahující aktuální POSIX timestamp (Unix time).

Tento podpis je platný po dobu 24 hodin. Pokud se hodnota parametru 'time' liší od aktuálního času serveru o více než 24 hodin (dopředu nebo dozadu), požadavek selže i v případě, že je podpis vypočítán bez chyb.

Pokud obchodníkově panel akceptoval žádost s nějakým podpisem, tento podpis nemůže být použit znovu, ani k odeslání žádosti se stejnými parametry (to zahrnuje parametr 'time').

Výsledný hash je předán v hlavičce HTTP 'Sign'.

Kromě vypočítaného podpisu musí žádost také obsahovat 'Api-Key' hlavičku obsahující použitý API klíč. Příklad:

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

Můžete podepsat požadavek odeslaný na AxtonPay jakýmkoli platným klíčem, který patří k tomuto pokladnímu systému. Nicméně AxtonPay vždy používá klíč, který jste vybrali v panelu obchodníka.

Příklad výpočtu podpisu:

/* 
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'
*/

Věnujte pozornost mezerám a zalomením řádků v dalším příkladu:

/* 
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 příklad skládání řetězce pro výpočet podpisu:

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

Parametry

API přijímá všechny parametry jak v QUERY_STRING, tak v těle POST požadavku.

Booleanovské proměnné

API očekává získání '0' nebo '1' v Booleovských proměnných, ale kvůli implicitní konverzi typů bude jakýkoli textový řetězec považován za '1', dokonce i slovo 'false'. Chcete-li tedy explicitně nastavit hodnotu 'FALSE' pro Booleovskou proměnnou, musíte jí předat buď hodnotu '0', nebo prázdný řetězec.

Desetinný oddělovač

Jako desetinný oddělovač v číslech se používá pouze desetinná tečka.

Velikost písmen v parametrech

S několika výjimkami jsou všechny parametry rozlišující velikost písmen.

URL pro zpětné volání

V administračním panelu AxtonPay, na stránce nastavení pokladny, je možné nastavit URL obchodů pro příjem server-server notifikací od AxtonPay, stejně jako URL pro přesměrování kupujícího po zaplacení faktury nebo jejím zrušení, stejně jako v případě chyby.

Tyto URL lze přepsat v požadavku na vytvoření faktury.

Metody AxtonPay API

Vytváření faktur: /api/v1/private/checkout/payment/create

Metoda /api/v1/private/checkout/payment/create spouští vytvoření faktury.

Pokud je úspěšná, metoda vrátí odkaz ('invoice_url'), na který byste měli zákazníka přesměrovat k platbě.

Vlastní parametry faktury:

• time (povinné) - POSIX timestamp (Unix time)
• amount (povinné) - částka k zaplacení (cena produktu nebo služby, kterou chce obchod získat)
• currency (povinné) - Třípísmenný kód měny podle ISO 4217-alpha, bez ohledu na velikost písmen
• pms (povinné) - platební metody zobrazené na stránce faktury. Pokud chcete povolit všechny platební metody, hodnota je 'all'; pokud chcete povolit pouze některé z nich, vypište jejich číselné identifikátory oddělené čárkou.
• pm - identifikátor vybrané platební metody. Je důležité, že pokud je předán parametr 'pm', faktura bude vytvořena v 'transparentním režimu', tj. kupující neuvidí stránku s fakturou, ale půjde rovnou do platebního systému.
• extra_data - asociativní pole obsahující jakákoli další data; tato data jsou vrácena do úložiště v plném rozsahu
• shop_user_id - identifikátor uživatele v obchodě, je vrácen do obchodu v nezměněné podobě
• shop_payment_id - identifikátor platby v obchodě, je vrácen do obchodu v nezměněné podobě
• shop_name - název obchodu (zobrazený na stránce faktury)
• shop_payment_desc - popis objednávky (zobrazeno na stránce faktury)
• shop_payment_remark - vaše poznámky k této platbě (toto je pole pro jakékoli poznámky, které máte k platbě, které AxtonPay nikam nepředává; jsou viditelné pouze v seznamu plateb; nevrací se zpět do obchodu)
• valid_time - časový interval, ve kterém může být faktura uhrazena; v sekundách
• view_time - časový interval, během kterého je faktura dostupná k prohlížení přes externí odkaz; v sekundách; odpočet začíná po ukončení 'valid_time' období
• server_notification_method - způsob odesílání oznámení server-server o stavech plateb do obchodu; platné hodnoty: POST, GET

Některá nastavení faktury jsou nastavena na stránce nastavení pokladny. Ale hodnoty předané v požadavku mají přednost před těmito nastaveními.

Parametry pokladny, které lze pro tuto fakturu přepsat:

• customer_success_url - odkaz, na který bude kupující přesměrován, pokud bude faktura úspěšně zaplacena (tj. pokud je stav faktury 'paid' nebo 'overpaid').
• customer_cancel_url - odkaz, na který bude kupující přesměrován, pokud bude platba zrušena
• customer_fail_url - odkaz, na který bude kupující přesměrován, pokud platba skončí chybou
• server_notification_url - odkaz pro zasílání oznámení o stavech plateb server-server do obchodu

Poznámka: Aby bylo možné dodržet vlastní zásady ochrany soukromí, obvykle není nutné zahrnovat osobní údaje zákazníka do vlastností faktury. Například v parametru "shop_user_id" je lepší uvést abstraktní ID zákazníka než jeho e-mail nebo telefonní číslo. Také v "shop_payment_desc" je lepší zákaznické údaje vůbec nezahrnovat, protože už o sobě všechno vědí; místo toho můžete napsat nějaké informace o zaplaceném zboží nebo službách, nebo jen uvést typ akce, například „Nákup“ nebo „Doplnění zůstatku“.

Veškeré odkazy jsou nezbytně přenášeny s protokolem.

Příklad žádosti:

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

Příklad úspěšné odpovědi při žádosti o vytvoření faktury:

{
    "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"
}

Získávání informací o faktuře: /api/v1/private/checkout/payment/get/{PID}

Chcete-li získat potřebné informace, zavolejte metodu /api/v1/private/checkout/payment/get/{PID} a na konci URL uveďte PID faktury.

Parametry dotazu:

• time (povinné) - POSIX timestamp (Unix time)

Příklad řádku pro složení podpisu:

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

// String for signature calculation: 
time=1766837343

Příklad odpovědi:

{
    "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"
    }
}

Porovnání požadované částky a zaplacené částky

Odpověď obsahuje několik různých částek (v měně, ve které byla faktura vystavena):

• "amount" - fakturovaná částka,
• "filled" - část faktury zaplacena,
• "total_filled" - kolik klient celkem zaplatil, včetně provizí.

Pokud "filled = amount", pak je zaplaceno přesně tolik, kolik je potřeba.

Pokud "filled > amount", dochází k přeplatku.

Pokud "filled < amount", faktura nebyla uhrazena celá (nedoplatek).

Faktura: zpracování oznámení od AxtonPay o změně stavu

Pokaždé, když se změní stav faktury, AxtonPay pošle oznámení server_notification_url (pomocí server_notification_method)

Ukázková data:

{
    "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"
}

V reakci na toto oznámení očekává AxtonPay přijetí HTTP code 200, které potvrzuje jeho úspěšné doručení. Jinak bude AxtonPay opakovat pokus 12krát s postupně se zvyšujícími intervaly, a potom se stav oznámení změní na 'error' (ale toto neovlivňuje stav samotné faktury).

Možné hodnoty stavu:

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

Úspěšné stavy plateb jsou 1 (paid) a 5 (overpaid); v případě jejich přijetí můžete převést uhrazený nákup zákazníkovi nebo doplnit zůstatek. U plateb se stavem 5 (overpaid) můžete při doplnění zůstatku doplnit zůstatek částkou skutečně přijaté platby, ale v případě prodeje zboží/služeb a významné částky přeplatku je vhodné kontaktovat plátce a dohodnout se s ním, jak naložit s přeplatkem.

Částečně úspěšný stav je 4 (underpaid); v případě obdržení tohoto stavu je možné dobít zůstatek o částku skutečně přijaté platby. Tento stav však nelze považovat za úspěšný při prodeji zboží/služeb.

Všechny ostatní stavy - 0 (pending), 2 (error), 3 (canceled by customer) znamenají úplnou absenci platby; v případě jejich obdržení by neměly být prováděny žádné akce týkající se doplnění zůstatku nebo prodeje zboží/služeb.

Kontrola podpisu

Aby bylo jisté, že oznámení bylo odesláno přesně společností AxtonPay, je nutné před jeho důvěrou ověřit podpis přijatého oznámení. Ověření je podobné podepisování vlastních požadavků, pouze je přidán poslední krok, kdy byste měli porovnat vypočítaný podpis s přijatým HTTP hlavičkou 'Sign'.

Hlavní kroky po obdržení oznámení o změně stavu platby jsou následující:

• vezměte celý řetězec argumentů (QUERY_STRING) z přijatého oznámení,
• vezměte celé POST data (REQUEST_BODY) z přijatého oznámení,
• vypočítejte podpis pomocí těchto QUERY_STRING + REQUEST_BODY a příslušného 'Secret key',
• porovnat vypočítaný podpis s tím, který je přijat v HTTP hlavičce 'Sign',
• pokud jsou podpisy stejné, oznámení skutečně přišlo od AxtonPay;
• Pokud se podpisy liší, může se jednat o pokus o podvod ze strany plátce.

Příklad řádku pro generování podpisu:

// 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

Potvrzení, že obchod zpracoval platební informace: /api/v1/private/checkout/payment/confirm/{PID}

Tento požadavek je odeslán na AxtonPay jako odpověď na oznámení, které od něj bylo přijato. Funkčně je to potvrzení, že obchod úspěšně přijal a zpracoval přijaté oznámení.

Chcete-li odeslat požadavek, zavolejte metodu /api/v1/private/checkout/payment/confirm/{PID} a na konci URL uveďte pid faktury.

Parametry požadavku:

• time (povinné) - POSIX timestamp (Unix time)
• status (povinné, celé číslo) - číslo stavu platby, pro které obchod zasílá potvrzení

Pokud přenášený stav odpovídá aktuálnímu stavu této faktury v systému, AxtonPay odpoví s 'OK' a pokud neodpovídá, odpoví chybou.

Příklad řádku pro generování podpisu:

// 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"}

Příklad odpovědi, pokud je aktuální stav platby stejný:

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

Příklad odpovědi, pokud se aktuální stav platby liší od stavu zaslaného v žádosti:

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

Kódy měn

Měny, které lze použít pro vytvoření faktury.

Většina používaných měnových kódů patří k fiat měnám a jsou rovny ISO 4217. Seznam také obsahuje několik kryptoměn.