AxtonPay API

Informação comum

Ponto de extremidade da API

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

Content-type

A API aceita HTTP pedidos com 2 tipos de conteúdo: 'application/x-www-form-urlencoded', 'application/json'.

O cabeçalho HTTP deve ajustar-se ao conteúdo do corpo POST.

Abreviaturas e definições

• {PID} - ID da fatura, geralmente é a sequência alfanumérica única de 8 caracteres.
• Shop - O seu website que aceita pagamentos através do serviço AxtonPay

Algoritmo de trabalho com API

Sequência habitual de ações para receber pagamento:

• criar uma fatura ('/api/v1/private/checkout/payment/create'), a resposta da API irá retornar o URL da fatura ('invoice_url'),
• envie o comprador para esta fatura para efetuar o pagamento,
• espere pelas notificações do servidor AxtonPay, que irão chegar a 'server_notification_url',
• ao receber qualquer notificação de AxtonPay, verifique a validade da sua assinatura e, preferencialmente, envie uma confirmação de recebimento a AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}'),
• se o estado de uma fatura for alterado, execute ações correspondentes a este estado (por exemplo, solicitar informações completas sobre a fatura, enviar as mercadorias, criar um ticket para a equipa de suporte, etc.)

Se definir um 'server_notification_url' vazio ou inválido ao criar uma fatura, o serviço não consegue enviar notificações sobre alterações de estado; nesses casos, deverá verificar a fatura você mesmo em algum intervalo ('/api/v1/private/checkout/payment/get/{PID}').

Autorização de pedidos

Para autorizar um pedido, é necessário calcular um Hash a partir de uma cadeia formada de uma maneira especial. A cadeia é composta concatenando (colando) os argumentos da URL (QUERY_STRING) e o corpo do pedido POST (REQUEST_BODY). É importante que todos os componentes sejam considerados exatamente na forma em que serão transmitidos para o servidor. Os argumentos da URL (QUERY_STRING) devem ser retirados da URL como uma única linha, sem alterar a ordem dos argumentos e sem eliminar qualquer elemento. O corpo do pedido POST (REQUEST_BODY) também deve ser usado sem quaisquer alterações, incluindo não remover aspas, espaços, colchetes ou quebras de linha.

Nos casos de um corpo de pedido POST vazio, e no caso de argumentos de URL vazios, esse componente será simplesmente uma string vazia.

A sequência de dados no pedido de assinatura: QUERY_STRING primeiro, depois os dados POST. Não deve inserir quaisquer sinais de ligação entre eles, apenas concatenar as duas cadeias de texto.

Mais uma vez, cada símbolo é significativo. Não deve adicionar nem remover sequer um espaço em branco ou símbolo de nova linha. Apenas use os dados brutos recebidos pelo servidor.

Um SHA-256 hash com a chave 'Secret key' é retirado da string resultante e usado como o segundo argumento da função hash_hmac().

É obrigatório passar o parâmetro 'time' que contém o POSIX timestamp (Unix time) atual.

Esta assinatura é válida por 24 horas. Se o valor do parâmetro 'time' diferir da hora atual do servidor por mais de 24 horas (seja para a frente ou para trás), o pedido falhará mesmo que a assinatura seja calculada sem erros.

Se o painel de comerciante aceitar um pedido com alguma assinatura, essa assinatura não pode ser usada novamente, mesmo para enviar o pedido com os mesmos parâmetros (isto inclui o parâmetro 'time').

O hash resultante é passado no cabeçalho HTTP 'Sign'.

Além da assinatura calculada, a requisição deve também conter um cabeçalho 'Api-Key' com a chave API utilizada. Exemplo:

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

Pode assinar o pedido enviado ao AxtonPay com qualquer chave válida que pertença a este checkout. No entanto, o AxtonPay utiliza sempre a chave que selecionou no painel do comerciante.

Exemplo de cálculo de assinatura:

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

Preste atenção aos espaços em branco e quebras de linha noutro exemplo:

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

O Python exemplo de compor a string para o cálculo da assinatura:

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

Parâmetros

A API aceita todos os parâmetros tanto em QUERY_STRING como no corpo do pedido POST.

Variáveis booleanas

A API espera receber '0' ou '1' em variáveis Booleanas, mas devido à conversão implícita de tipos, qualquer cadeia de texto será tratada como '1', mesmo a palavra 'false'. Assim, para definir explicitamente um valor 'FALSE' para uma variável Booleana, é necessário passar-lhe ou o valor '0' ou uma cadeia vazia.

