3-3. コールバック
注文が処理されると、システムは販売者が設定したコールバック アドレスに通知メッセージを送信します。
コールバック アドレスの構成
注文を行う際、notifyUrl パラメータを通じてこの注文の専用コールバック アドレスを指定できます。このアドレスは、販売者のバックエンドで構成されたデフォルトのコールバック アドレスをオーバーライドします。
param.put("notifyUrl", "http://{domain}/callback/notifyUrl");
注文時に notifyUrl が入力されなかった場合、システムは販売者のバックエンドで構成されたデフォルトのコールバック アドレスをコールバックします。
デフォルトのコールバック アドレスは、作成時に販売者によって提供され、運用管理のバックグラウンドで維持できます。
コールバックリクエストメソッド
HTTP メソッド
POST
コンテンツタイプ
application/json
コールバック データの例
{
"amount": "100",
"bizType": "WITHDRAW_ANY_DIGITAL_WALLET",
"blockchain": {
"network": "TRON",
"receiverAddress": "THcJ2FeNBkuzd4PZBpRans6tx9QGg9KHRt",
"senderAddress": "TE35TrUfHjbGEBsVS6zVXdHS8HxXCWwC2y",
"txIndex": "2",
"txId": "d848e4b62ec6925b8b3ff49dbc4d839f3f88508497c3af525f0c8293cb303ab3"
},
"currency": "CNY",
"localOrderId": "TestOTM0625ROB016",
"merchantActualAmount": "138.12",
"merchantCurrency": "CNY",
"merchantId": 302992856974,
"merchantPaidAmount": "100",
"notifyTime": 1772173006425,
"orderCreateTime": 1772172958082,
"orderId": "472515854147845",
"status": "SUCCESS",
"type": "WITHDRAW",
"userAmount": "14.971722",
"userCurrency": "USDT",
"userMinerFee": "0",
"isReissue": false,
"userReceivableAmount": "14.971722",
"rate": "6.71080951",
"rateExpression": "1USDT≈6.7108CNY",
"sign": "2c27c7e8184cc709a64ad502ee42eab7",
"key": "9yUreYgTRtit39Dy"
}
**ビジネス開発のニーズを満たすために、将来、コールバック パラメーターに新しいフィールドが追加される可能性があります。新しく追加されたフィールドは、デフォルトで署名計算に参加します (署名ルールに特に指定されているフィールドを除く)。したがって、販売者システムは、フィールドの拡張による署名検証の失敗を回避するために、上位互換性を備えている必要があります。 **
コールバックパラメータの説明
| パラメータ名 | タイプ | 参加署名 | パラメータの意味 | パラメータの説明 |
|---|---|---|---|---|
amount | decimal | はい | 注文金額 | |
bizType | enum | はい | 注文タイプ | 注文タイプの説明は次のとおりです。 |
blockchain | object | はい | チェーントランザクション情報 | オンチェーン トランザクション情報。isBlockchain=true |
| └ネットワーク | String | はい | メインネット | |
| └受信者アドレス | String | はい | 受信者のアドレス | |
| └差出人住所 | decimal | はい | 送付先住所 | |
| └txId | String | はい | トランザクションID | ブロックチェーントランザクションハッシュ |
| └txインデックス | String | はい | トランザクションインデックス | トランザクションインデックス (バッチ転送シナリオ) |
currency | String | はい | 通貨 | 注文通貨 |
key | String | はい | 販売者キー | |
localOrderId | String | はい | 販売者の注文番号 | |
merchantActualAmount | decimal | はい | 販売者の実際の支払い額 | |
merchantCurrency | String | はい | 加盟店決済通貨 | |
merchantId | String | はい | 販売者 ID | |
merchantPaidAmount | decimal | はい | 販売者が受け取る金額または支払う金額 | |
merchantUserId | String | はい | 販売者ユーザー ID | |
notifyTime | long | はい | コールバック時間 | コールバック通知時間 |
orderCreateTime | long | はい | 注文作成時間 | |
orderId | String | はい | 注文番号 | プラットフォーム注文番号 (一意) |
status | String | はい | 支払い状況 | 成功、失敗 (以下の説明) |
type | String | はい | 注文タイプ | 支払い、出金（下記説明） |
userAmount | decimal | はい | ユーザーが実際に受け取ったまたは支払った金額 | |
userCurrency | String | はい | ユーザー通貨 | |
userMinerFee | String | はい | マイニング料金 | |
userReceivableAmount | String | はい | ユーザーが支払うべき金額または受け取るべき金額 | |
isReissue | Boolean | はい | 再発行するかどうか | コールバックを再発行するかどうか |
rate | string | はい | 為替レート | |
rateExpression | string | はい | 為替レートの式 | |
sign | String | いいえ | 署名値 | md5 署名 (詳細については署名アルゴリズムを参照) |
ステータス ステータスの説明
| ステータス値 | 説明 |
|---|---|
SUCCESS | 完了 |
FAIL | 失敗しました |
タイプ タイプの説明
| タイプ値 | 説明 |
|---|---|
PAYMENT | お支払い |
WITHDRAW | 出金 |
bizType ビジネス タイプの説明
| bizType | 説明 |
|---|---|
PAYMENT_WALLET_SCAN | VPAY ウォレットでコードをスキャンして支払う |
PAYMENT_TRANSFER | デジタル通貨バインディングアドレス直接入金 |
PAYMENT_ANY_DIGITAL_SCAN | QR コードをスキャンして、任意の金額のデジタル通貨を支払います |
PAYMENT_FIXED_DIGITAL_SCAN | デジタル通貨定額スキャンコード決済 |
WITHDRAW_WALLET | VPAY ウォレットへの出金 |
WITHDRAW_ANY_DIGITAL_WALLET | あらゆるデジタルウォレットへの出金 |
BATCH_PAY | 一括支払い |
コールバック応答要件
販売者がコールバックを正常に処理した後、次のコンテンツが返される必要があります。
success
システムが文字列 success を受信すると、コールバック処理は成功したとみなされ、再度送信されることはありません。
コールバック再試行メカニズム
次の場合:
- 応答がありません
- 返されるコンテンツは
successではありません - HTTPリクエストの例外
- サービスタイムアウト
システムは自動的にコールバック通知の送信を再試行します。
最大再試行回数
14次
再試行間隔
15s
15s
30s
180s
600s
1200s
1800s
1800s
1800s
3600s
10800s
10800s
21600s
21600s
繰り返しのコールバックによるビジネス データの繰り返し処理を避けるために、マーチャント システムは orderId に従って冪等処理を実装することをお勧めします。
署名の検証
コールバック通知を受信した後、マーチャントはまず署名検証を実行し、検証に合格した後にビジネス ロジックを実行する必要があります。 署名アルゴリズムは、注文リクエストの署名ルールと完全に一致しています。 「2.署名方法」を参照してください。
署名検証プロセス
- コールバックパラメータで
signを取得します 2.パラメータからsignを削除します - パラメータに販売者
keyを入力します - マーチャント
secretを使用して、署名ルールに従って署名を再計算します - コールバック内で計算結果が
signと一致するか比較する
署名検証が成功した後にのみ、注文業務が処理される必要があります。
Java 署名検証の例
public void notify(JSONObject data) {
log.info("收到回调通知：{}", data.toJSONString());
String key = "your_key";
String secret = "your_secret";
String sign = data.getString("sign");
data.put("key", key);
data.remove("sign");
String calculatedSign = SignUtils.getSign(data, secret);
if (!calculatedSign.equals(sign)) {
throw new DxBizException("签名验证失败");
}
// 业务处理逻辑
}