AxtonPay API

Informations communes

Point de terminaison de l'API

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

Content-type

L'API accepte les requêtes HTTP avec 2 types de contenu : 'application/x-www-form-urlencoded', 'application/json'.

L'en-tête HTTP doit correspondre au contenu du corps POST.

Abréviations et définitions

• {PID} - ID de la facture, généralement c'est la séquence alphanumérique unique de 8 caractères.
• Shop - Votre site web qui accepte les paiements via le service AxtonPay

Algorithme de travail avec l'API

Séquence habituelle des actions pour recevoir un paiement :

• créer une facture ('/api/v1/private/checkout/payment/create'), la réponse de l'API renverra l'URL de la facture ('invoice_url'),
• envoyer l'acheteur à cette facture afin de effectuer le paiement,
• attendez les notifications du serveur AxtonPay, qui arriveront vers 'server_notification_url',
• dès réception de toute notification de AxtonPay, vérifier la validité de sa signature et, de préférence, envoyer un accusé de réception à AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• si le statut d'une facture est modifié, exécutez les actions correspondant à ce statut (par exemple, demander toutes les informations sur la facture, expédier les marchandises, créer un ticket pour l'équipe de support, etc.).

Si vous définissez une 'server_notification_url' vide ou invalide lors de la création d'une facture, le service ne peut pas envoyer de notifications concernant les changements de statut ; dans ce cas, vous devriez vérifier vous-même la facture à intervalles réguliers ('/api/v1/private/checkout/payment/get/{PID}').

Autorisation des demandes

Pour autoriser une requête, il est nécessaire de calculer un Hash à partir d'une chaîne formée de manière spéciale. La chaîne est composée en concaténant (collant ensemble) les arguments de l'URL (QUERY_STRING) et le corps de la requête POST (REQUEST_BODY). Il est important que tous les composants soient pris exactement sous la forme dans laquelle ils seront transmis au serveur. Les arguments de l'URL (QUERY_STRING) doivent être pris depuis l'URL en une seule ligne, sans changer l'ordre des arguments et sans supprimer aucun élément. Le corps de la requête POST (REQUEST_BODY) doit également être utilisé sans aucune modification, y compris ne pas retirer les guillemets, les espaces, les crochets ou les sauts de ligne.

Dans les cas d'un corps de requête POST vide, et dans le cas d'arguments d'URL vides, ce composant sera simplement une chaîne vide.

La séquence des données dans la demande de signature : QUERY_STRING d'abord, puis les données POST. Vous ne devez pas insérer de signes de connexion entre elles, il suffit de concaténer les deux chaînes de texte.

Encore une fois, chaque symbole est significatif. Vous ne devez ajouter ni supprimer un espace ou un symbole de nouvelle ligne. Utilisez simplement les données brutes reçues par le serveur.

Un SHA-256 hachage avec la clé 'Secret key' est extrait de la chaîne résultante et utilisé comme deuxième argument de la fonction hash_hmac().

Il est obligatoire de passer le paramètre 'time' contenant le POSIX timestamp (Unix time) actuel.

Cette signature est valide pendant 24 heures. Si la valeur du paramètre 'time' diffère de l'heure actuelle du serveur de plus de 24 heures (en avance ou en retard), la requête échouera même si la signature est calculée sans erreurs.

Si le panneau marchand a accepté une demande avec une certaine signature, cette signature ne peut pas être utilisée à nouveau, même pour envoyer la demande avec les mêmes paramètres (cela inclut le paramètre 'time').

Le hachage résultant est transmis dans l'en-tête HTTP 'Sign'.

En plus de la signature calculée, la requête doit également contenir un en-tête 'Api-Key' contenant la clé API utilisée. Exemple :

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

Vous pouvez signer la demande envoyée au AxtonPay avec n'importe quelle clé valide qui appartient à ce point de vente. Cependant, le AxtonPay utilise toujours la clé que vous avez sélectionnée dans le panneau marchand.

Exemple de calcul de signature :

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

Faites attention aux espaces et aux sauts de ligne dans un autre 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"
}' 
*/

Le Python exemple de composition de la chaîne pour le calcul de la signature :

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

Paramètres

L'API accepte tous les paramètres à la fois dans QUERY_STRING et dans le corps de la demande POST.

Variables booléennes

L'API s'attend à recevoir '0' ou '1' dans des variables booléennes, mais à cause de la conversion implicite de type, toute chaîne de texte sera traitée comme un '1', même le mot 'false'. Ainsi, pour définir explicitement une valeur 'FALSE' pour une variable booléenne, vous devez lui passer soit la valeur '0' soit une chaîne vide.

