AxtonPay API

Splošne informacije

API končna točka

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

Content-type

API sprejema HTTP zahteve z 2 vrstama vsebine: 'application/x-www-form-urlencoded', 'application/json'.

Glava HTTP naj se ujema z vsebino POST telesa.

Okrajšave in definicije

• {PID} - ID računa, običajno je to edinstvena 8-mestna alfanumerična zaporedna koda.
• Shop - Vaša spletna stran, ki sprejema plačila preko storitve AxtonPay

Algoritem dela z API-jem

Običajen vrstni red dejanj za prejem plačila:

• ustvari račun ('/api/v1/private/checkout/payment/create'), odziv API-ja bo vrnil URL računa ('invoice_url'),
• pošljite kupca na ta račun, da izvede plačilo,
• počakajte na AxtonPay obvestila strežnika, ki bodo prispela na 'server_notification_url',
• ob prejemu katere koli obvestila od AxtonPay, preverite veljavnost njegovega podpisa in po možnosti pošljite potrdilo o prejemu AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• če se status računa spremeni, izvedite dejanja, ki ustrezajo temu statusu (npr. zahtevajte popolne informacije o računu, pošljite blago, ustvarite zahtevek za podporno ekipo itd.).

Če nastavite prazno ali neveljavno 'server_notification_url' pri ustvarjanju računa, storitev ne more pošiljati obvestil o spremembah stanja; v takih primerih morate račun sami preveriti v določenem intervalu ('/api/v1/private/checkout/payment/get/{PID}').

Pooblastitev zahtev

Za avtorizacijo zahteve je potrebno izračunati hash iz niza, oblikovanega na poseben način. Niz je sestavljen z združevanjem (lepljenjem skupaj) URL argumentov (QUERY_STRING) in telesa POST zahteve (REQUEST_BODY). Pomembno je, da so vsi deli vzeti natančno v obliki, v kateri bodo poslani strežniku. URL argumenti (QUERY_STRING) morajo biti vzeti iz URL-ja kot ena vrstica, brez spreminjanja vrstnega reda argumentov in brez izpuščanja posameznih elementov. Telo POST zahteve (REQUEST_BODY) je treba prav tako uporabiti brez kakršnih koli sprememb, kar vključuje, da ne smete odstranjevati narekovajev, presledkov, oklepajev, preloma vrstic.

V primerih praznega POST telesa zahteve in v primeru praznih URL argumentov bo ta komponenta preprosto prazen niz.

Zaporedje podatkov v zahtevi za podpis: QUERY_STRING najprej, nato POST podatki. Med njima ne smete vstaviti nobenih povezalnih znakov, le združite dve besedilni nizi.

Še enkrat, vsak simbol je pomemben. Ne smete dodajati ali odstranjevati celo presledka ali znaka za novo vrstico. Uporabite samo surove podatke, prejete od strežnika.

Haš SHA-256 s ključem 'Secret key' se vzame iz nastalega niza in uporabi kot drugi argument funkcije hash_hmac().

Obvezno je posredovati parameter 'time', ki vsebuje trenutni POSIX timestamp (Unix time).

Ta podpis velja 24 ur. Če se vrednost parametra 'time' razlikuje od trenutnega čas serverja za več kot 24 ur (naprej ali nazaj), bo zahteva neuspešna, tudi če je podpis izračunan brez napak.

Če trgovski panel sprejme zahtevo z določenim podpisom, tega podpisa ni mogoče uporabiti znova, tudi za pošiljanje zahteve z enakimi parametri (to vključuje parameter 'time').

Rezultantni zgoščeni zapis se pošlje v glavi HTTP 'Sign'.

Poleg izračunanega podpisa mora zahteva vsebovati tudi 'Api-Key' glavo, ki vsebuje uporabljen API ključ. Primer:

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

Zahtevo, poslano AxtonPay, lahko podpišete z katerim koli veljavnim ključem, ki pripada temu blagajniškemu sistemu. Vendar pa AxtonPay vedno uporablja ključ, ki ste ga izbrali v trgovinskem panelu.

Primer izračuna podpisa:

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

Posvetite pozornost presledkom in prelomom vrstic v drugem primeru:

