暗号資産決済の連携テスト：公開前のチェックリスト

暗号資産決済の連携テストで証明すべきなのは、決済ページが開くことではありません。決済の検証後に限り、正しい注文が一度だけ履行されることです。 通知の配信テスト、アプリケーションの注文状態テスト、承認を得た実際の資金による受入検証は分けて行ってください。それぞれで確認する内容が異なります。

このチェックリストは、決済フローの公開を準備する開発者と販売者向けです。選択した資産とネットワークが実際に利用できる場合のUSDCやUSDT決済も対象です。推奨するテスト手順であり、Yolfiがあなたのアプリケーションでこれらのテストに合格したことや、完全なテストネット決済フローを提供していることを報告するものではありません。

実行するテストの種類を把握する

模擬的な決済通知は、ブロックチェーン上の送金ではありません。テストネットの送金は、本番ネットワークでの決済ではありません。ブラウザーのリダイレクト成功も、そのいずれをも意味しません。

Ethereumのネットワークガイドでは、アカウント残高や取引履歴は独立したネットワーク間で引き継がれないと説明しています。アドレスが同じに見えても、テストネットの資金をメインネットで使えるわけではありません。一般的なウォレットのテストがその決済サービスにも当てはまると考えず、提供元の最新ドキュメントを確認してください。

まずテスト範囲を書面で定める

何かを送信する前に、アプリケーション環境、提供元のアカウント、受信先URL、署名シークレットの保管場所、注文ID、意図する副作用を記録します。模擬シナリオでは破棄できる顧客レコードを使い、実際の配送、有料アクセス権の付与、顧客へのメール送信を無効にしてください。

テスト用と本番用の設定を分離してください。署名シークレットを記事、スクリーンショット、課題管理票、チャット履歴にコピーしてはいけません。テストの証拠には使用したシークレットのバージョンを記し、値そのものは公開しないでください。テスト失敗の調査のために、購入者にウォレットのリカバリーフレーズや秘密鍵を求めてはいけません。

実際の資金を使う検証では、金額、手数料、送金先、担当者について明確な社内承認を得てください。事業者が管理するウォレットと、失っても許容できる金額を使います。古いスクリーンショット、自動生成された通貨ページ、非公式のテスト手順に載っていたという理由だけで、そのアドレスやネットワークに送金してはいけません。

注文金額をサーバーが管理することを証明する

Yolfi API決済では、販売者のサーバーが最終金額と通貨を指定してCheckout Session（決済セッション）を作成します。購入者が対応するネットワークとトークンを選ぶと、そのセッションからInvoice（決済請求書）が作成されます。繰り返し使えるPaylinkは、サーバーで価格を決定する動的な注文とは用途が異なります。

内容が変わるカートでは、資金移動のテストより先に、自社サーバーの価格計算とセッションの関連付けを検証してください。

• ブラウザーから送信する合計額を変更し、正式な注文価格を上書きできないことを確認します。
• 別の顧客の注文参照情報を使い、アプリケーションが権限のないアクセスを拒否することを確認します。
• 決済フローを再読み込み、または開き直し、繰り返しの試行が意図した注文に関連付けられたままであることを確認します。
• セッション作成後にカートを変更し、古い決済試行を置き換える、または拒否する明確なルールがあることを確認します。

これらはアプリケーションの受入基準であり、提供元のエンドポイントがあらゆるリクエストを拒否するという主張ではありません。サーバーの注文参照情報と、返されたセッション参照情報を一緒に保管してください。APIフィールドを作り上げたり、ブラウザーから操作できる識別子が所有権を証明すると考えたりしてはいけません。

実際の売上を作らずにテストWebhookを送る

現在のYolfi Webhookドキュメントでは、本番イベントと同じ配信経路、アダプター、署名ヘッダーを使って管理画面から送るテストイベントを説明しています。ペイロードにはlivemode: falseと、evt_test_で始まるイベントIDが含まれます。このテストでは、請求書、決済イベント、サブスクリプション、顧客レコードは作成されません。

このイベントで確認するのは配信とペイロード処理であり、資金の決済ではありません。受信先が200 OKを返していても、誤ってアクセス権を付与していたり、通知を黙って破棄していたりする可能性があります。配信結果だけでなく、その結果生じたアプリケーションの状態も確認してください。

組織のAPIキーではなく、ドキュメントに記載された手順とエンドポイント固有の署名シークレットを使って署名を検証してください。本番の注文履行処理がテストイベントを支払済み注文として扱えないことを確認します。隔離されたテスト環境でテストデータを使って注文履行を試す場合は、破棄できるレコードを使い、本番とは別に確認してください。

Yolfiは公開HTTPまたはHTTPSの送信先を必要とし、リダイレクトには追従しません。ローカル開発では公開HTTPSトンネルを使うことをドキュメントで推奨しています。最終的な受信先URLを正確に確認してください。別のパスやローカル専用アドレスへのリクエストが成功しても、提供元からの配信を証明したことにはなりません。

正常系の画像だけでなく障害マトリクスを使う

提供元のテスト送信機能で再現できないケースは、自社の隔離されたテスト環境で、管理されたテストデータを使って実行してください。アプリケーションテストであることを明記し、作り上げた提供元のイベントを実際の決済の証拠として示してはいけません。

