AxtonPay API

Opšte informacije

API krajnja tačka

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

Content-type

API prihvata HTTP zahteve sa 2 tipa sadržaja: 'application/x-www-form-urlencoded', 'application/json'.

HTTP zaglavlje treba da odgovara sadržaju POST tela.

Skraćenice i definicije

• {PID} - ID fakture, obično je to jedinstvena 8-karakterna alfanumerička sekvenca.
• Shop - Vaš vebsajt koji prihvata uplate putem AxtonPay servisa

Algoritam rada sa API-jem

Uobičajeni redosled radnji za primanje uplate:

• napravite fakturu ('/api/v1/private/checkout/payment/create'), API odgovor će vratiti URL fakture ('invoice_url'),
• pošaljite kupcu ovu fakturu kako bi izvršio plaćanje,
• čekaj obaveštenja servera AxtonPay, koja će stići na 'server_notification_url',
• po prijemu bilo kakve obaveštenja od AxtonPay, proverite validnost njegovog potpisa i po mogućstvu pošaljite potvrdu prijema AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• ako se status fakture promeni, izvršite radnje koje odgovaraju tom statusu (npr. zatražite potpune informacije o fakturi, pošaljite robu, kreirajte tiket za tim za podršku itd.).

Ako postavite prazno ili nevažeće 'server_notification_url' prilikom kreiranja fakture, servis neće moći da šalje obaveštenja o promenama statusa; u takvim slučajevima, trebalo bi da sami proveravate fakturu u nekom intervalu ('/api/v1/private/checkout/payment/get/{PID}').

Ovlašćivanje zahteva

Da bi se autorizovao zahtev, potrebno je izračunati Hash iz stringa formiranog na poseban način. String se sastoji od povezivanja (lepljenja) URL argumenata (QUERY_STRING) i tela POST zahteva (REQUEST_BODY). Važno je da svi delovi budu uzeti tačno u obliku u kojem će biti poslati serveru. URL argumenti (QUERY_STRING) treba da budu uzeti iz URL-a kao jedna linija, bez promene redosleda argumenata i bez izostavljanja bilo kojih elemenata. Telo POST zahteva (REQUEST_BODY) takođe treba koristiti bez ikakvih izmena, uključujući da se iz njega ne uklanjaju navodnici, razmaci, zagrade, prelomi linija.

U slučajevima praznog POST tela zahteva, i u slučaju praznih URL argumenata, ta komponenta će jednostavno biti prazan string.

Redosled podataka u zahtevu za potpisivanje: QUERY_STRING prvo, zatim POST podaci. Ne biste smeli da ubacujete bilo kakve spojnice između njih, samo spojite dva tekstualna niza.

Još jednom, svaki simbol je značajan. Ne bi trebalo da dodajete ili uklanjate čak ni razmak ili simbol novog reda. Samo koristite sirove podatke primljene od servera.

SHA-256 haš sa ključem 'Secret key' se uzima iz dobijenog niza i koristi kao drugi argument funkcije hash_hmac().

Obavezno je proslediti 'time' parametar koji sadrži trenutni POSIX timestamp (Unix time).

Ovaj potpis važi 24 sata. Ako vrednost 'time' parametra odstupa od trenutnog vremena servera za više od 24 sata (bilo unapred ili unazad), zahtev će biti neuspešan čak i ako je potpis izračunat bez grešaka.

Ako trgovački panel prihvati zahtev sa nekim potpisom, taj potpis se ne može ponovo koristiti, čak ni za slanje zahteva sa istim parametrima (ovo uključuje parametar 'time').

Dobijeni heš se prosleđuje u HTTP zaglavlju 'Sign'.

Pored izračunate potpise, zahtev takođe mora sadržati 'Api-Key' zaglavlje koje sadrži korišćen API ključ. Primer:

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

Možete potpisati zahtev poslat na AxtonPay bilo kojim važećim ključem koji pripada ovom plaćanju. Međutim, AxtonPay uvek koristi ključ koji ste odabrali u prodajnom panelu.

Primer izračunavanja potpisa:

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

Obratite pažnju na razmake i prekide linija u drugom 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 sastavljanja stringa za izračunavanje potpisa:

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

Parametri

API prihvata sve parametre i u QUERY_STRING i u telu POST zahteva.

Buleove promenljive

API očekuje da dobije '0' ili '1' u Boolean promenljivama, ali zbog implicitne konverzije tipova, bilo koji tekstualni string će biti tretiran kao '1', čak i reč 'false'. Dakle, da biste eksplicitno postavili vrednost 'FALSE' za Boolean promenljivu, potrebno je da joj prosledite ili vrednost '0' ili prazan string.