/* 
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 primer sestavljanja niza za izračun podpisa:

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

Parametri

API sprejema vse parametre tako v QUERY_STRING kot v telesu POST zahteve.

Booleove spremenljivke

API pričakuje, da bo dobil '0' ali '1' v Boolean spremenljivkah, vendar zaradi implicitne pretvorbe tipov bo katera koli besedilna niza obravnavana kot '1', celo beseda 'false'. Torej, da eksplicitno nastavite vrednost 'FALSE' za Boolean spremenljivko, ji morate predati bodisi vrednost '0' bodisi prazen niz.

Decimalni ločevalnik

V številkah se kot decimalna ločila uporablja samo decimalna vejica.

Velikost črk v parametrih

Z redkimi izjemami so vsi parametri občutljivi na velike in male črke.

URL za klic nazaj

V administracijskem panelu AxtonPay je na strani z nastavitvami blagajne mogoče nastaviti URL-je trgovine za prejemanje obvestil strežnik-strežnik od AxtonPay, kot tudi URL-je za preusmeritev kupca po plačilu računa ali njegovi preklici, pa tudi v primeru napake.

Te URL-je je mogoče prepisati v zahtevi za ustvarjanje računa.

Metode AxtonPay API

Ustvarjanje računa: /api/v1/private/checkout/payment/create

Metoda /api/v1/private/checkout/payment/create sproži ustvarjanje računa.

Če je uspešna, metoda vrne povezavo ('invoice_url'), na katero morate napotiti stranko za plačilo.

Lastni parametri računa:

• time (zahtevano) - POSIX timestamp (Unix time)
• amount (zahtevano) - znesek za plačilo (cena izdelka ali storitve, ki jo trgovina želi prejeti)
• currency (zahtevano) - 3-mestna koda valute po ISO 4217-alpha, neobčutljivo na velike in male črke
• pms (zahtevano) - Na strani računa so prikazani načini plačila. Če želite dovoliti vse načine plačila, je vrednost 'all'; če želite dovoliti samo nekatere, navedite njihove številčne identifikatorje, ločene z vejico.
• pm - identifikator izbranega načina plačila. Pomembno je, da če je parameter 'pm' poslan, bo račun ustvarjen v 'prozornem načinu', tj. kupec ne bo videl strani računa, ampak bo šel neposredno do plačilnega sistema.
• extra_data - asociativno polje, ki vsebuje dodatne podatke; ti podatki se v celoti vrnejo v trgovino
• shop_user_id - uporabniški identifikator v trgovini, se vrne v trgovino v nespremenjeni obliki
• shop_payment_id - identifikator plačila v trgovini, je vrnjen trgovini v nespremenjeni obliki
• shop_name - ime trgovine (prikazano na strani računa)
• shop_payment_desc - opis naročila (prikazan na strani računa)
• shop_payment_remark - vaše opombe o tem plačilu (to je polje za vse opombe, ki jih imate o plačilu, ki jih AxtonPay nikjer ne posreduje; vidno je samo na seznamu plačil; ne vrne se v trgovino)
• valid_time - časovno obdobje, v katerem je mogoče račun plačati; v sekundah
• view_time - časovno obdobje, v katerem je račun na voljo za ogled preko zunanje povezave; v sekundah; odštevanje se začne po koncu obdobja 'valid_time'
• server_notification_method - metoda pošiljanja obvestil strežnik-strežnik o statusih plačil v trgovino; veljavne vrednosti: POST, GET

Nekate nastavitve za račun so določene na strani nastavitev plačila. Vendar pa bodo vrednosti, poslane v zahtevi, imele prednost pred temi nastavitvami.

Parametri blagajne, ki jih je mogoče spremeniti za ta račun:

• customer_success_url - povezava, na katero bo kupec preusmerjen, če bo račun uspešno plačan (tj. če je stanje računa 'paid' ali 'overpaid').
• customer_cancel_url - povezava, na katero bo kupec preusmerjen, če bo plačilo preklicano
• customer_fail_url - povezava, na katero bo kupec preusmerjen, če se plačilo konča z napako
• server_notification_url - povezava za pošiljanje obvestil o statusih plačil med strežnikom in strežnikom v trgovino

Opomba: Da bi upoštevali svojo politiko zasebnosti, običajno ni potrebno vključevati osebnih podatkov vaših strank v lastnosti računa. Na primer, v parametru "shop_user_id" je bolje navesti abstraktno ID stranke namesto njihovega e-poštnega naslova ali telefonske številke. Prav tako v "shop_payment_desc" je bolje ne vključevati podatkov o stranki, saj že poznajo vse o sebi; namesto tega lahko napišete nekaj informacij o kupljenem blagu ali storitvah, ali pa preprosto navedete vrsto dejanja, na primer "Nakup" ali "Polog na račun".

Vse reference so nujno posredovane s protokolom.

Primer zahteve:

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

Primer uspešnega odgovora pri zahtevi za izdajo računa:

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

Pridobivanje podatkov o računu: /api/v1/private/checkout/payment/get/{PID}

Za pridobitev informacij morate klicati metodo /api/v1/private/checkout/payment/get/{PID}, tako da na koncu URL-ja navedete PID računa.

Parametri poizvedbe:

• time (zahtevano) - POSIX timestamp (Unix time)

Primer vrstice za sestavo podpisa:

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

// String for signature calculation: 
time=1766837343

Primer odgovora:

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

Primerjava zahtevane vs plačane vsote

Odgovor vsebuje več različnih zneskov (v valuti, v kateri je bil izdan račun):

• "amount" - zaračunani znesek,
• "filled" - plačan del računa,
• "total_filled" - koliko je stranka skupaj plačala, vključno s provizijami.

Če "filled = amount", potem je plačano točno toliko, kolikor je potrebno.

Če "filled > amount", obstaja preplačilo.

Če "filled < amount", račun ni bil plačan v celoti (podplačilo).

Račun: obdelava obvestila od AxtonPay o spremembi statusa

Vsakič, ko se spremeni status računa, AxtonPay pošlje obvestilo server_notification_url (z uporabo server_notification_method)

Primer podatkov:

{
    "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 odgovoru na to obvestilo AxtonPay pričakuje prejeti HTTP code 200, kar potrjuje njegovo uspešno prejem. V nasprotnem primeru bo AxtonPay poskusil še 12-krat z vedno daljšimi intervali, nato pa se stanje obvestila spremeni v 'error' (vendar to ne vpliva na stanje samega računa).

Možne vrednosti stanja:

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

Uspešni statusi plačila so 1 (paid) in 5 (overpaid); ob njihovem prejemu lahko plačano nakupnino prenesete na kupca ali dopolnite stanje. Pri plačilih s statusom 5 (overpaid) lahko v primeru dopolnitve stanja stanje dopolnite za znesek dejansko prejetega plačila, vendar v primeru prodaje blaga/storitev in znatnega zneska preplačila je priporočljivo, da se obrnete na plačnika in se z njim dogovorite, kako ravnati s preplačilom.

Delno uspešen status je 4 (underpaid); v primeru prejema tega statusa je mogoče ponovno napolniti stanje za znesek dejansko prejetega plačila. Vendar pa tega statusa ne moremo šteti za uspešnega pri prodaji blaga/storitev.

Vsi ostali statusi - 0 (pending), 2 (error), 3 (canceled by customer) pomenijo popolno odsotnost plačila; v primeru njihove prejema ne smejo biti izvedena nobena dejanja glede polnjenja stanja ali prodaje blaga/storitev.

Preverjanje podpisa

Da ste prepričani, da je obvestilo poslano natančno s strani AxtonPay, je potrebno preveriti podpis prejetega obvestila, preden mu zaupate. Preverjanje je podobno podpisovanju lastnih zahtevkov, le da je dodan zadnji korak, ko morate primerjati izračunani podpis s prejetim HTTP headerjem 'Sign'.

Glavni koraki po prejemu obvestila o spremenjenem stanju plačila so naslednji:

• vzemite celoten niz argumentov (QUERY_STRING) iz prejetega obvestila,
• vzemite celoten POST data (REQUEST_BODY) iz prejete obvestila,
• izračunajte podpis z uporabo tistih QUERY_STRING + REQUEST_BODY in ustreznega 'Secret key',
• primerjajte izračunani podpis s tistim, ki je prejet v glavi HTTP 'Sign',
• če so podpisi isti, je obvestilo res prišlo od AxtonPay;
• Če so podpisi različni, je to morda poskus goljufije s strani plačnika.

Primer vrstice za generiranje podpisa:

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

Potrditev, da je trgovina obdelala podatke o plačilu: /api/v1/private/checkout/payment/confirm/{PID}

Ta zahteva je poslana AxtonPay kot odgovor na prejeto obvestilo od njega. Funkcionalno gre za potrditev, da je trgovina uspešno prejela in obdelala prejeto obvestilo.

Za pošiljanje zahteve pokličite metodo /api/v1/private/checkout/payment/confirm/{PID}, tako da na koncu URL-ja navedete pid računa.

Parametri zahteve:

• time (zahtevano) - POSIX timestamp (Unix time)
• status (zahtevano, celo število) - številka stanja plačila, za katero trgovina pošlje potrdilo

Če se preneseno stanje ujema s trenutnim stanjem tega računa v sistemu, bo AxtonPay odgovoril z 'OK', če pa se ne ujema, bo odgovoril z napako.

Primer vrstice za generiranje podpisa:

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

Primer odgovora, če je trenutni status plačila enak:

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

Primer odgovora, če se trenutni status plačila razlikuje od tistega, poslanega v zahtevi:

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

Valutne kode

Valute, ki jih je mogoče uporabiti za izdajo računa.

Večina uporabljenih valutnih kod pripada fiat valutam in so enake ISO 4217. Seznam vsebuje tudi nekaj kriptovalut.