Separador decimal

Apenas o ponto decimal é usado como separador decimal nos números.

Maiúsculas e minúsculas nos parâmetros

Com poucas exceções, todos os parâmetros diferenciam maiúsculas de minúsculas.

URL de retorno de chamada

No painel de administração do AxtonPay, na página de definições de checkout, é possível definir URLs da loja para receber notificações servidor-servidor do AxtonPay, assim como URLs para redirecionar o comprador após o pagamento da fatura ou a sua anulação, bem como em caso de erro.

Estes URLs podem ser substituídos na solicitação de criação de fatura.

Métodos da AxtonPay API

Criação de fatura: /api/v1/private/checkout/payment/create

O método /api/v1/private/checkout/payment/create inicia a criação da fatura.

Se for bem-sucedido, o método retorna um link ('invoice_url') para o qual deve encaminhar o cliente para pagamento.

Parâmetros da fatura própria:

• time (obrigatório) - POSIX timestamp (Unix time)
• amount (obrigatório) - quantia a pagar (o preço do produto ou serviço que a loja deseja receber)
• currency (obrigatório) - Código de moeda de 3 letras de acordo com ISO 4217-alpha, sem distinção entre maiúsculas e minúsculas
• pms (obrigatório) - métodos de pagamento exibidos na página da fatura. Se quiser permitir todos os métodos de pagamento, o valor é 'all'; se quiser permitir apenas alguns deles, liste os seus identificadores numéricos separados por vírgulas.
• pm - identificador do método de pagamento selecionado. É importante que, se o parâmetro 'pm' for passado, a fatura seja criada em 'modo transparente', ou seja, o comprador não verá a página da fatura, mas será direcionado diretamente para o sistema de pagamento.
• extra_data - um array associativo contendo quaisquer dados adicionais; estes dados são devolvidos à loja na sua totalidade
• shop_user_id - identificador do utilizador na loja, ele é devolvido à loja na forma inalterada
• shop_payment_id - identificador de pagamento na loja, é devolvido à loja na forma inalterada
• shop_name - nome da loja (exibido na página da fatura)
• shop_payment_desc - descrição da encomenda (exibida na página da fatura)
• shop_payment_remark - as suas notas sobre este pagamento (este é um campo para quaisquer notas que tenha sobre o pagamento, que AxtonPay não transmite para lado nenhum; é apenas visível na lista de pagamentos; não volta para a loja)
• valid_time - o intervalo de tempo em que a fatura pode ser paga; em segundos
• view_time - intervalo de tempo durante o qual a fatura está disponível para visualização através de link externo; em segundos; a contagem decrescente começa após o fim do período 'valid_time'
• server_notification_method - método de envio de notificações servidor-servidor sobre estados de pagamento para a loja; valores válidos: POST, GET

Algumas configurações para a fatura estão definidas na página de configurações de checkout. Mas os valores enviados na solicitação terão prioridade sobre estas configurações.

Parâmetros de checkout que podem ser substituídos para esta fatura:

• customer_success_url - um link para o qual o comprador será redirecionado se a fatura for paga com sucesso (ou seja, se o estado da fatura for 'paid' ou 'overpaid').
• customer_cancel_url - um link para o qual o comprador será redirecionado se o pagamento for cancelado
• customer_fail_url - um link para o qual o comprador será redirecionado se o pagamento terminar com um erro
• server_notification_url - link para enviar notificações servidor-servidor sobre estados de pagamento para a loja

Nota: Para cumprir a sua própria política de privacidade, geralmente não é necessário incluir os dados pessoais do seu cliente nas propriedades da fatura. Por exemplo, no parâmetro "shop_user_id", é melhor especificar um ID de cliente abstrato em vez do seu email ou número de telefone. Também no "shop_payment_desc", é preferível não incluir dados do cliente de todo, porque eles já sabem tudo sobre si próprios; em vez disso, pode escrever alguma informação sobre os bens ou serviços pagos, ou até apenas indicar o tipo de ação, por exemplo, "Compra" ou "Recarregamento de saldo".

Todas as referências são necessariamente transmitidas com o protocolo.

Exemplo de pedido:

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

Exemplo de uma resposta bem-sucedida ao solicitar a criação de uma fatura:

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

A obter informações da fatura: /api/v1/private/checkout/payment/get/{PID}

Para obter a informação que precisa, chame o método /api/v1/private/checkout/payment/get/{PID}, especificando o PID da fatura no final do URL.

Parâmetros da requisição:

• time (obrigatório) - POSIX timestamp (Unix time)

