AxtonPay API

常见信息

API端点

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

Content-type

API 接受 HTTP 请求，支持 2 种内容类型：'application/x-www-form-urlencoded', 'application/json'。

HTTP 头部应适合 POST 正文的内容。

缩写和定义

• {PID} - 发票的编号，通常是唯一的8位字母数字组合。
• Shop - 您的网站通过 AxtonPay 服务接受支付

与 API 一起工作的算法

收到付款的通常操作顺序：

• 创建发票 ('/api/v1/private/checkout/payment/create')，API 响应将返回发票 URL ('invoice_url')，
• 将买家引导到此发票以进行付款，
• 等待AxtonPay服务器通知，这些通知将发送到'server_notification_url'，
• 在收到来自 AxtonPay 的任何通知后，检查其签名的有效性，并最好向 AxtonPay ('/api/v1/private/checkout/payment/confirm/{PID}') 发送接收确认，
• 如果发票的状态发生变化，请执行与该状态对应的操作（例如，请求有关发票的完整信息、发货、创建支持团队的工单等）。

如果在创建发票时设置了空白或无效的'server_notification_url'，服务将无法发送有关状态更改的通知；在这种情况下，您应当在某个间隔时间内自行检查发票（'/api/v1/private/checkout/payment/get/{PID}'）。

请求授权

要授权请求，必须从以特定方式形成的字符串计算哈希。该字符串由连接（粘合）URL 参数（QUERY_STRING）和 POST 请求的主体（REQUEST_BODY）组成。重要的是，所有组件都应以传输到服务器的形式完整获取。URL 参数（QUERY_STRING）应从 URL 中获取为单行，不改变参数顺序，也不丢失任何元素。POST 请求主体（REQUEST_BODY）也应完整使用，不进行任何修改，包括不得去掉引号、空格、括号或换行符。

在空的 POST 请求体和空的 URL 参数的情况下，该组件将只是一个空字符串。

签名请求中的数据顺序：QUERY_STRING 首先，然后是 POST 数据。你不应在它们之间插入任何连接符号，只需将两个文本字符串连接起来。

再一次，每个符号都很重要。你不应该添加或删除任何空格或换行符号。只使用服务器接收到的原始数据。

从结果字符串中取出带有键 'Secret key' 的 SHA-256 哈希，并将其用作函数 hash_hmac() 的第二个参数。

必须传递包含当前 POSIX timestamp (Unix time) 的 'time' 参数。

此签名有效期为24小时。如果'time'参数的值与当前服务器时间相差超过24小时（无论是向前还是向后），即使签名计算正确，请求也会失败。

如果商户面板已经接受了带有某个签名的请求，该签名不能再次使用，即使是发送具有相同参数的请求（这包括参数'time'）。

生成的哈希值会通过 HTTP 头 'Sign' 传递。

除了计算出的签名，请求还必须包含一个 'Api-Key' 头部，其中包含所使用的 API 密钥。示例：

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

您可以使用属于此结账的任何有效密钥签署发送到 AxtonPay 的请求。但是 AxtonPay 总是使用您在商户面板中选择的密钥。

签名计算示例：

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

注意另一个例子中的空格和换行：

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

用于签名计算的字符串组合示例 Python：

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

参数

该 API 接受所有参数，无论是在 QUERY_STRING 中还是在 POST 请求的正文中。

布尔变量

API 期望在布尔变量中接收 '0' 或 '1'，但是由于隐式类型转换，任何文本字符串都会被视为 '1'，甚至包括单词 'false'。因此，要显式设置布尔变量的“FALSE”值，您需要传递给它 '0' 值或空字符串。

小数分隔符

在数字中，只有小数点被用作小数分隔符。

参数中的字符大小写

除少数例外，所有参数都区分大小写。

回调 URL

在AxtonPay的管理面板中，在结账设置页面，可以设置用于接收来自AxtonPay的服务器到服务器通知的商店网址，以及在发票付款或取消后重定向买家的网址，以及在发生错误时的重定向网址。

这些 URL 可以在发票创建请求中被覆盖。

AxtonPay API 的方法

发票创建：/api/v1/private/checkout/payment/create

方法 /api/v1/private/checkout/payment/create 开始创建发票。

如果成功，该方法将返回一个链接（'invoice_url'），您应将客户引导至该链接进行付款。

自有发票参数：

• time （必填） - POSIX timestamp (Unix time)
• amount （必填） - 应支付金额（商店希望收到的产品或服务价格）
• currency （必填） - 根据ISO 4217-alpha的3位字母货币代码，不区分大小写
• pms （必填） - 发票页面上显示的付款方式。如果您想允许所有付款方式，值为'all'；如果您只想允许其中的某些方式，请列出它们以逗号分隔的数字标识符。
• pm - 所选支付方式的标识符。重要的是，如果传递了'pm'参数，发票将以“透明模式”创建，即买家不会看到发票页面，而是直接进入支付系统。
• extra_data - 一个包含任何附加数据的关联数组；这些数据将完整地返回给存储
• shop_user_id - 商店中的用户标识符，它以不变的形式返回给商店
• shop_payment_id - 商店中的支付标识符，它以不变的形式返回给商店
• shop_name - 商店名称（显示在发票页面上）
• shop_payment_desc - 订单描述（显示在发票页面上）
• shop_payment_remark - 关于此付款的备注（这是用于记录您对该付款的任何备注的字段，AxtonPay 不会将其传递到任何地方；它仅在付款列表中可见；不会返回到商店）
• valid_time - 发票可支付的时间间隔；以秒为单位
• view_time - 通过外部链接可查看发票的时间间隔；以秒为单位；倒计时在'valid_time'期间结束后开始
• server_notification_method - 将有关付款状态的服务器到服务器通知发送到商店的方法；有效值：POST, GET