Séparateur décimal

Seul le point décimal est utilisé comme séparateur décimal dans les nombres.

Casse des caractères dans les paramètres

À quelques exceptions près, tous les paramètres sont sensibles à la casse.

URL de rappel

Dans le panneau d'administration de AxtonPay, sur la page des paramètres de paiement, il est possible de définir des URL de magasin pour recevoir des notifications serveur à serveur de AxtonPay, ainsi que des URL pour rediriger l'acheteur après le paiement de la facture ou son annulation, ainsi qu'en cas d'erreur.

Ces URL peuvent être remplacées dans la demande de création de facture.

Méthodes de AxtonPay API

Création de facture : /api/v1/private/checkout/payment/create

La méthode /api/v1/private/checkout/payment/create lance la création de la facture.

Si elle réussit, la méthode renvoie un lien ('invoice_url') vers lequel vous devez diriger le client pour le paiement.

Paramètres de facture propres :

• time (requis) - POSIX timestamp (Unix time)
• amount (requis) - montant à payer (le prix du produit ou du service que le magasin souhaite recevoir)
• currency (requis) - Code de devise à 3 lettres selon ISO 4217-alpha, insensible à la casse
• pms (requis) - méthodes de paiement affichées sur la page de la facture. Si vous voulez autoriser toutes les méthodes de paiement, la valeur est 'all' ; si vous voulez n'autoriser que certaines d'entre elles, listez leurs identifiants numériques séparés par des virgules.
• pm - identifiant du mode de paiement sélectionné. Il est important que si le paramètre 'pm' est passé, la facture sera créée en 'mode transparent', c'est-à-dire que l'acheteur ne verra pas la page de facturation, mais ira directement vers le système de paiement.
• extra_data - un tableau associatif contenant toutes les données supplémentaires ; ces données sont renvoyées au magasin dans leur intégralité
• shop_user_id - identifiant utilisateur dans le magasin, il est renvoyé au magasin sous une forme inchangée
• shop_payment_id - identifiant de paiement dans le magasin, il est renvoyé au magasin sous forme inchangée
• shop_name - nom du magasin (affiché sur la page de facture)
• shop_payment_desc - description de la commande (affichée sur la page de la facture)
• shop_payment_remark - vos notes concernant ce paiement (il s'agit d'un champ pour toutes les notes que vous avez sur le paiement, que AxtonPay ne transmet nulle part ; elles ne sont visibles que dans la liste des paiements ; elles ne retournent pas au magasin)
• valid_time - l'intervalle de temps pendant lequel la facture peut être payée ; en secondes
• view_time - intervalle de temps pendant lequel la facture est disponible pour consultation via un lien externe ; en secondes ; le compte à rebours commence après la fin de la période 'valid_time'
• server_notification_method - méthode d'envoi de notifications serveur-serveur concernant les statuts de paiement au magasin ; valeurs valides : POST, GET

Certaines options pour la facture sont définies sur la page des paramètres de paiement. Mais les valeurs transmises dans la requête auront la priorité sur ces paramètres.

Paramètres de paiement pouvant être remplacés pour cette facture :

• customer_success_url - un lien vers lequel l'acheteur sera redirigé si la facture est payée avec succès (c'est-à-dire si le statut de la facture est 'paid' ou 'overpaid').
• customer_cancel_url - un lien vers lequel l'acheteur sera redirigé si le paiement est annulé
• customer_fail_url - un lien vers lequel l'acheteur sera redirigé si le paiement se termine par une erreur
• server_notification_url - lien pour envoyer des notifications serveur-à-serveur des statuts de paiement au magasin

Remarque : Afin de se conformer à votre propre politique de confidentialité, il n'est généralement pas nécessaire d'inclure les données personnelles de votre client dans les propriétés de la facture. Par exemple, dans le paramètre "shop_user_id", il est préférable de spécifier un identifiant client abstrait plutôt que son e-mail ou son numéro de téléphone. De même, dans le "shop_payment_desc", il vaut mieux ne pas inclure du tout de données sur le client, car il connaît déjà tout sur lui-même ; à la place, vous pouvez écrire certaines informations sur les biens ou services payés, ou même simplement indiquer le type d'action, par exemple, " Achat " ou " Recharge de solde ".

Toutes les références sont nécessairement transmises avec le protocole.

Exemple de demande :

<?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'une réponse réussie lors de la demande de création d'une facture :

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

Obtention des informations de facture : /api/v1/private/checkout/payment/get/{PID}

Pour obtenir les informations dont vous avez besoin, appelez la méthode /api/v1/private/checkout/payment/get/{PID}, en spécifiant le PID de la facture à la fin de l'URL.

