AxtonPay API

共通情報

APIエンドポイント

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

Content-type

APIは、2つのコンテンツタイプのHTTPリクエストを受け入れます: 'application/x-www-form-urlencoded', 'application/json'。

HTTP ヘッダーは POST 本文の内容に合うべきです。

略語と定義

• {PID} - 請求書のIDで、通常は一意の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 データです。それらの間に接続記号を挿入せず、単に2つの文字列を連結してください。

改めて言いますが、すべての記号は重要です。空白や改行の記号を追加したり削除したりしてはいけません。サーバーから受け取った生のデータをそのまま使用してください。

結果の文字列からキー'Secret key'を使ったSHA-256ハッシュが取り出され、関数hash_hmac()の第2引数として使用されます。

現在のPOSIX timestamp (Unix time)を含む'time'パラメータを渡すことは必須です。

この署名は24時間有効です。'time'パラメータの値が現在のサーバー時刻と24時間以上ずれている場合（前後どちらでも）、署名の計算にエラーがなくてもリクエストは失敗します。

もしマーチャントパネルがある署名付きのリクエストを受け入れた場合、その署名は再使用できません。同じパラメータ（'time'を含む）でリクエストを送信する場合であっても使用できません。

生成されたハッシュは HTTP ヘッダー 'Sign' に渡されます。

計算された署名に加えて、リクエストには使用された API キーを含む 'Api-Key' ヘッダーも含める必要があります。例:

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

署名計算のための文字列を作成する最も基本的な例：

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

パラメータ

APIは、すべてのパラメータをQUERY_STRINGでもPOSTリクエストの本文でも受け入れます。

ブール変数

APIはBoolean変数で'0'または'1'を受け取ることを期待していますが、暗黙の型変換のため、どんなテキスト文字列も'1'として扱われます。'false'という単語でさえもです。したがって、Boolean変数に明示的に『FALSE』値を設定するには、'0'の値か空の文字列のいずれかを渡す必要があります。

小数点

数字では、小数点として小数点のみが使用されます。

パラメータの文字の大文字と小文字

ほとんど例外を除いて、すべてのパラメータは大文字と小文字が区別されます。

コールバックURL

AxtonPayの管理パネルのチェックアウト設定ページでは、AxtonPayからのサーバー間通知を受け取るためのストアURLや、請求書の支払い後またはキャンセル後、エラー発生時に購入者をリダイレクトするためのURLを設定することが可能です。

これらの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}

必要な情報を取得するには、URLの末尾に請求書のPIDを指定して、メソッド/api/v1/private/checkout/payment/get/{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_methodを使ってserver_notification_urlに通知を送ります

例のデータ:

{
    "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 から受け取った通知への応答として送信されます。機能的には、ストアが受信した通知を正常に受け取り、処理したことを確認するものです。

リクエストを送信するには、URLの末尾に請求書のpidを指定して、/api/v1/private/checkout/payment/confirm/{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に等しいです。また、リストにはいくつかの暗号通貨も含まれています。