AxtonPay API

Informació comuna

punt final de l'API

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

Content-type

L'API accepta HTTP sol·licituds amb 2 tipus de contingut: 'application/x-www-form-urlencoded', 'application/json'.

L'encapçalament HTTP hauria d'ajustar-se al contingut del cos POST.

Abreviatures i definicions

• {PID} - ID de la factura, normalment és la seqüència alfanumèrica única de 8 caràcters.
• Shop - El teu lloc web que accepta pagaments a través del servei AxtonPay

Algorisme de treball amb l'API

Seqüència habitual d’accions per rebre el pagament:

• crear una factura ('/api/v1/private/checkout/payment/create'), la resposta de l'API retornarà l'URL de la factura ('invoice_url'),
• envieu el comprador a aquesta factura per tal de fer el pagament,
• espera les notificacions del servidor AxtonPay, que arribaran a 'server_notification_url',
• en rebre qualsevol notificació de AxtonPay, comprovar la validesa de la seva signatura i, preferiblement, enviar una confirmació de recepció a AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• si es modifica l'estat d'una factura, realitzeu les accions corresponents a aquest estat (per exemple, sol·licitar informació completa sobre la factura, enviar els béns, crear un tiquet per a l'equip de suport, etc.).

Si configureu un 'server_notification_url' buit o invàlid en crear una factura, el servei no podrà enviar notificacions sobre els canvis d'estat; en aquests casos, heu de comprovar la factura vosaltres mateixos de tant en tant ('/api/v1/private/checkout/payment/get/{PID}').

Autorització de sol·licituds

Per autoritzar una sol·licitud és necessari calcular un Hash a partir d'una cadena formada d'una manera especial. La cadena es compon unint (enganxant) els arguments de la URL (QUERY_STRING) i el cos de la sol·licitud POST (REQUEST_BODY). És important que tots els components s'agafin exactament en la forma en què seran transmesos al servidor. Els arguments de la URL (QUERY_STRING) s'han d'agafar des de la URL com una sola línia, sense canviar l'ordre dels arguments i sense eliminar cap element. El cos de la sol·licitud POST (REQUEST_BODY) també s'ha d'utilitzar sense cap modificació, inclòs no eliminar-ne cometes, espais, parèntesis o salts de línia.

En els casos d'un cos de sol·licitud POST buit, i en el cas d'arguments d'URL buits, aquell component simplement serà una cadena buida.

La seqüència de dades a la sol·licitud de signatura: QUERY_STRING primer, després les dades POST. No heu d'inserir cap signe de connexió entre elles, només concateneu les dues cadenes de text.

Un cop més, cada símbol és significatiu. No hauríeu d'afegir ni treure ni un espai en blanc ni cap símbol de línia nova. Només utilitzeu les dades en brut rebudes pel servidor.

Un SHA-256 hash amb la clau 'Secret key' es pren de la cadena resultant i s'utilitza com a segon argument de la funció hash_hmac().

És obligatori passar el paràmetre 'time' que conté el POSIX timestamp (Unix time) actual.

Aquesta signatura és vàlida durant 24 hores. Si el valor del paràmetre 'time' difereix del temps actual del servidor en més de 24 hores (ja sigui endavant o enrere), la sol·licitud fallarà encara que la signatura s'hagi calculat sense errors.

Si el panell del comerciant ha acceptat una sol·licitud amb alguna signatura, aquesta signatura no es pot utilitzar de nou, ni tan sols per enviar la sol·licitud amb els mateixos paràmetres (això inclou el paràmetre 'time').

El hash resultant es passa a la capçalera HTTP 'Sign'.

A més de la signatura calculada, la sol·licitud també ha de contenir un encapçalament 'Api-Key' amb la clau API utilitzada. Exemple:

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

Pots signar la sol·licitud enviada al AxtonPay amb qualsevol clau vàlida que pertanyi a aquest procés de compra. Tanmateix, el AxtonPay sempre utilitza la clau que has seleccionat al panell del comerciant.

Exemple de càlcul de signatura:

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

Presta atenció als espais en blanc i als salts de línia en un altre exemple:

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

L'exemple Python de compondre la cadena per al càlcul de la signatura:

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

Paràmetres

L'API accepta tots els paràmetres tant en QUERY_STRING com en el cos de la sol·licitud POST.

Variables booleànes

L'API espera rebre '0' o '1' en variables booleans, però a causa de la conversió de tipus implícita, qualsevol cadena de text es tractarà com a '1', fins i tot la paraula 'false'. Així, per establir explícitament un valor 'FALS' per a una variable booleana, cal passar-li ja sigui el valor '0' o una cadena buida.

Separador decimal

Només el punt decimal s'utilitza com a separador decimal en els nombres.

Majúscules i minúscules en els paràmetres

Amb poques excepcions, tots els paràmetres són sensibles a majúscules i minúscules.

URL de retorn de trucada

A l'panell d'administració de AxtonPay, a la pàgina de configuració del procés de pagament, és possible establir URL de la botiga per rebre notificacions servidor a servidor de AxtonPay, així com URL per redirigir el comprador després del pagament de la factura o la seva cancel·lació, així com en cas d'un error.

Aquests URL es poden substituir en la sol·licitud de creació de la factura.

Mètodes de AxtonPay API

Creació de factura: /api/v1/private/checkout/payment/create

El mètode /api/v1/private/checkout/payment/create inicia la creació de la factura.

Si té èxit, el mètode retorna un enllaç ('invoice_url') al qual heu d’enviar el client per al pagament.

Paràmetres de la pròpia factura:

• time (obligatori) - POSIX timestamp (Unix time)
• amount (obligatori) - import a pagar (el preu del producte o servei que la botiga vol rebre)
• currency (obligatori) - Codi de moneda de 3 lletres segons ISO 4217-alpha, sense distingir majúscules de minúscules
• pms (obligatori) - mètodes de pagament mostrats a la pàgina de la factura. Si voleu permetre tots els mètodes de pagament, el valor és 'all'; si voleu permetre només alguns d’ells, indiqueu els seus identificadors numèrics separats per comes.
• pm - identificador del mètode de pagament seleccionat. És important que si es passa el paràmetre 'pm', la factura es crearà en 'mode transparent', és a dir, el comprador no veurà la pàgina de la factura, sinó que anirà directament al sistema de pagament.
• extra_data - un array associatiu que conté qualsevol dada addicional; aquestes dades es retornen a l'emmagatzematge en la seva totalitat
• shop_user_id - identificador d'usuari a la botiga, es retorna a la botiga sense canvis
• shop_payment_id - identificador de pagament a la botiga, es retorna a la botiga en forma inalterada
• shop_name - nom de la botiga (mostrat a la pàgina de la factura)
• shop_payment_desc - descripció de la comanda (mostrada a la pàgina de la factura)
• shop_payment_remark - les teves notes sobre aquest pagament (aquest és un camp per a qualsevol nota que tinguis sobre el pagament, que AxtonPay no transmet a enlloc; només és visible a la llista de pagaments; no torna a la botiga)
• valid_time - l'interval de temps en què es pot pagar la factura; en segons
• view_time - interval de temps durant el qual la factura està disponible per a visualització mitjançant enllaç extern; en segons; el compte enrere comença després que finalitzi el període 'valid_time'
• server_notification_method - mètode d'enviament de notificacions servidor-servidor sobre els estats de pagament a la botiga; valors vàlids: POST, GET

Algunes configuracions de la factura s'estableixen a la pàgina de configuració de la caixa. Però els valors passats en la sol·licitud tindran prioritat sobre aquestes configuracions.

Paràmetres de pagament que es poden sobreescriure per a aquesta factura:

• customer_success_url - un enllaç al qual el comprador serà redirigit si la factura es paga amb èxit (és a dir, si l’estat de la factura és 'paid' o 'overpaid').
• customer_cancel_url - un enllaç al qual el comprador serà redirigit si el pagament es cancel·la
• customer_fail_url - un enllaç al qual el comprador serà redirigit si el pagament acaba en un error
• server_notification_url - enllaç per enviar notificacions de servidor a servidor de l'estat dels pagaments a la botiga

Nota: Per complir amb la seva pròpia política de privacitat, normalment no és necessari incloure les dades personals del vostre client a les propietats de la factura. Per exemple, en el paràmetre "shop_user_id", és millor especificar un ID de client abstracte en lloc del seu correu electrònic o número de telèfon. També en el "shop_payment_desc", és millor no incloure cap dada del client, ja que ells ja saben tot sobre si mateixos; en canvi, podeu escriure alguna informació sobre els béns o serveis pagats, o fins i tot només escriure el tipus d'acció, per exemple, "Compra" o "Recarrega de saldo".

Totes les referències es transmeten necessàriament amb el protocol.

Exemple de sol·licitud:

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

Exemple d'una resposta exitosa quan es sol·licita la creació d'una factura:

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

Obtenció d'informació de la factura: /api/v1/private/checkout/payment/get/{PID}

Per obtenir la informació que necessiteu, truqueu al mètode /api/v1/private/checkout/payment/get/{PID}, especificant el PID de la factura al final de la URL.

Paràmetres de la sol·licitud:

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

Exemple d'una línia per a compondre una signatura:

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

// String for signature calculation: 
time=1766837343

Exemple d'una resposta:

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

Comparació de l'import sol·licitat i l'import pagat

La resposta conté diverses quantitats diferents (en la moneda en què s’ha emès la factura):

• "amount" - quantitat facturada,
• "filled" - va pagar part de la factura,
• "total_filled" - quant va pagar el client en total, incloses les comissions.

Si "filled = amount", llavors es paga exactament tant com cal.

Si "filled > amount", hi ha un pagament en excés.

Si "filled < amount", la factura no ha estat pagada en la seva totalitat (pagament insuficient).

Factura: processament de la notificació de AxtonPay sobre el canvi d'estat

Cada vegada que es canvia l'estat d'una factura, AxtonPay envia una notificació a server_notification_url (utilitzant el server_notification_method)

Dades d'exemple:

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

En resposta a aquesta notificació AxtonPay espera rebre HTTP code 200, que confirma la seva recepció exitosa. En cas contrari, AxtonPay intentarà de nou 12 vegades més amb intervals progressivament creixents, i després l'estat de la notificació canvia a 'error' (però això no afecta l'estat de la factura en si).

