AxtonPay API

Información común

punto final de la API

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

Content-type

La API acepta HTTP solicitudes con 2 tipos de contenido: 'application/x-www-form-urlencoded', 'application/json'.

El encabezado HTTP debe ajustarse al contenido del cuerpo POST.

Abreviaturas y definiciones

• {PID} - ID de la factura, generalmente es la secuencia alfanumérica única de 8 caracteres.
• Shop - Tu sitio web que acepta pagos a través del servicio AxtonPay

Algoritmo de trabajo con API

Secuencia habitual de acciones para recibir el pago:

• crear una factura ('/api/v1/private/checkout/payment/create'), la respuesta de la API devolverá la URL de la factura ('invoice_url'),
• envía al comprador a esta factura para realizar el pago,
• espera las notificaciones del servidor AxtonPay, que llegarán a las 'server_notification_url',
• al recibir cualquier notificación de AxtonPay, verifique la validez de su firma y, preferiblemente, envíe una confirmación de recibo a AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• Si se cambia el estado de una factura, realiza las acciones correspondientes a este estado (por ejemplo, solicitar información completa sobre la factura, enviar los productos, crear un ticket para el equipo de soporte, etc.).

Si estableces una 'server_notification_url' vacía o inválida al crear una factura, el servicio no podrá enviar notificaciones sobre cambios de estado; en esos casos, deberías revisar la factura tú mismo en algún intervalo ('/api/v1/private/checkout/payment/get/{PID}').

Autorización de solicitudes

Para autorizar una solicitud es necesario calcular un Hash a partir de una cadena formada de manera especial. La cadena se compone concatenando (uniendo) los argumentos de la URL (QUERY_STRING) y el cuerpo de la solicitud POST (REQUEST_BODY). Es importante que todos los componentes se tomen exactamente en la forma en que serán enviados al servidor. Los argumentos de la URL (QUERY_STRING) deben tomarse de la URL como una sola línea, sin cambiar el orden de los argumentos y sin omitir ningún elemento. El cuerpo de la solicitud POST (REQUEST_BODY) también debe usarse sin ninguna modificación, incluyendo no eliminar comillas, espacios, corchetes o saltos de línea.

En los casos de un cuerpo de solicitud POST vacío y en el caso de argumentos de URL vacíos, ese componente simplemente será una cadena vacía.

La secuencia de datos en la solicitud de firma: QUERY_STRING primero, luego los datos POST. No debes insertar ningún signo de conexión entre ellos, solo concatenar las dos cadenas de texto.

Una vez más, cada símbolo es significativo. No deberías agregar ni eliminar siquiera un espacio en blanco o un símbolo de nueva línea. Simplemente utiliza los datos en bruto recibidos por el servidor.

Se toma un hash SHA-256 con la clave 'Secret key' de la cadena resultante y se utiliza como el segundo argumento de la función hash_hmac().

Es obligatorio pasar el parámetro 'time' que contiene la POSIX timestamp (Unix time) actual.

Esta firma es válida por 24 horas. Si el valor del parámetro 'time' difiere de la hora actual del servidor en más de 24 horas (ya sea hacia adelante o hacia atrás), la solicitud fallará incluso si la firma se calcula sin errores.

Si el panel del comerciante ha aceptado una solicitud con alguna firma, esa firma no puede usarse de nuevo, ni siquiera para enviar la solicitud con los mismos parámetros (esto incluye el parámetro 'time').

El hash resultante se pasa en el encabezado HTTP 'Sign'.

Además de la firma calculada, la solicitud también debe contener un encabezado 'Api-Key' que incluya la clave API utilizada. Ejemplo:

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

Puedes firmar la solicitud enviada a las AxtonPay con cualquier clave válida que pertenezca a este checkout. Sin embargo, las AxtonPay siempre usan la clave que has seleccionado en el panel del comerciante.

Ejemplo de cálculo de firma:

