AxtonPay API

Informații comune

Punct final API

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

Content-type

API acceptă HTTP cereri cu 2 tipuri de conținut: 'application/x-www-form-urlencoded', 'application/json'.

Antetul HTTP ar trebui să se potrivească cu conținutul corpului POST.

Abrevieri și definiții

• {PID} - ID-ul facturii, de obicei este secvența alfanumerică unică de 8 caractere.
• Shop - Site-ul dvs. care acceptă plăți prin serviciul AxtonPay

Algoritmul de lucru cu API

Secvența obișnuită de acțiuni pentru a primi plata:

• creează o factură ('/api/v1/private/checkout/payment/create'), răspunsul API va returna URL-ul facturii ('invoice_url'),
• trimiteți cumpărătorul la această factură pentru a efectua plata,
• așteaptă notificările serverului AxtonPay, care vor veni la 'server_notification_url',
• la primirea oricărui notificări de la AxtonPay, verificați validitatea semnăturii sale și, de preferință, trimiteți o confirmare de primire către AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• dacă starea unei facturi se schimbă, efectuați acțiuni corespunzătoare acestei stări (de exemplu, solicitați informații complete despre factură, expediați bunurile, creați un tichet pentru echipa de suport etc.).

Dacă setați un 'server_notification_url' gol sau invalid atunci când creați o factură, serviciul nu poate trimite notificări despre schimbările de stare; în astfel de cazuri, ar trebui să verificați factura singur la anumite intervale ('/api/v1/private/checkout/payment/get/{PID}').

Autorizarea cererilor

Pentru a autoriza o cerere, este necesar să se calculeze un Hash dintr-un șir format într-un mod special. Șirul este compus prin concatenarea (lipirea împreună) a argumentelor URL (QUERY_STRING) și a corpului cererii POST (REQUEST_BODY). Este important ca toate componentele să fie preluate exact în forma în care vor fi transmise către server. Argumentele URL (QUERY_STRING) trebuie preluate din URL ca un singur rând, fără a schimba ordinea argumentelor și fără a elimina elemente. Corpul cererii POST (REQUEST_BODY) trebuie, de asemenea, utilizat fără nicio modificare, inclusiv fără a elimina din acesta ghilimele, spații, paranteze sau întreruperi de linie.

În cazurile unui corp de cerere POST gol și în cazul unor argumente URL goale, componenta respectivă va fi pur și simplu un șir gol.

Secvența de date din cererea de semnare: QUERY_STRING mai întâi, apoi datele POST. Nu ar trebui să inserezi niciun semn de legătură între ele, doar concatenează cele două șiruri de text.

O dată în plus, fiecare simbol este semnificativ. Nu ar trebui să adăugați sau să eliminați nici măcar un spațiu sau un simbol de linie nouă. Folosiți doar datele brute primite de la server.

Un SHA-256 hash cu cheia 'Secret key' este preluat din șirul rezultat și folosit ca al doilea argument al funcției hash_hmac().

Este obligatoriu să transmiteți parametrul 'time' care conține POSIX timestamp (Unix time) curent.

Această semnătură este valabilă timp de 24 de ore. Dacă valoarea parametrului 'time' diferă de timpul serverului actual cu mai mult de 24 de ore (fie înainte, fie înapoi), cererea va eșua chiar dacă semnătura a fost calculată fără erori.

Dacă panoul comerciantului a acceptat o cerere cu un anumit semnătură, acea semnătură nu poate fi folosită din nou, nici măcar pentru a trimite cererea cu aceiași parametri (aceasta include parametrul 'time').

Hash-ul rezultat este trecut în antetul HTTP 'Sign'.

În plus față de semnătura calculată, cererea trebuie să conțină și un antet 'Api-Key' care să includă cheia API utilizată. Exemplu:

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

Puteți semna cererea trimisă către AxtonPay cu orice cheie validă care aparține acestui checkout. Cu toate acestea, AxtonPay folosește întotdeauna cheia pe care ați selectat-o în panoul comerciantului.

Exemplu de calcul al semnăturii:

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

Acordă atenție spațiilor albe și întreruperilor de linie în alt exemplu:

