🔔 Webhook通知

Webhookを設定して通知を受け取るようにします。HaloPayは最終的な取引結果をmerchantに通知します。Webhook URLは**アプリ管理ページ**で設定できます。

以下のイベントが発生すると、merchantが設定したコールバックインターフェースにリクエストが送信されます：

✅ 決済取引成功
⏱️ 決済タイムアウト
💡 決済不足
✅ 出金成功
❌ 出金失敗

コールバック頻度：5s、15s、30s、3m、10m、20m、30m、30m、30m、60m、3h、3h、3h、6h、6h。合計：24h3m50s

コールバックの内容は常に暗号化されています。詳細については、署名をご覧ください。

Webhook通知

ヘッダー

名前	値	必須	型	説明
X-Appid	h3j6k9m2n...	Y	string	merchantの一意の認証情報。アプリ管理ページで確認できます。
X-Timestamp	1700349280	Y	string	秒単位のタイムスタンプ（10桁）。リクエストは2分間有効です。
X-Sign	e0c6a719ebc366da...	Y	string	hmacSHA256(body（json文字列）+timestamp+appKey)
X-EventType	Paid	Y	string	取引ステータスコード

決済 Body

{
  "appid": "ad4cyr8dpfs9j2u1",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd17b7e4ad06f0d6ec24099c013",
  "status": "PAID",  (TO-BE-PAID/PAID/TIME-OUT)
  "time": 1773471015
}

💡

顧客が全額支払わなくても、ステータスフィールドをTO-BE-PAIDに設定したコールバック通知を送ります。amount_collectedフィールドには、支払われたトークン数が表示されます。

決済の時間制限を超過すると、ステータスフィールドをTIME-OUTに設定したコールバックを送ります。amount_collectedフィールドにも支払われたトークン数が表示されます。

出金 Body

{
  "appid": "ad4cyr8dpfs9j2u1",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
  "currency_id": 75,
  "status": "PAID",  (PAID/FAIL)
  "time": 1773473637,
  "token_amount": "1",
  "trade_no": "202603141533083d1eba01c48c2a873c",
  "txid": "aa23e0aebd2e4c5b82786a5e8b1f414222c7c525a438b95e2cc7d67c81187a5d",
  "type": "TRANSFER"
}

QRコード決済 Body

{
  "appid": "1aiqfs0agrd3b9fm", (デフォルトでは支払いAPPIDと異なります。)
  "trade_no": "2c8b150bf35abc59189e333c107247db",
  "type": "QR_PAYMENT",
  "chain": "Tron",
  "chain_id": 3448148188,
  "contract": "TRX",
  "txid": "2cdf12e85ec73a61280daaf49c4f27686519407fa0dc7b7744596cad29cbd53c",
  "currency_id": 75,
  "from_address": "TSpjU4PUYzAyY88wyKEEMD7MryneC1WLeb",
  "to_address": "TY1RJdyJh4y1tgmPFrnSaWFhM1HwqTvCQ1",
  "token_amount": "11",
  "status": "PAID",  (PAID)
  "time": 1773473913
}

パラメータ

フィールド	型	説明
appid	string	merchantのAPPID
trade_no	string	取引ID
out_trade_no	string	merchantの注文ID
amount	string	取引金額（法定通貨金額）
token_amount	string	取引金額（トークン）
chain	string	チェーン名
chain_id	int	チェーンID
type	string	取引タイプ（「PAYMENT/TRANSFER/QR_PAYMENT」）
currency_id	int	グローバル一意の通貨ID TokenList
txid	string	オンチェーン取引ハッシュ
status	string	取引ステータス（TO-BE-PAID/PAID/TIME-OUT/FAIL）。注文が完全に支払われていない場合、TO-BE-PAIDコールバックがトリガーされます。
time	int	最終オンチェーン時刻（失敗した場合、タイムアウト期間を返します）
amount_collected	string	ユーザーが支払ったトークン数
contract	string	トークンのコントラクトアドレス。主通貨はETH/TRX/BNB
from_address	string	決済ウォレットアドレス
to_address	string	受取ウォレットアドレス

💡

merchantは情報の安全を保証するために署名します。注文の処理に成功したら、HTTPレスポンスのボディに「Success」を返してください。処理に失敗した場合、HaloPayは再送信を試み、Webhookは最大15回までリトライします（コールバック頻度：5s、15s、30s、3m、10m、20m、30m、30m、30m、60m、3h、3h、3h、6h、6h、合計：24h3m50s）。

📌 例

Merchant Webhookサーバーへのリクエスト

POST /webhook/callback HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
X-Appid: ad4cyr8dpfs9j2u1
X-Timestamp: 1773471015
X-Sign: e0c6a719ebc366da...
X-EventType: Paid

{
  "appid": "ad4cyr8dpfs9j2u1",
  "trade_no": "202603141449020ad66d22c5787af677",
  "out_trade_no": "20250101xxxxxxxxxxxxx12221c",
  "amount_collected": "5",
  "amount": "5",
  "token_amount": "4.998045",
  "chain": "Tron",
  "chain_id": 3448148188,
  "type": "PAYMENT",
  "currency_id": 75,
  "txid": "008f81782daa47709d67bc2073ffff639035cfd17b7e4ad06f0d6ec24099c013",
  "status": "PAID",
  "time": 1773471015
}

Merchant Webhookサーバーからのレスポンス

HTTP/1.1 200 OK
Content-Type: text/plain

Success

Webhook通知​

📌 例​

Webhook通知

📌 例