AxtonPay API

Common information

API endpoint

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

Content-type

API accepts HTTP requests with 2 content types: 'application/x-www-form-urlencoded', 'application/json'.

The HTTP header should fit the content of POST body.

Abbreviations and definitions

• {PID} - ID of the invoice, usually it's the unique 8-character alphanumeric sequence.
• Shop - Your website that accepts payments through the AxtonPay service

Algorithm of work with API

Usual sequence of actions to receive payment:

• create an invoice ('/api/v1/private/checkout/payment/create'), the API response will return the invoice URL ('invoice_url'),
• send the buyer to this invoice in order to make payment,
• wait for AxtonPay server notifications, that will be coming to 'server_notification_url',
• upon receipt of any notification from AxtonPay, check the validity of its signature and preferably send a confirmation of receipt to AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• if the status of an invoice is changed, perform actions corresponding to this status (e.g., request full information about the invoice, ship the goods, create a ticket to the support team, etc.).

If you set an empty or invalid 'server_notification_url' when creating an invoice, the service is unable to send notifications about status changes; in such cases, you should check the invoice yourself at some interval ('/api/v1/private/checkout/payment/get/{PID}').

Authorization of requests

To authorize a request it is necessary to calculate a Hash from a string formed in a special way. The string is composed by concatenating (gluing together) the URL arguments (QUERY_STRING) and the body of the POST request (REQUEST_BODY). It is important that all components should be taken exactly in the form in which they will be transmitted to the server. The URL arguments (QUERY_STRING) should be taken from the URL as a single line, without changing the order of arguments and without dropping any elements. POST request body (REQUEST_BODY) should also be used without any modifications, including do not remove from it quotes, spaces, brackets, line breaks.

In the cases of an empty POST request body, and in the case of an empty URL arguments, that component will simply be empty string.

The sequence of data in the signing request: QUERY_STRING first, then the POST data. You should not insert any connecting signs between them, just concatenate two text strings.

Once again, every symbol is significant. You should not add or remove even a whitespace or symbol of new line. Just use the raw data received by server.

A SHA-256 hash with the key 'Secret key' is taken from the resulting string and used as the second argument of function hash_hmac().

It is mandatory to pass the 'time' parameter containing the current POSIX timestamp (Unix time).

This signature is valid for 24 hours. If the value of 'time' parameter differs from the current server time by more than the 24 hours (whether forward or backward), the request will fail even if the signature is calculated without errors.

If merchant panel has accept a request with some signature that signature cannot be used again, even to send the request with the same parameters (this includes parameter 'time').

The resulting hash is passed in the HTTP header 'Sign'.

In addition to the calculated signature, the request must also contain an 'Api-Key' header containing the used API key. Example:

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

You may sign the request sent to the AxtonPay with any valid key that belongs to this checkout. However the AxtonPay always use the key which you have selected in the merchant panel.

Example of signature calculation:

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

Pay attention to whitespaces and line breaks in another example:

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

The Python example of composing the string for signature calculation:

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

Parameters

The API accepts all parameters in both QUERY_STRING and in the body of the POST request.

Boolean variables

The API expects to get '0' or '1' in Boolean variables, but because of implicit type conversion, any text string will be treated as a '1', even the word 'false'. Thus, to explicitly set a 'FALSE' value for a Boolean variable, you need to pass to it either the value '0' or an empty string.

Decimal separator

Only the decimal point is used as a decimal separator in numbers.

Character case in parameters

With few exceptions, all parameters are case-sensitive.

Callback URL

In the admin panel of AxtonPay, on the checkout settings page, it is possible to set store URLs for receiving server-server notifications from AxtonPay, as well as URLs for redirecting the buyer after invoice payment or its cancelation, as well as in case of an error.

These URLs can be overridden in the invoice creation request.

Methods of AxtonPay API

Invoice creation: /api/v1/private/checkout/payment/create

Method /api/v1/private/checkout/payment/create initiates the invoice creation.

If successful, the method returns a link ('invoice_url') to which you should forward the customer for payment.

Own invoice parameters:

• time (required) - POSIX timestamp (Unix time)
• amount (required) - amount to be paid (the price of the product or service the store wants to receive)
• currency (required) - 3-letter currency code according to ISO 4217-alpha, case-insensitive
• pms (required) - payment methods displayed on the invoice page. If you want to allow all payment methods, the value is 'all'; if you want to allow only some of them, list their comma-separated numeric identifiers.
• pm - identifier of the selected payment method. It is important that if the 'pm' parameter is passed, the invoice will be created in 'transparent mode', i.e. the buyer will not see the invoice page, but will go right to the payment system.
• extra_data - an associative array containing any additional data; this data is returned to the store in its entirety
• shop_user_id - user identifier in the store, it is returned to the store in unchanged form
• shop_payment_id - payment identifier in the store, it is returned to the store in unchanged form
• shop_name - store name (displayed on the invoice page)
• shop_payment_desc - order description (displayed on the invoice page)
• shop_payment_remark - your notes about this payment (this is a field for any notes you have on the payment, which AxtonPay does not pass anywhere; it is only visible in the list of payments; it does not go back to the store)
• valid_time - the time interval in which the invoice can be paid; in seconds
• view_time - time interval during which the invoice is available for viewing via external link; in seconds; countdown starts after 'valid_time' period ends
• server_notification_method - method of sending server-server notifications about payment statuses to the store; valid values: POST, GET