Yolfiではinvoice.createdは開始を示し、ドキュメントで注文履行の契機とされているのはpayment.confirmedです。最初の通知が届いただけで注文を支払済みにしないでください。Webhookの冪等性ガイドでは永続的な重複排除を説明しています。このチェックリストは、実装が実際にそのとおり動く証拠を集めることに重点を置いています。

復旧は意図的にテストしてください。イベントを保存する前に成功を返す処理は、クラッシュすると作業を失う可能性があります。完了を記録する前に商品を提供する処理は、再試行後に提供を繰り返す可能性があります。永続性のある処理設計を選び、中断が起きる箇所を試してください。リクエストが1回成功すれば信頼性を証明できるとは考えないでください。

購入者向けの案内と未解決決済の対応経路を確認する

実際の決済フローをスマートフォンとデスクトップで開いてください。送金前に、表示金額、選択した資産、ネットワーク、送金先、有効期限の情報が理解できるか確認します。コピー機能とQRコードの読み取りをテストし、QRコードだけですべての送金用ウォレットが自動的に正しく設定されるとは考えないでください。

エラーメッセージを試すためだけに、非対応トークンを送ったり、意図的に間違ったネットワークを使ったり、取り消せない送金を行ったりしてはいけません。こうした問い合わせ対応は、管理されたレコードで練習してください。誤ったネットワークへの送金防止ガイドでは、購入者向けに用意すべき確認事項を説明しています。

未払いや期限切れの注文を想定して対応を練習してください。購入者に伝えるべきなのは、根拠のない資金回収の約束ではなく、明確な状態と安全な次の手順です。期限切れ請求書への対応手順を使い、再度の支払いを求める前に調べるべき内容を決めてください。最初の支払いが不明確だからといって、自動的に2回目の支払いを求めてはいけません。

承認を得た場合は実際の決済による受入検証を1件記録する

選択した本番の資産とネットワークが実際のフローで利用可能だと確認してから進めてください。必要なネットワーク手数料を考慮し、送金先は事業者の管理下に置いてください。提供元のテストWebhookが成功しても、未検証の経路に実際の資金を送る根拠にはなりません。

注文と決済の参照情報、実際の資産とネットワーク、金額、観測した確認状況、受取ウォレットの証拠、結果としての注文履行状態を記録します。あらゆる状況に共通する確認回数や決済完了時間を約束しないでください。ウォレットのスクリーンショットだけでなく、実際に観測した結果を確認してください。

次に、その決済を注文と領収書の記録に照合します。照合チェックリストは、入金、注文への充当額、手数料を区別するのに役立ちます。受入検証の支払いを返金する予定なら、返金を別途承認し、検証してください。自動的に取り消されるとは考えないでください。

検証に合格して分かるのは、ある時点で観測した1つの経路の結果だけです。決済ロジック、受信先のデプロイ、シークレット、対応経路が変わったら、関連する受入テストを繰り返してください。USDC決済が1件成功したことを、USDTのすべてのネットワークが動作する証拠にしてはいけません。

リリースの検証記録を保管する

テストしたアプリケーションのバージョン、環境、シナリオ、期待する結果、実際の結果、未解決の問題を簡潔な報告書に残してください。顧客識別子やウォレットの全履歴を公開するのではなく、非公開ログや注文記録にリンクしてください。

テストイベントで本番注文が履行される、重複イベントで二重提供される、不正な署名で状態が変わる、確認済み決済を安全に照合できない場合は、公開を止めてください。未解決項目ごとに責任者を決めます。配信成功を示す緑の表示は、こうした業務上の結果の代わりにはなりません。

よくある質問

YolfiのテストWebhookは暗号資産を移動させますか？

いいえ。ドキュメントに記載されたテストは、請求書や決済記録を作らず、配信とペイロード処理を検証します。実際のブロックチェーン決済の成功を証明するものではありません。

テストネット決済と決済サービスのサンドボックスは同じですか？

いいえ。テストネットは独立したブロックチェーンネットワークです。提供元のサンドボックスは、そのサービス専用の環境です。必要とする特定のモードに提供元が対応しているかを確認してください。この記事はYolfiがテストネット決済を提供することを示すものではありません。

決済ページのリダイレクトが成功したら公開してよいですか？

その証拠だけでは不十分です。サーバー側の決済処理、注文の照合、重複防止、障害復旧を検証してください。購入者は復帰ページが開く前にブラウザーを閉じる可能性があります。

すべての障害を実際の送金でテストする必要がありますか？

いいえ。障害処理には、隔離したアプリケーションテストと、提供元が文書化したシミュレーションを使ってください。実際の決済による受入検証には承認と対応経路の確認が必要です。意図的に間違ったネットワークへ送金することではありません。

結論：公開前に業務上の結果を検証する

まず範囲を明確にし、サーバー側の注文処理を証明し、模擬イベントと検証済みの資金を区別してください。適した固定価格の商品やサービスにはYolfi決済リンクを、動的な注文にはドキュメントに記載されたAPIフローを使います。そのうえで、注文履行を制御しているのがブラウザーのリダイレクトではなく、決済処理であるという証拠を残してください。