暗号資産決済APIの連携は、提供者に関わらず予測可能な形をたどります：インボイスを生成し、チェックアウトをリダイレクトまたは埋め込み、決済の進行に応じて非同期Webhookを受け取り、検証し、自分の記録と突き合わせます。難しいのは正常系ではなく、その周縁です。
中核の流れ
多くのゲートウェイは同じライフサイクルを持つREST APIを公開します。サーバ側で呼び出し（APIキーをブラウザに絶対に晒さない）、注文が支払われたかの真実の源としてはブラウザリダイレクトではなくWebhookを扱います。
注文の状態機械を先に設計しましょう：保留 → 不足/支払 → 確認 → 完了、期限切れと超過決済への明示的な分岐とともに。これを先に配線すれば、二重履行を招く絡んだ条件分岐を防げます。
- 金額、通貨、注文ID、Webhook URLでインボイスを生成。
- ホスト型チェックアウトを表示するか、アドレスと金額を自前で描画。
- 各状態変化ごとにWebhookを受け取り署名を検証。
- 決済が必要な確認数に達したか確かめてから履行。
- Webhookをオンチェーン取引と注文に突き合わせて消込。
インボイスの生成
インボイスは特定の金額を特定の注文に制限時間つきで結び付けます。Webhookが推測なしに逆引きできるよう注文IDをメタデータで送り、ゲートウェイが返すインボイスIDを保存します。
レートは期限切れになります — ゲートウェイが数分間レートを固定します。インボイスの期限と状態を保存し、UIがカウントダウンを表示でき、遅れた決済が失われた注文ではなく消込ケースとして扱われるようにします。
Webhookが真実の源
決済後のブラウザリダイレクトは利便であって保証ではありません — ユーザがタブを閉じるかもしれません。サーバが受け取るWebhookが行動の根拠です。全てのWebhookを検証しましょう：一つのフィールドも信じる前に署名（通常はシークレットで生ボディに対するHMAC）を確認します。
Webhook処理を冪等にしましょう。ゲートウェイは配信を再試行するので、同じ「支払済み」イベントが2回届き得ます。イベントやインボイスIDをキーにして繰り返し配信を何もしない操作にします。2xxを素早く返し、遅い処理は非同期で行い、ゲートウェイがタイムアウトで不要に再試行しないようにします。
確認と最終性
決済は最終化されるずっと前に（メムプール内やゼロ確認で）見えることがあります。金額とチェーンに合った確認しきい値を決め、満たされた時だけ履行します。速いチェーンの少額ステーブルコイン決済ではこれは速く、大きな金額はもっと待ちます。
自分の初回の目撃ではなくゲートウェイの「確認済み」状態を信じ、リスクを受け入れない限りゼロ確認決済で商品を渡さないことで、リオーグと二重支払を防ぎます。
消込と失敗ケース
消込は、全ての「支払済み」注文が実際のオンチェーン取引に対応し、その逆も成り立つことを毎日証明する仕事です。各注文にトランザクションハッシュ、受領額、ネットワークを保存すれば、不一致が調査ではなくクエリになります。
不足（購入者が少なく送った）、超過（差額を返金またはクレジット）、間違ったネットワークへの送信、期限切れ後に支払われたインボイスに明示的に備えましょう。量が増えればこれらは稀な例外ではなく毎週の出来事であり、それらを静かに処理するシステムこそが「本番対応」の実際の意味です。
よくある質問
ブラウザリダイレクトとWebhook、どちらを信じるべきですか？
Webhookです。リダイレクトはユーザがタブを閉じると失われ、偽装もされ得ます。サーバ側でWebhookの署名を検証し、注文が支払われたという権威ある信号として扱いましょう。
Webhookが2回処理されるのをどう防ぎますか？
処理を冪等にします。ゲートウェイは配信を再試行するので、インボイスやイベントIDをキーにして繰り返しを何もしない操作にします。同じ「支払済み」イベントが再び来たからと注文を二重に履行しないこと。
確認は何回待つべきですか？
金額とチェーンによります。速いネットワークの少額ステーブルコイン決済はほぼ即時に最終と扱え、大きな金額はより多くの確認が正当です。自分の初回目撃ではなくゲートウェイの「確認済み」状態を使いましょう。
顧客が不足または超過決済したらどうなりますか？
両方を明示的に処理します。ゲートウェイが不足を示すので差額を請求または返金でき、超過の場合は超過分を返金またはクレジットします。これらの分岐を先に作ることがデモと本番の差です。