发票的一些设置是在结账设置页面上进行的。但请求中传递的值将优先于这些设置。

可以为此发票覆盖的结账参数：

• customer_success_url - 如果发票支付成功（即发票状态为'paid'或'overpaid'），买家将被重定向到的链接。
• customer_cancel_url - 如果付款被取消，买家将被重定向到的链接
• customer_fail_url - 如果付款出现错误，买家将被重定向到的链接
• server_notification_url - 用于向商店发送服务器到服务器付款状态通知的链接

注意：为了遵守您自己的隐私政策，通常不需要在发票属性中包含客户的个人数据。例如，在"shop_user_id"参数中，最好指定一个抽象的客户ID，而不是他们的电子邮件或电话号码。在"shop_payment_desc"中，也最好完全不包含客户数据，因为他们自己已经知道所有信息；相反，您可以写一些关于已付款商品或服务的信息，或者只是写动作类型，例如“购买”或“余额充值”。

所有引用都必须通过协议传输。

请求示例：

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

请求创建发票时的成功回应示例：

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

获取发票信息：/api/v1/private/checkout/payment/get/{PID}

要获取所需的信息，请调用方法 /api/v1/private/checkout/payment/get/{PID}，在 URL 的末尾指定发票的 PID。

请求参数：

• time （必填） - POSIX timestamp (Unix time)

用于签名的一行示例：

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

// String for signature calculation: 
time=1766837343

答案示例：

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

申请金额与支付金额的比较

响应中包含若干不同金额（以开具发票的货币计）：

• "amount" - 开票金额
• "filled" - 支付了部分发票
• "total_filled" - 客户支付的总金额，包括佣金。

如果"filled = amount"，那么它就支付了恰好所需的金额。

如果 "filled > amount"，则有多付的情况。

如果"filled < amount"，发票未全额支付（付款不足）。

发票：处理来自AxtonPay的状态变更通知

每次发票状态改变时，AxtonPay 会向 server_notification_url 发送通知（使用 server_notification_method）

示例数据：

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

作为对该通知的响应，AxtonPay 预期收到 HTTP code 200，以确认其成功接收。否则，AxtonPay 将在逐渐增加的间隔内重试 12 次，然后通知状态会变为 'error'（但这不会影响发票本身的状态）。

可能的状态值：

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

成功的支付状态是 1 (paid) 和 5 (overpaid)；在收到这些状态时，您可以将已支付的购买转给客户或充值余额。对于状态为 5 (overpaid) 的付款，在充值余额时，可以按实际收到的付款金额充值，但在销售商品/服务且存在大量超额付款的情况下，建议联系付款人并与其决定如何处理超额付款。

部分成功状态为 4 (underpaid)；在收到此状态的情况下，可以按实际收到的付款金额充值余额。然而，此状态不能被视为商品/服务销售成功。

所有其他状态 - 0 (pending), 2 (error), 3 (canceled by customer) 意味着完全没有付款；在收到这些状态时，不应进行余额充值或商品/服务销售的任何操作。

签名检查

为了确保通知确实由AxtonPay发送，必须在信任之前验证收到的通知的签名。验证方式类似于签署你自己的请求，只是增加了最后一步，即你应该将计算出的签名与接收到的HTTP头'Sign'进行比较。

收到有关付款状态变更的通知后的主要步骤如下：

• 从接收到的通知中获取整串参数 (QUERY_STRING)，
• 从收到的通知中取出整个 POST data (REQUEST_BODY),
• 使用那些 QUERY_STRING + REQUEST_BODY 和适当的 'Secret key' 计算签名,
• 将计算出的签名与在 HTTP 头中接收到的签名进行比较 'Sign',
• 如果签名相同，通知确实来自 AxtonPay；
• 如果签名不同，付款人可能在尝试作弊。

用于生成签名的示例行：

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

确认商店已处理付款信息：/api/v1/private/checkout/payment/confirm/{PID}

此请求是发送给 AxtonPay 的，以回应从它收到的通知。从功能上讲，这是对商店已成功接收并处理所收到通知的确认。

要发送请求，请调用方法/api/v1/private/checkout/payment/confirm/{PID}，在URL末尾指定发票的pid。

请求参数：

• time （必填） - POSIX timestamp (Unix time)
• status （必填，整数） - 商店发送确认的支付状态编号

如果传输的状态与系统中此发票的当前状态匹配，AxtonPay 将以 'OK' 响应；如果不匹配，将返回错误。

用于生成签名的示例行：

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

如果当前付款状态相同的回应示例：

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

如果当前付款状态与请求中传输的状态不同，响应示例：

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

货币代码

可以用于创建发票的货币。

大多数使用的货币代码属于法定货币，它们等于ISO 4217。列表中也包含若干加密货币。