/* 
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ón a los espacios en blanco y los saltos de línea en otro ejemplo:

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

El Python ejemplo de cómo componer la cadena para el cálculo de la firma:

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

Parámetros

La API acepta todos los parámetros tanto en QUERY_STRING como en el cuerpo de la solicitud POST.

Variables booleanas

La API espera recibir '0' o '1' en variables booleanas, pero debido a la conversión implícita de tipos, cualquier cadena de texto se tratará como '1', incluso la palabra 'false'. Por lo tanto, para establecer explícitamente un valor 'FALSE' en una variable booleana, necesitas pasarle ya sea el valor '0' o una cadena vacía.

Separador decimal

Solo se utiliza el punto decimal como separador de decimales en los números.

Mayúsculas y minúsculas en los parámetros

Con pocas excepciones, todos los parámetros distinguen entre mayúsculas y minúsculas.

URL de retorno de llamada

En el panel de administración de AxtonPay, en la página de configuración de pago, es posible establecer las URL de la tienda para recibir notificaciones servidor a servidor de AxtonPay, así como las URL para redirigir al comprador después del pago de la factura o su cancelación, así como en caso de error.

Estas URL se pueden anular en la solicitud de creación de la factura.

Métodos de AxtonPay API

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

El método /api/v1/private/checkout/payment/create inicia la creación de la factura.

Si tiene éxito, el método devuelve un enlace ('invoice_url') al que deberías dirigir al cliente para el pago.

Parámetros de la factura propia:

• time (requerido) - POSIX timestamp (Unix time)
• amount (requerido) - cantidad a pagar (el precio del producto o servicio que la tienda desea recibir)
• currency (requerido) - Código de moneda de 3 letras según ISO 4217-alpha, sin distinguir mayúsculas de minúsculas
• pms (requerido) - métodos de pago mostrados en la página de la factura. Si deseas permitir todos los métodos de pago, el valor es 'all'; si deseas permitir solo algunos de ellos, enumera sus identificadores numéricos separados por comas.
• pm - identificador del método de pago seleccionado. Es importante que si se pasa el parámetro 'pm', la factura se creará en 'modo transparente', es decir, el comprador no verá la página de la factura, sino que irá directamente al sistema de pago.
• extra_data - un arreglo asociativo que contiene cualquier dato adicional; estos datos se devuelven a la tienda en su totalidad
• shop_user_id - identificador de usuario en la tienda, se devuelve a la tienda sin cambios
• shop_payment_id - identificador de pago en la tienda, se devuelve a la tienda sin cambios
• shop_name - nombre de la tienda (se muestra en la página de la factura)
• shop_payment_desc - descripción del pedido (se muestra en la página de la factura)
• shop_payment_remark - tus notas sobre este pago (este es un campo para cualquier nota que tengas sobre el pago, la cual AxtonPay no envía a ningún lugar; solo es visible en la lista de pagos; no regresa a la tienda)
• valid_time - el intervalo de tiempo en el que se puede pagar la factura; en segundos
• view_time - intervalo de tiempo durante el cual la factura está disponible para ver a través de un enlace externo; en segundos; la cuenta regresiva comienza después de que finaliza el período 'valid_time'
• server_notification_method - método de envío de notificaciones de servidor a servidor sobre los estados de pago a la tienda; valores válidos: POST, GET

Algunas configuraciones de la factura se establecen en la página de ajustes de pago. Pero los valores enviados en la solicitud tendrán prioridad sobre estas configuraciones.

Parámetros de pago que se pueden sobrescribir para esta factura:

• customer_success_url - un enlace al que el comprador será redirigido si la factura se paga con éxito (es decir, si el estado de la factura es 'paid' o 'overpaid').
• customer_cancel_url - un enlace al que se redirigirá al comprador si el pago se cancela
• customer_fail_url - un enlace al que el comprador será redirigido si el pago termina con un error
• server_notification_url - enlace para enviar notificaciones de estados de pago de servidor a servidor a la tienda

Nota: Para cumplir con su propia política de privacidad, generalmente no es necesario incluir los datos personales de su cliente en las propiedades de la factura. Por ejemplo, en el parámetro "shop_user_id", es mejor especificar un ID de cliente abstracto en lugar de su correo electrónico o número de teléfono. También en "shop_payment_desc", es mejor no incluir datos del cliente, porque ellos ya saben todo sobre sí mismos; en su lugar, puede escribir alguna información sobre los bienes o servicios pagados, o incluso solo escribir el tipo de acción, por ejemplo, "Compra" o "Recarga de saldo".

Todas las referencias se transmiten necesariamente con el protocolo.

Ejemplo de solicitud:

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

Ejemplo de una respuesta exitosa al solicitar la creación de 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"
}

Obteniendo información de la factura: /api/v1/private/checkout/payment/get/{PID}

Para obtener la información que necesitas, llama al método /api/v1/private/checkout/payment/get/{PID}, especificando el PID de la factura al final de la URL.

Parámetros de la solicitud:

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

Ejemplo de una línea para componer una firma:

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

// String for signature calculation: 
time=1766837343

Ejemplo de una respuesta:

{
    "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ón entre la cantidad solicitada y la cantidad pagada

La respuesta contiene varias cantidades diferentes (en la moneda en la que se emitió la factura):

• "amount" - importe facturado
• "filled" - pagó parte de la factura,
• "total_filled" - cuánto pagó el cliente en total, incluidas las comisiones.

Si "filled = amount", entonces se paga exactamente lo que necesita ser.

Si "filled > amount", hay un pago en exceso.

Si "filled < amount", la factura no ha sido pagada en su totalidad (pago insuficiente).

Factura: procesamiento de notificación de AxtonPay sobre cambio de estado

Cada vez que se cambia el estado de una factura, AxtonPay envía una notificación a server_notification_url (usando el server_notification_method)

Datos de ejemplo:

{
    "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 respuesta a esta notificación, AxtonPay espera recibir HTTP code 200, lo que confirma su recepción exitosa. De lo contrario, AxtonPay intentará 12 veces más a intervalos progresivamente crecientes, y luego el estado de la notificación cambia a 'error' (pero esto no afecta el estado de la factura en sí).

Posibles valores de estado:

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

Los estados de pago exitosos son 1 (paid) y 5 (overpaid); en caso de recibirlos, puedes transferir la compra pagada al cliente o recargar el saldo. Para los pagos con estado 5 (overpaid), en caso de recarga de saldo, puedes recargar el saldo por el monto del pago realmente recibido, pero en caso de venta de bienes/servicios y un monto significativo de sobrepago, es recomendable contactar al pagador y decidir con él cómo manejar el sobrepago.

El estado parcialmente exitoso es 4 (underpaid); en caso de recibir este estado, es posible recargar el saldo por la cantidad efectivamente recibida. Sin embargo, este estado no puede considerarse exitoso para la venta de bienes/servicios.

Todos los demás estados - 0 (pending), 2 (error), 3 (canceled by customer) significan ausencia total de pago; en caso de recibirlos, no se deben realizar acciones de recarga de saldo ni de venta de bienes/servicios.

Comprobación de firma

Para asegurarse de que la notificación la envía exactamente AxtonPay, es necesario verificar la firma de la notificación recibida antes de confiar en ella. La verificación es similar a firmar tus propias solicitudes, solo que se añade el último paso, cuando debes comparar la firma calculada con la cabecera HTTP recibida 'Sign'.

Los pasos principales después de recibir la notificación sobre el cambio en el estado de pago son los siguientes:

• toma toda la cadena de argumentos (QUERY_STRING) de la notificación recibida,
• toma todo el POST data (REQUEST_BODY) de la notificación recibida,
• calcula la firma usando esos QUERY_STRING + REQUEST_BODY y los 'Secret key' apropiados,
• comparar la firma calculada con la que se recibe en el encabezado HTTP 'Sign',
• si las firmas son las mismas, la notificación realmente vino de AxtonPay;
• Si las firmas son diferentes, podría ser un intento de fraude por parte del pagador.

Ejemplo de una línea para la generación de firmas:

// 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ón de que la tienda ha procesado la información de pago: /api/v1/private/checkout/payment/confirm/{PID}

Esta solicitud se envía a AxtonPay en respuesta a una notificación recibida de él. Funcionalmente, es una confirmación de que la tienda ha recibido y procesado correctamente la notificación recibida.

Para enviar una solicitud, llama al método /api/v1/private/checkout/payment/confirm/{PID}, especificando el pid de la factura al final de la URL.

Parámetros de solicitud:

• time (requerido) - POSIX timestamp (Unix time)
• status (obligatorio, número entero) - número de estado de pago para el cual la tienda envía la confirmación

Si el estado transmitido coincide con el estado actual de esta factura en el sistema, AxtonPay responderá con 'OK' y si no coincide, responderá con un error.

Ejemplo de una línea para la generación de firmas:

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

Ejemplo de una respuesta si el estado de pago actual es el mismo:

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

Ejemplo de una respuesta si el estado de pago actual difiere del que se transmitió en la solicitud:

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

Códigos de moneda

Las monedas que se pueden usar para la creación de una factura.

La mayoría de los códigos de moneda utilizados pertenecen a monedas fiduciarias, y son iguales al ISO 4217. También la lista contiene varias criptomonedas.