Some settings for the invoice are set on the checkout settings page. But the values passed in the request will take precedence over these settings.

Checkout parameters which can be overridden for this invoice:

• customer_success_url - a link to which the buyer will be redirected if the invoice is successfully paid (i.e. if the invoice status is 'paid' or 'overpaid').
• customer_cancel_url - a link to which the buyer will be redirected if the payment is canceled
• customer_fail_url - a link to which the buyer will be redirected if the payment ends in an error
• server_notification_url - link for sending server-server notifications of payment statuses to the store

Note: In order to comply with your own privacy policy, it is usually not necessary to include your customer's personal data in the invoice properties. For example, in the "shop_user_id" parameter, it is better to specify an abstract customer ID rather than their email or phone number. Also in the "shop_payment_desc", it is better not to include customer data at all, because they already know everything about themselves; instead, you can write some information about the paid goods or services, or even just write the type of action, for example, "Purchase" or "Balance top-up".

All references are necessarily transmitted with the protocol.

Example of request:

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

Example of a successful response when requesting the creation of an invoice:

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

Obtaining invoice information: /api/v1/private/checkout/payment/get/{PID}

To get the information you need to call the method /api/v1/private/checkout/payment/get/{PID}, by specifying the PID of the invoice at the end of the URL.

Параметры запроса:

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

Example of a line for composing a signature:

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

// String for signature calculation: 
time=1766837343

Example of an answer:

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

Comparison of amount requested and amount paid

The response contains several different amounts (in the currency in which the invoice was issued):

• "amount" - invoiced amount,
• "filled" - paid part of the invoice,
• "total_filled" - how much the client paid in total, including commissions.

If "filled = amount", then it's paid exactly as much as it needs to be.

If "filled > amount", there is an overpayment.

If "filled < amount", the invoice has not been paid in full (underpayment).

Invoice: processing of notification from AxtonPay about status change

Each time the status of an invoice is changed, AxtonPay sends a notification to server_notification_url (using the server_notification_method)

Example data:

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

In response to this notification AxtonPay expects to receive HTTP code 200, which confirms its successful receipt. Otherwise, AxtonPay will retry 12 more times at progressively increasing intervals, and then the notification status changes to 'error' (but this does not affect the status of the invoice itself).

Possible status values:

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

Successful payment statuses are 1 (paid) and 5 (overpaid); in case of their receipt you can transfer the paid purchase to the customer or replenish the balance. For payments with status 5 (overpaid), in case of balance replenishment you can replenish the balance by the amount of the actually received payment, but in case of sale of goods/services and a significant amount of overpayment it is advisable to contact the payer and decide with him how to deal with the overpayment.

Partially successful status is 4 (underpaid); in case of receiving this status it is possible to recharge the balance by the amount of actually received payment. However, this status cannot be considered successful for the sale of goods/services.

All other statuses - 0 (pending), 2 (error), 3 (canceled by customer) mean complete absence of payment; in case of their receipt no actions on balance replenishment or sale of goods/services should be performed.

Signature checking

To be sure that notification is sent by AxtonPay exactly it is necessary to verify the signature of the received notification before trusting it. The verification is similar to signing your own requests, only the last step is added, when you should compare the calculated signature with the received HTTP header 'Sign'.

The main steps after receiving notification about the changed payment status are following:

• take the whole string of arguments (QUERY_STRING) from the received notification,
• take the whole POST data (REQUEST_BODY) from the received notification,
• calculate the signature using those QUERY_STRING + REQUEST_BODY and the appropriate 'Secret key',
• compare calculated signature with one that is received in the HTTP header 'Sign',
• if the signatures are the same, the notification really came from AxtonPay;
• if the signatures are different, it may be an attempt to cheat by the payer.

Example of a line for signature generation:

// 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 that the store has processed the payment information: /api/v1/private/checkout/payment/confirm/{PID}

This request is sent to AxtonPay in response to a notification received from it. Functionally, it is a confirmation that the store has successfully received and processed the received notification.

To send a request, call the method /api/v1/private/checkout/payment/confirm/{PID}, by specifying the pid of the invoice at the end of the URL.

Request parameters:

• time (required) - POSIX timestamp (Unix time)
• status (required, integer) - payment status number for which the store sends confirmation

If the transmitted status matches the current status of this invoice in the system, AxtonPay will respond with 'OK' and if it does not match, it will respond with an error.

Example of a line for signature generation:

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

Example of a response if the current payment status is the same:

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

Example of a response if the current payment status differs from the one transmitted in the request:

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

Currency codes

The currencies that can be used for an invoice creation.

Most of used currency codes belong to fiat currencies, and they are equal to the ISO 4217. Also list contains a several cryptocurrencies.