結果通知（Webhook）

概要

結果通知は、決済やキャンセルなどの処理が行われた際に、APIレスポンスとは別に加盟店様システムへ知らせるための非同期通知機能です。
取引の最終結果を確実に把握するため、ご利用をお勧めしております。
なお、ご利用にあたって通知受信プログラムをご用意いただく必要があります。

対象接続方式

• プロトコルタイプ
• リンクタイプ Plus
• OpenAPIタイプ（Webhook通知）

こんな場面で役立ちます

• 決済完了後に自動で商品発送処理を開始したい
• リンクタイプ Plusで決済完了を把握したい
• コンビニ決済の入金完了を自動で検知したい
• d払いやPayPayなどでの決済完了を把握したい

接続方式ごとの主な違い

プロトコルタイプ / リンクタイプ Plus と OpenAPIタイプでは、一部仕様が異なります。

項目	プロトコルタイプ / リンクタイプ Plus	OpenAPIタイプ
URL通知先	管理画面で事前設定	APIパラメータmerchant.webhookUrlに設定
リクエスト形式	application/x-www-form-urlencoded	application/json
レスポンス形式	0 または 1	HTTPステータスコード（200番台）
通知対象	各決済手段のAPIリファレンス内「結果通知」を参照	通知の対象を参照

注意

取引の登録時に使用した接続方式に応じて通知方式が決定されます。
例えば、プロトコルタイプで取引登録を行った取引に対してOpenAPIタイプで処理を行った場合、プロトコルタイプの結果通知仕様に則り通知されます。

利用の流れ

結果通知を受信するには、加盟店様側で受信用プログラムと設定が必要です。

1. 結果通知の準備

結果通知を利用するには、事前準備が必要です。

受信プログラムの実装

結果通知を受信するプログラムを実装します。
リクエスト/レスポンス仕様をご参照ください。

通知先の設定

プロトコルタイプ / リンクタイプ Plus

管理画面で結果通知を有効化し、必要な設定を行います。

1. 結果通知の有効化：管理画面で「結果通知」を有効にする
2. 通知先URLの設定：結果通知を受信するURLを登録する

OpenAPIタイプ

APIリクエスト時にmerchant.webhookUrlパラメータを指定します。

ポイント

管理画面で設定した有効／無効と通知先URLは無視されます

2. 通知内容の確認

利用中の決済手段ごとに通知内容が異なります。

プロトコルタイプ / リンクタイプ Plus

各決済手段のAPIリファレンス内「結果通知」セクションを参照してください。

ポイント

初期設定は全ての取引状態が通知対象となっているため、結果通知送信ステータス設定より結果通知を受信したい取引状態のみ設定することを推奨します

OpenAPIタイプ

通知対象を参照してください。

3. 処理フローの理解

結果通知の送信タイミングと処理の流れを確認します。

• API実行時の通知：APIの処理結果が確定した際に送信
• 非同期処理時の通知：入金完了、期限切れなどのタイミングで送信

ポイント

• APIレスポンスの成功／失敗と、結果通知の成否は別に扱われます
• 結果通知は通信状態などにより届かないことがあるため、取引照会APIとの併用を推奨します

4. 結果通知失敗時の動作

結果通知に失敗した場合の動作を確認します。

再送処理

受信失敗とみなされた場合、最大5回まで再送されます。
詳細は再送処理を参照してください。

エラーレポートメール

初回の結果通知に失敗した場合にメールで通知されます。

• 送信対象：初回失敗時のみ(再送失敗時は送信されません)
• メール内容：失敗した取引の情報・応答値・エラー内容

詳細はエラーレポートメールを参照してください。

通知の対象

OpenAPIタイプのみ

このセクションはOpenAPIタイプのWebhook通知の対象を示します。
プロトコルタイプ / リンクタイプ Plusの場合は、各決済手段のAPIリファレンスを参照してください。

Webhook通知の対象となる処理は以下のとおりです。