Valors d'estat possibles:

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

Els estats de pagament reeixits són 1 (paid) i 5 (overpaid); en cas de rebre'ls, podeu transferir la compra pagada al client o reomplir el saldo. Per als pagaments amb estat 5 (overpaid), en cas de reompliment del saldo, podeu reomplir el saldo per l'import del pagament realment rebut, però en cas de venda de béns/serveis i un import significatiu de pagament en excés és recomanable contactar amb el pagador i decidir amb ell com gestionar el pagament en excés.

L'estat parcialment exitós és 4 (underpaid); en cas de rebre aquest estat, és possible recarregar el saldo per l'import del pagament efectivament rebut. Tanmateix, aquest estat no es pot considerar exitós per a la venda de béns/serveis.

Tots els altres estats - 0 (pending), 2 (error), 3 (canceled by customer) signifiquen absència total de pagament; en cas de rebre'ls no s'haurien de realitzar accions per a la reposició de saldo o la venda de béns/serveis.

Comprovació de la signatura

Per assegurar-se que la notificació és enviada per AxtonPay exactament, és necessari verificar la signatura de la notificació rebuda abans de confiar-hi. La verificació és similar a signar les teves pròpies sol·licituds, només que s’afegeix l’últim pas, quan hauries de comparar la signatura calculada amb la capçalera HTTP rebuda 'Sign'.