Decimalni separator

Samo se decimalna tačka koristi kao decimalni separator u brojevima.

Velika i mala slova u parametrima

Sa nekoliko izuzetaka, svi parametri razlikuju velika i mala slova.

URL za povratni poziv

U admin panelu AxtonPay, na stranici podešavanja naplate, moguće je podesiti URL adrese prodavnice za primanje obaveštenja server-server od AxtonPay, kao i URL adrese za preusmeravanje kupca nakon plaćanja fakture ili njenog otkazivanja, kao i u slučaju greške.

Ovi URL-ovi mogu biti prepisani u zahtevu za kreiranje fakture.

Metode AxtonPay API-ja

Kreiranje fakture: /api/v1/private/checkout/payment/create

Metod /api/v1/private/checkout/payment/create pokreće kreiranje fakture.

Ako je uspešno, metoda vraća link ('invoice_url') na koji treba da uputite kupca za plaćanje.

Parametri sopstvene fakture:

• time (obavezno) - POSIX timestamp (Unix time)
• amount (obavezno) - iznos koji treba platiti (cena proizvoda ili usluge koju prodavnica želi da primi)
• currency (obavezno) - 3-slova šifra valute prema ISO 4217-alpha, bez obzira na velika i mala slova
• pms (obavezno) - metode plaćanja prikazane na stranici računa. Ako želite da dozvolite sve metode plaćanja, vrednost je 'all'; ako želite da dozvolite samo neke od njih, navedite njihove numeričke identifikatore odvojene zarezom.
• pm - identifikator odabrane metode plaćanja. Važno je da ako se prosledi 'pm' parametar, faktura će biti kreirana u 'transparentnom režimu', tj. kupac neće videti stranicu fakture, već će ići direktno na platni sistem.
• extra_data - asocijativni niz koji sadrži sve dodatne podatke; ovi podaci se u celosti vraćaju u prodavnicu
• shop_user_id - identifikator korisnika u prodavnici, vraća se u prodavnicu u neizmenjenom obliku
• shop_payment_id - identifikator plaćanja u prodavnici, vraća se u prodavnicu u nepromenjenom obliku
• shop_name - ime prodavnice (prikazano na stranici računa)
• shop_payment_desc - opis porudžbine (prikazan na stranici računa)
• shop_payment_remark - vaše beleške o ovoj uplati (ovo je polje za bilo koje beleške koje imate o uplati, koje AxtonPay nigde ne prosleđuje; vidljive su samo u listi uplata; ne vraćaju se u prodavnicu)
• valid_time - vremenski interval u kojem se faktura može platiti; u sekundama
• view_time - vremenski interval tokom kojeg je faktura dostupna za pregled preko spoljnog linka; u sekundama; odbrojavanje počinje nakon što period 'valid_time' završi
• server_notification_method - metod slanja server-server obaveštenja o statusima plaćanja prodavnici; važeće vrednosti: POST, GET

Neka podešavanja za fakturu su postavljena na stranici podešavanja naplate. Ali vrednosti prosleđene u zahtevu će imati prednost nad tim podešavanjima.

Parametri plaćanja koje je moguće prebrisati za ovu fakturu:

• customer_success_url - link na koji će kupac biti preusmeren ako je faktura uspešno plaćena (tj. ako je status fakture 'paid' ili 'overpaid').
• customer_cancel_url - link na koji će kupac biti preusmeren ako je plaćanje otkazano
• customer_fail_url - link na koji će kupac biti preusmeren ako plaćanje završi greškom
• server_notification_url - link za slanje obaveštenja o statusu plaćanja sa servera na server prodavnici

Napomena: Da biste se pridržavali svoje politike privatnosti, obično nije potrebno uključivati lične podatke vašeg kupca u svojstva fakture. Na primer, u parametru "shop_user_id" bolje je navesti apstraktni ID kupca umesto njihovog e-maila ili broja telefona. Takođe, u "shop_payment_desc" je bolje uopšte ne uključivati podatke o kupcu, jer oni već sve znaju o sebi; umesto toga, možete napisati neke informacije o kupljenim proizvodima ili uslugama, ili čak samo napisati tip akcije, na primer, "Kupovina" ili "Dopuna stanja".

Sve reference se neophodno prenose sa protokolom.

Primer zahteva:

<?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šnog odgovora prilikom zahteva za izradu fakture:

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

Dobijanje informacija o fakturi: /api/v1/private/checkout/payment/get/{PID}

Da biste dobili potrebne informacije, pozovite metodu /api/v1/private/checkout/payment/get/{PID}, navodeći PID fakture na kraju URL-a.