Exemplo de uma linha para compor uma assinatura:

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

// String for signature calculation: 
time=1766837343

Exemplo de uma 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"
    }
}

Comparação entre o montante solicitado e o montante pago

A resposta contém vários montantes diferentes (na moeda em que a fatura foi emitida):

• "amount" - montante faturado,
• "filled" - pagou parte da fatura,
• "total_filled" - quanto o cliente pagou no total, incluindo comissões.

Se "filled = amount", então é pago exatamente o que é necessário.

Se "filled > amount", há um pagamento em excesso.

Se "filled < amount", a fatura não foi paga na totalidade (pagamento insuficiente).

Fatura: processamento da notificação de AxtonPay sobre a mudança de estado

Cada vez que o estado de uma fatura é alterado, AxtonPay envia uma notificação para server_notification_url (usando o server_notification_method)

Exemplo de dados:

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

Em resposta a esta notificação AxtonPay espera receber HTTP code 200, o que confirma o seu recebimento com sucesso. Caso contrário, AxtonPay irá tentar 12 vezes mais em intervalos progressivamente maiores, e depois o estado da notificação muda para 'error' (mas isto não afeta o estado da própria fatura).

Valores de estado possíveis:

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

Os estados de pagamento bem-sucedidos são 1 (paid) e 5 (overpaid); no caso de os receber, pode transferir a compra paga para o cliente ou reabastecer o saldo. Para pagamentos com o estado 5 (overpaid), no caso de reabastecimento do saldo, pode reabastecer o saldo pelo montante do pagamento realmente recebido, mas no caso de venda de bens/serviços e um montante significativo de pagamento em excesso, é aconselhável contactar o pagador e decidir com ele como lidar com o pagamento em excesso.

O estado parcialmente bem-sucedido é 4 (underpaid); no caso de receber este estado, é possível recarregar o saldo pelo montante do pagamento efetivamente recebido. No entanto, este estado não pode ser considerado bem-sucedido para a venda de bens/serviços.

Todos os outros estados - 0 (pending), 2 (error), 3 (canceled by customer) significam ausência total de pagamento; no caso da sua receção, não devem ser realizadas ações de reposição de saldo ou venda de bens/serviços.

Verificação de assinatura

Para ter a certeza de que a notificação é enviada pela AxtonPay, é necessário verificar a assinatura da notificação recebida antes de confiar nela. A verificação é semelhante à assinatura dos seus próprios pedidos, apenas é adicionado o último passo, quando deve comparar a assinatura calculada com o cabeçalho HTTP recebido 'Sign'.

Os principais passos após receber a notificação sobre a alteração do estado de pagamento são os seguintes:

• pegar toda a sequência de argumentos (QUERY_STRING) da notificação recebida,
• pegue o POST data (REQUEST_BODY) inteiro da notificação recebida,
• calcule a assinatura usando aqueles QUERY_STRING + REQUEST_BODY e o 'Secret key' apropriado,
• comparar a assinatura calculada com a que é recebida no cabeçalho HTTP 'Sign',
• se as assinaturas forem iguais, a notificação realmente veio de AxtonPay;
• se as assinaturas forem diferentes, pode ser uma tentativa de fraude por parte do pagador.

Exemplo de uma linha para geração de assinatura:

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

Confirmação de que a loja processou a informação de pagamento: /api/v1/private/checkout/payment/confirm/{PID}

Este pedido é enviado para AxtonPay em resposta a uma notificação recebida por ele. Funcionalmente, é uma confirmação de que a loja recebeu e processou com sucesso a notificação recebida.

Para enviar um pedido, chame o método /api/v1/private/checkout/payment/confirm/{PID}, especificando o pid da fatura no final da URL.

Parâmetros do pedido:

• time (obrigatório) - POSIX timestamp (Unix time)
• status (obrigatório, inteiro) - número do estado de pagamento para o qual a loja envia confirmação

Se o estado transmitido corresponder ao estado atual desta fatura no sistema, AxtonPay irá responder com 'OK' e, se não corresponder, irá responder com um erro.

Exemplo de uma linha para geração de assinatura:

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

Exemplo de uma resposta se o estado de pagamento atual for o mesmo:

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

Exemplo de uma resposta caso o estado de pagamento atual difira do transmitido na solicitação:

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

Códigos de moeda

As moedas que podem ser usadas para a criação de uma fatura.

A maioria dos códigos de moeda utilizados pertence a moedas fiduciárias e são iguais ao ISO 4217. A lista também contém várias criptomoedas.