対象Webhook	ケース	タイミング
現金払い支払い完了通知	コンビニ、バーチャル口座でお客様が入金	数秒～2時間程度 ※事業者に依存します
Amazon Pay V2キャンセル結果通知	返金が確定した場合	1時間～3時間 ※事業者に依存します
Pay払い決済結果通知	決済完了時	リアルタイム
都度支払い（フロントエンド方式）決済結果通知	決済完了時	リアルタイム
アトカラ与信結果通知	決済完了時	※保留となった場合数日かかるケースもあります
Pay払い利用承諾通知	決済完了時	リアルタイム

通知の設定・確認

管理画面で以下の機能を提供しています。必要に応じてご利用ください。

設定の変更

機能	使用場面	参照先
再送リトライ間隔の変更	再送を早めたい／遅くしたい場合	管理画面
受信対象のカスタム	特定の状態のみ通知が受け取りたい場合	管理画面
SNI設定の切り替え	SSL証明書エラーが発生する場合 ※OpenAPIタイプはこの設定に関わらず常にSNI有効となります	管理画面
結果通知の一時停止	サーバーメンテナンス中に通知を停止したい	管理画面

メンテナンス時の推奨手順

1. 管理画面で一時停止時間を設定
2. メンテナンスを実施
3. 設定した終了時刻に自動で再開
4. 停止中の通知は再開後にまとめて送信されます

履歴の確認

機能	使用場面	参照先
結果通知履歴の確認	通知が届いたか管理画面で確認したい	管理画面

以下の通知結果は管理画面から確認できません。

• カード登録などの会員情報に関する通知
• 口座振替のオンライン口座登録の通知
• 口座直結決済の口座登録の通知

注意事項

結果通知を運用する際の重要事項です。

通知タイミング

プロトコルタイプ / リンクタイプ Plus

コンビニ決済、Pay-easy、バーチャル口座における「PAYSUCCESS：決済完了」の結果通知は、一般的にお客様が入金してから数秒から2時間程度で通知します。

OpenAPIタイプ

現金払い支払い完了通知は、一般的にお客様が入金してから数秒から2時間程度で通知します。

備考

各決済事業者から当サービスへ通知されるタイミングに依存しますので、上記タイムラグを当サービスにて保証するものではありません。

順序性

プロトコルタイプ / リンクタイプ Plus のみ

このセクションはプロトコルタイプ / リンクタイプ Plusに適用されます。

APIレスポンスとは別に非同期で送信されるため、順序性の保証はありません。

また、履歴単位での通知となるために加盟店様の受信状況によっては、履歴とは異なる順序で受信となる可能性もあります。
そのため、加盟店様システムでは必ず取引IDや処理日時を確認してください。

例）取引履歴が以下の場合(実売上のみ2回目で正常応答)

取引履歴：

1. 仮売上
2. 実売上
3. 取消

結果通知順序：

1. 仮売上(正常応答) ⇒ 2. 実売上(異常応答) ⇒ 3. 取消(正常応答) ⇒ 2. 実売上(正常応答)

SSL証明書

決済結果をhttps通信で受け取る場合は、第三者が発行したSSLサーバ証明書が必要です。
詳細はSSL証明書を参照してください。

プロトコルタイプ / リンクタイプ Plus

加盟店様が利用されているSSL証明書のSNI対応／非対応により、当サービスからの結果通知が受け取れない場合があります。
その際は管理画面のSNI設定よりSNI有効／無効を切り替えることで解消する可能性があります。

OpenAPIタイプ

SNI設定について

OpenAPIタイプのWebhookでは、SNI設定は常に有効です。
管理画面でのSNI設定切り替えは適用されません。

一時停止について

10秒以内に応答なしが連続した場合、一時的に送信を停止することがあります。

• 一定時間経過後、リトライを行い10秒以内に応答があることを確認できたら、結果通知の送信を再開
• 停止時／再開時にメール通知　内容は一時停止通知メールをご参照ください。
• 停止期間中の通知は、再開後にまとめて送信

注意

通知停止が発生した場合、復旧後に大量の通知が一度に送信される可能性があります。受信側の処理能力を考慮してください。