Parametri zahteva:

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

Primer linije za sastavljanje potpisa:

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

Uporedba traženog iznosa i isplaćenog iznosa

Odgovor sadrži nekoliko različitih iznosa (u valuti u kojoj je faktura izdata):

• "amount" - fakturisani iznos
• "filled" - platio deo fakture,
• "total_filled" - koliko je klijent ukupno platio, uključujući provizije.

Ako "filled = amount", onda se plaća tačno koliko je potrebno.

Ako "filled > amount", postoji preplaćivanje.

Ako "filled < amount", faktura nije u potpunosti plaćena (nedoplatak).

Faktura: obrada obaveštenja od AxtonPay o promeni statusa

Svaki put kada se status fakture promeni, AxtonPay šalje obaveštenje server_notification_url (koristeći server_notification_method)

Primer podataka:

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

Kao odgovor na ovu obavest AxtonPay očekuje da primi HTTP code 200, što potvrđuje njeno uspešno primanje. U suprotnom, AxtonPay će pokušati još 12 puta u postepeno sve dužim intervalima, a zatim se status obaveštenja menja u 'error' (ali to ne utiče na status same fakture).

Moguće vrednosti statusa:

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

Statusi uspešne uplate su 1 (paid) i 5 (overpaid); u slučaju njihovog prijema možete preneti plaćenu kupovinu na kupca ili dopuniti saldo. Za uplate sa statusom 5 (overpaid), u slučaju dopune salda možete dopuniti saldo za iznos stvarno primljene uplate, ali u slučaju prodaje dobara/usluga i značajnog iznosa preplate preporučuje se da kontaktirate platioca i dogovorite se sa njim kako postupiti sa preplatom.

Delimično uspešan status je 4 (underpaid); u slučaju dobijanja ovog statusa moguće je dopuniti balans za iznos stvarno primljene uplate. Međutim, ovaj status se ne može smatrati uspešnim za prodaju robe/usluga.

Svi ostali statusi - 0 (pending), 2 (error), 3 (canceled by customer) označavaju potpuno odsustvo plaćanja; u slučaju njihovog prijema ne bi trebalo preduzimati nikakve radnje u vezi sa dopunom salda ili prodajom dobara/usluga.

Provera potpisa

Da biste bili sigurni da je obaveštenje poslato od strane AxtonPay-a, potrebno je da verifikujete potpis primljenog obaveštenja pre nego što mu verujete. Verifikacija je slična potpisivanju vaših sopstvenih zahteva, samo što se dodaje poslednji korak, kada treba da uporedite izračunati potpis sa primljenim HTTP header-om 'Sign'.

Glavni koraci nakon prijema obaveštenja o promenjenom statusu plaćanja su sledeći:

• uzmi celu niz argumenata (QUERY_STRING) iz primljene notifikacije,
• uzmi ceo POST data (REQUEST_BODY) iz primljene obavesti,
• izračunajte potpis koristeći te QUERY_STRING + REQUEST_BODY i odgovarajući 'Secret key',
• uporedi izračunati potpis sa onim koji je primljen u HTTP zaglavlju 'Sign',
• ako su potpisi isti, obaveštenje je zaista stiglo od AxtonPay;
• ako su potpisi različiti, to može biti pokušaj prevarе od strane platioca.

Primer linije za generisanje potpisa:

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

Potvrda da je prodavnica obradila informacije o plaćanju: /api/v1/private/checkout/payment/confirm/{PID}

Ovaj zahtev se šalje AxtonPay kao odgovor na obaveštenje primljeno od njega. Funkcionalno, to je potvrda da je prodavnica uspešno primila i obradila primljeno obaveštenje.

Da biste poslali zahtev, pozovite metodu /api/v1/private/checkout/payment/confirm/{PID}, navodeći pid fakture na kraju URL-a.

Parametri zahteva:

• time (obavezno) - POSIX timestamp (Unix time)
• status (obavezno, ceo broj) - broj statusa plaćanja za koji prodavnica šalje potvrdu

Ako preneti status odgovara trenutnom statusu ove fakture u sistemu, AxtonPay će odgovoriti sa 'OK', a ako se ne poklapa, odgovoriće sa greškom.

Primer linije za generisanje potpisa:

// 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 ako je trenutni status plaćanja isti:

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

Primer odgovora ako trenutni status plaćanja razlikuje od onog koji je poslat u zahtevu:

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

Kodovi valuta

Valute koje se mogu koristiti za kreiranje fakture.

Većina korišćenih kodova valuta pripada fiat valutama, i oni su jednaki ISO 4217. Lista takođe sadrži nekoliko kriptovaluta.