Paramètres de la requête :

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

Exemple d'une ligne pour composer une signature :

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

// String for signature calculation: 
time=1766837343

Exemple de réponse :

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

Comparaison du montant demandé et du montant payé

La réponse contient plusieurs montants différents (dans la monnaie dans laquelle la facture a été émise) :

• "amount" - montant facturé
• "filled" - payé une partie de la facture,
• "total_filled" - combien le client a payé au total, y compris les commissions.

Si "filled = amount", alors c'est payé exactement autant qu'il le faut.

S'il y a un "filled > amount", il y a un trop-perçu.

Si "filled < amount", la facture n'a pas été entièrement payée (sous-paiement).

Facture : traitement de la notification de AxtonPay concernant le changement de statut

Chaque fois que le statut d'une facture est modifié, AxtonPay envoie une notification à server_notification_url (en utilisant le server_notification_method)

Exemple de données :

{
    "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 réponse à cette notification, AxtonPay s'attend à recevoir HTTP code 200, ce qui confirme sa réception réussie. Sinon, AxtonPay réessaiera 12 fois de plus à des intervalles de plus en plus longs, puis le statut de la notification passe à 'error' (mais cela n'affecte pas le statut de la facture elle-même).

Valeurs de statut possibles :

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

Les statuts de paiement réussis sont 1 (paid) et 5 (overpaid) ; en cas de réception de ceux-ci, vous pouvez transférer l'achat payé au client ou reconstituer le solde. Pour les paiements avec le statut 5 (overpaid), en cas de reconstitution du solde, vous pouvez reconstituer le solde du montant effectivement reçu, mais en cas de vente de biens/services et d'un montant important de trop-perçu, il est conseillé de contacter le payeur et de décider avec lui comment traiter le trop-perçu.

Le statut partiellement réussi est 4 (underpaid) ; en cas de réception de ce statut, il est possible de recharger le solde du montant du paiement effectivement reçu. Cependant, ce statut ne peut pas être considéré comme réussi pour la vente de biens/services.

Tous les autres statuts - 0 (pending), 2 (error), 3 (canceled by customer) signifient une absence totale de paiement ; en cas de leur réception, aucune action concernant le réapprovisionnement du solde ou la vente de biens/services ne doit être effectuée.

Vérification de la signature

Pour être sûr que la notification est envoyée par AxtonPay exactement, il est nécessaire de vérifier la signature de la notification reçue avant de lui faire confiance. La vérification est similaire à la signature de vos propres requêtes, seule la dernière étape est ajoutée, lorsque vous devez comparer la signature calculée avec l'en-tête HTTP reçu 'Sign'.

Les étapes principales après avoir reçu une notification concernant le changement de statut de paiement sont les suivantes :

• prendre toute la chaîne d'arguments (QUERY_STRING) de la notification reçue,
• prendre tout le POST data (REQUEST_BODY) de la notification reçue,
• calculez la signature en utilisant ces QUERY_STRING + REQUEST_BODY et le 'Secret key' approprié,
• comparez la signature calculée avec celle qui est reçue dans l'en-tête HTTP 'Sign',
• si les signatures sont les mêmes, la notification vient vraiment de AxtonPay;
• si les signatures sont différentes, cela peut être une tentative de tricherie de la part du payeur.

Exemple d'une ligne pour la génération de signature :

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

Confirmation que le magasin a traité les informations de paiement : /api/v1/private/checkout/payment/confirm/{PID}

Cette requête est envoyée à AxtonPay en réponse à une notification reçue de celui-ci. Fonctionnellement, c'est une confirmation que le magasin a reçu et traité avec succès la notification reçue.

Pour envoyer une requête, appelez la méthode /api/v1/private/checkout/payment/confirm/{PID}, en spécifiant le pid de la facture à la fin de l'URL.

Paramètres de la requête :

• time (requis) - POSIX timestamp (Unix time)
• status (obligatoire, entier) - numéro de statut de paiement pour lequel le magasin envoie une confirmation

Si le statut transmis correspond au statut actuel de cette facture dans le système, AxtonPay répondra par 'OK' et s'il ne correspond pas, il répondra par une erreur.

Exemple d'une ligne pour la génération de signature :

// 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 de réponse si le statut de paiement actuel est le même :

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

Exemple de réponse si le statut de paiement actuel diffère de celui transmis dans la requête :

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

Codes monétaires

Les devises qui peuvent être utilisées pour la création d'une facture.

La plupart des codes de monnaie utilisés appartiennent aux monnaies fiduciaires, et ils sont égaux au ISO 4217. La liste contient également plusieurs crypto-monnaies.