Els passos principals després de rebre la notificació sobre el canvi d'estat del pagament són els següents:

• agafa tota la cadena d'arguments (QUERY_STRING) de la notificació rebuda,
• agafa tot el POST data (REQUEST_BODY) de la notificació rebuda,
• calculeu la signatura utilitzant aquests QUERY_STRING + REQUEST_BODY i el 'Secret key' adequat,
• comparar la signatura calculada amb la que es rep a la capçalera HTTP 'Sign',
• si les signatures són les mateixes, la notificació realment va venir de AxtonPay;
• si les signatures són diferents, podria ser un intent d'enganyar per part del pagador.

Exemple d'una línia per a la generació de signatura:

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

Confirmació que la botiga ha processat la informació de pagament: /api/v1/private/checkout/payment/confirm/{PID}

Aquesta sol·licitud s'envia a AxtonPay en resposta a una notificació rebuda d'ella. Funcionalment, és una confirmació que la botiga ha rebut i processat correctament la notificació rebuda.

Per enviar una sol·licitud, truqueu al mètode /api/v1/private/checkout/payment/confirm/{PID}, especificant el pid de la factura al final de l'URL.

Paràmetres de la sol·licitud:

• time (obligatori) - POSIX timestamp (Unix time)
• status (obligatori, enter) - número d’estat de pagament pel qual la botiga envia la confirmació

Si l'estat transmès coincideix amb l'estat actual d'aquesta factura al sistema, AxtonPay respondrà amb 'OK' i si no coincideix, respondrà amb un error.

Exemple d'una línia per a la generació de signatura:

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

Exemple d'una resposta si l'estat actual del pagament és el mateix:

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

Exemple d'una resposta si l'estat actual del pagament difereix del que es va transmetre en la sol·licitud:

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

Codis de moneda

Les monedes que es poden utilitzar per a la creació d'una factura.

La majoria dels codis de moneda utilitzats pertanyen a monedes fiduciàries, i són iguals a les ISO 4217. També la llista conté diverses criptomonedes.