/* 
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 exemplul de compunere a șirului pentru calculul semnăturii:

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

Parametri

API-ul acceptă toți parametrii atât în QUERY_STRING, cât și în corpul cererii POST.

Variabile booleene

API-ul se așteaptă să primească '0' sau '1' în variabile Boolean, dar din cauza conversiei implicite de tip, orice șir de text va fi tratat ca un '1', chiar și cuvântul 'false'. Prin urmare, pentru a seta explicit o valoare 'FALSE' pentru o variabilă Boolean, trebuie să îi treci fie valoarea '0', fie un șir gol.

Separator zecimal

Doar punctul zecimal este folosit ca separator zecimal în numere.

Cazul caracterelor în parametri

Cu câteva excepții, toți parametrii fac diferență între majuscule și minuscule.

URL de apel invers

În panoul de administrare al AxtonPay, pe pagina de setări pentru checkout, este posibil să se seteze URL-uri ale magazinului pentru a primi notificări server-server de la AxtonPay, precum și URL-uri pentru redirecționarea cumpărătorului după plata facturii sau anularea acesteia, precum și în caz de eroare.

Aceste URL-uri pot fi suprascrise în cererea de creare a facturii.

Metode ale AxtonPay API

Crearea facturii: /api/v1/private/checkout/payment/create

Metoda /api/v1/private/checkout/payment/create inițiază crearea facturii.

Dacă are succes, metoda returnează un link ('invoice_url') către care ar trebui să direcționați clientul pentru plată.

Parametrii facturii proprii:

• time (obligatoriu) - POSIX timestamp (Unix time)
• amount (obligatoriu) - suma de plată (prețul produsului sau serviciului pe care magazinul dorește să îl primească)
• currency (obligatoriu) - Cod de valută format din 3 litere conform ISO 4217-alpha, fără a ține cont de majuscule/minuscule
• pms (obligatoriu) - metodele de plată afișate pe pagina facturii. Dacă doriți să permiteți toate metodele de plată, valoarea este 'all'; dacă doriți să permiteți doar unele dintre ele, listați identificatorii lor numerici separați prin virgulă.
• pm - identificatorul metodei de plată selectate. Este important ca, dacă parametrul 'pm' este transmis, factura va fi creată în modul 'transparent', adică cumpărătorul nu va vedea pagina facturii, ci va merge direct la sistemul de plată.
• extra_data - un tablou asociativ care conține orice date suplimentare; aceste date sunt returnate magazinului în întregime
• shop_user_id - identificatorul utilizatorului din magazin, este returnat magazinului în forma neschimbată
• shop_payment_id - identificator de plată în magazin, este returnat magazinului în forma neschimbată
• shop_name - numele magazinului (afișat pe pagina facturii)
• shop_payment_desc - descrierea comenzii (afișată pe pagina facturii)
• shop_payment_remark - notele tale despre această plată (acesta este un câmp pentru orice note ai despre plată, pe care AxtonPay nu le transmite nicăieri; ele sunt vizibile doar în lista plăților; nu se întorc la magazin)
• valid_time - intervalul de timp în care factura poate fi plătită; în secunde
• view_time - interval de timp în care factura este disponibilă pentru vizualizare prin link extern; în secunde; numărătoarea inversă începe după ce perioada 'valid_time' se încheie
• server_notification_method - metodă de trimitere a notificărilor server-server despre statusurile plăților către magazin; valori valide: POST, GET

Unele setări pentru factură sunt stabilite pe pagina de setări a checkout-ului. Dar valorile transmise în cerere vor avea prioritate față de aceste setări.

Parametrii de checkout care pot fi suprascrişi pentru această factură:

• customer_success_url - un link către care cumpărătorul va fi redirecționat dacă factura este plătită cu succes (adică dacă starea facturii este 'paid' sau 'overpaid').
• customer_cancel_url - un link către care cumpărătorul va fi redirecționat dacă plata este anulată
• customer_fail_url - un link către care va fi redirecționat cumpărătorul dacă plata se încheie cu o eroare
• server_notification_url - link pentru trimiterea notificărilor de plată de la server la server către magazin

Notă: Pentru a respecta propria politică de confidențialitate, de obicei nu este necesar să includeți datele personale ale clientului în proprietățile facturii. De exemplu, în parametrul "shop_user_id", este mai bine să specificați un ID abstract al clientului decât adresa lor de email sau numărul de telefon. De asemenea, în "shop_payment_desc", este mai bine să nu includeți deloc date despre client, deoarece ei deja știu totul despre ei înșiși; în schimb, puteți scrie unele informații despre bunurile sau serviciile plătite, sau chiar doar să scrieți tipul de acțiune, de exemplu, „Cumpărare” sau „Încărcare sold”.

Toate referințele sunt transmise neapărat împreună cu protocolul.

Exemplu de cerere:

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

Exemplu de răspuns de succes atunci când se solicită crearea unei facturi:

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

Obținerea informațiilor despre factură: /api/v1/private/checkout/payment/get/{PID}

Pentru a obține informațiile de care aveți nevoie, apelați metoda /api/v1/private/checkout/payment/get/{PID}, specificând PID facturii la sfârșitul URL-ului.

Parametrii cererii:

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

Exemplu de linie pentru compunerea unei semnături:

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

// String for signature calculation: 
time=1766837343

Exemplu de răspuns:

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

Compararea sumei solicitate cu suma plătită

Răspunsul conține mai multe sume diferite (în moneda în care a fost emisă factura):

• "amount" - sumă facturată,
• "filled" - plătit o parte din factură,
• "total_filled" - cât a plătit clientul în total, inclusiv comisioanele.

Dacă "filled = amount", atunci este plătit exact cât trebuie să fie.

Dacă "filled > amount", există o plată în exces.

Dacă "filled < amount", factura nu a fost plătită integral (subplată).

Factură: procesarea notificării de la AxtonPay despre schimbarea stării

De fiecare dată când statusul unei facturi se schimbă, AxtonPay trimite o notificare către server_notification_url (folosind server_notification_method)

Date exemplu:

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

Ca răspuns la această notificare, AxtonPay se așteaptă să primească HTTP code 200, care confirmă primirea sa cu succes. În caz contrar, AxtonPay va încerca din nou de 12 ori la intervale crescătoare progresiv, iar apoi starea notificării se schimbă în 'error' (dar acest lucru nu afectează starea facturii în sine).

Valori posibile pentru stare:

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

Stările de plată reușită sunt 1 (paid) și 5 (overpaid); în caz de primire a acestora, poți transfera achiziția plătită către client sau poți reîncărca soldul. Pentru plățile cu statutul 5 (overpaid), în caz de reîncărcare a soldului, poți reîncărca soldul cu suma plății efectiv primite, dar în caz de vânzare de bunuri/servicii și o sumă semnificativă de plată în exces, este recomandat să contactezi plătitorul și să decizi împreună cu el cum să gestionezi plata în exces.

Starea parțial reușită este 4 (underpaid); în cazul primirii acestei stări este posibil să reîncărcați soldul cu suma plății efectiv primite. Totuși, această stare nu poate fi considerată reușită pentru vânzarea de bunuri/servicii.

Toate celelalte stări - 0 (pending), 2 (error), 3 (canceled by customer) înseamnă absența completă a plății; în caz de primire a acestora, nu trebuie efectuate acțiuni de realimentare a soldului sau de vânzare a bunurilor/serviciilor.

Verificarea semnăturii

Pentru a fi sigur că notificarea este trimisă exact de AxtonPay, este necesar să verificați semnătura notificării primite înainte de a avea încredere în ea. Verificarea este similară cu semnarea propriilor solicitări, doar că se adaugă ultimul pas, când trebuie să comparați semnătura calculată cu antetul HTTP primit 'Sign'.

Principalele etape după primirea notificării cu privire la schimbarea stării plății sunt următoarele:

• ia întreaga serie de argumente (QUERY_STRING) din notificarea primită,
• ia întregul POST data (REQUEST_BODY) din notificarea primită,
• calculează semnătura folosind acele QUERY_STRING + REQUEST_BODY și 'Secret key' corespunzător,
• compară semnătura calculată cu cea primită în antetul HTTP 'Sign',
• dacă semnăturile sunt la fel, notificarea a venit cu adevărat de la AxtonPay;
• dacă semnăturile sunt diferite, poate fi o încercare de a trișa din partea plătitorului.

Exemplu de linie pentru generarea semnăturii:

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

Confirmarea că magazinul a procesat informațiile de plată: /api/v1/private/checkout/payment/confirm/{PID}

Această cerere este trimisă către AxtonPay ca răspuns la o notificare primită de la acesta. Funcțional, este o confirmare că magazinul a primit și a procesat cu succes notificarea primită.

Pentru a trimite o cerere, apelează metoda /api/v1/private/checkout/payment/confirm/{PID}, specificând pid-ul facturii la sfârșitul URL-ului.

Parametrii cererii:

• time (obligatoriu) - POSIX timestamp (Unix time)
• status (obligatoriu, întreg) - numărul stării de plată pentru care magazinul trimite confirmare

Dacă statusul transmis corespunde cu statusul curent al acestei facturi în sistem, AxtonPay va răspunde cu 'OK' și dacă nu corespunde, va răspunde cu o eroare.

Exemplu de linie pentru generarea semnăturii:

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

Exemplu de răspuns dacă starea actuală a plății este aceeași:

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

Exemplu de răspuns dacă starea actuală a plății diferă de cea transmisă în cerere:

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

Coduri valutare

Valutele care pot fi folosite pentru crearea unei facturi.

Majoritatea codurilor valutare folosite aparțin monedelor fiat și sunt egale cu ISO 4217. De asemenea, lista conține câteva criptomonede.