メインコンテンツまでスキップ
Markdownをコピー

推奨する実装パターン

概要​

OpenAPIタイプのAPIを利用した決済システムを構築する際に推奨する実装パターンをまとめています。

トピック内容
リダイレクト後の取引照会コールバックパラメータのaccessIdを用いた取引照会による決済ステータス確認
Pay払い決済におけるWebhook活用取引照会とWebhookの2系統による確実なステータス把握
APIバージョンの指定X-MP-Versionヘッダーによる意図せぬ仕様変更の防止
API呼び出しのリトライ429/500/502/503エラー時の指数バックオフによるリトライ
重要

リダイレクトを伴う決済フローでは、コールバックURLへの到達だけでは決済が完了したかどうか判断できません。 必ずコールバックパラメータのaccessIdを用いて取引照会で決済ステータスを確認してください。

リダイレクト後の取引照会​

推奨する理由​

リダイレクトを伴う決済フローでは、コールバックURLに到達しただけでは決済の成否を判断できません。

  • コールバックURLへの到達は決済成功を意味しない
  • コールバック時に渡されるパラメータに決済結果は含まれない
  • ネットワーク障害やブラウザ閉じ等でリダイレクト自体が失敗する可能性がある
  • 決済事業者側の処理が非同期で完了するケースがある

そのため、コールバックURLにリクエストが到達したら、必ずコールバックパラメータに含まれるaccessIdを用いて照会（/order/inquiry）APIを実行し、決済ステータスを確認してください。

コールバックパラメータ​

本サービスでは、コールバック時にクエリパラメータpとしてBase64URLエンコードされた以下のJSON文字列を付与します。

{
  "accessId": "<orderReference.accessId>",  // 取引ID — 取引照会のキーとして使用
  "event": "WALLET_CHARGE_FINISHED",        // イベントタイプ — 処理分岐に使用
  "csrfToken": "<merchant.csrfToken>"       // CSRF対策用トークン — 正当性確認に使用
}

詳細はリダイレクトとコールバックを参照してください。

推奨シーケンス​

以下は、リダイレクトを伴う決済（Pay払い等）における推奨する実装パターンです。

備考

このシーケンス図はコールバック受信後の処理にフォーカスして簡略化しています。決済フローの全体像（当サービスによるPay払い事業者への確定処理等）はPay払い処理フローを参照してください。

実装のポイント​

ポイント説明
パラメータpのデコードコールバックURLのクエリパラメータpをBase64URLデコードし、accessId・event・csrfTokenを取得する
CSRF対策csrfTokenが取引リクエスト時に設定した値と一致することを確認する
accessIdで取引照会取得したaccessIdを用いて照会（/order/inquiry）APIを実行する
eventによる処理分岐イベントタイプに応じて、取引照会による成否判断または3Dセキュア後処理など適切な処理を実施する
ステータスによる画面分岐取引照会レスポンスの決済ステータスに応じて、成功画面・失敗画面を出し分ける

Pay払い決済におけるWebhook活用​

推奨する理由​

Pay払い系の決済手段（PayPay、楽天ペイ、d払い等）では、決済完了時に結果通知（Webhook）が送信されます。

Webhookを活用すべき理由は以下のとおりです。

  • リダイレクト失敗への備え — お客様がブラウザを閉じたり、ネットワーク障害が発生した場合、コールバックURLに到達しない可能性がある。Webhookはサーバー間通信のため、この影響を受けない
  • ステータスの整合性確保 — Webhook受信時にマルペイ側の決済ステータスと加盟店様側のステータスを突合することで、不整合を検知・解消できる
  • 非同期処理の結果把握 — 決済事業者側の処理が非同期で完了するケースでも、Webhookで最終結果を受け取れる

推奨シーケンス​

取引照会（リダイレクト経由）とWebhook受信の2系統を並行して処理する推奨パターンです。

実装のポイント​

ポイント説明
2系統の並行処理リダイレクト経由の取引照会とWebhook受信の両方を実装し、どちらが先に到達しても正しく処理できるようにする
ステータスの突合Webhook受信時に、加盟店様DBの決済ステータスとWebhookで通知されたステータスを比較し、不整合があれば照会（/order/inquiry）で最新状態を確認する
冪等性の確保同じ取引に対して取引照会とWebhookの両方でステータス更新が行われる可能性があるため、二重処理を防ぐ実装にする
Webhook受信の実装Webhook受信プログラムの実装方法は結果通知（Webhook）開発ガイドを参照

APIバージョンの指定​

OpenAPIタイプのAPIでは、リクエストヘッダー X-MP-Version でAPIバージョンを指定できます。

省略時や日付の様式が正しくない場合は最新のバージョンとして扱われます。バージョンを指定しない場合、APIの仕様変更が行われた際に意図せぬ影響を受ける可能性があるため、明示的にバージョンを指定することを推奨します。

現在指定可能なバージョン:

バージョン説明
2023-06現行バージョン

設定例​

リクエストヘッダーに以下を追加してください。

X-MP-Version: 2023-06

API呼び出しのリトライ​

照会（/order/inquiry）API、確定（/order/capture）API、キャンセル（/order/cancel）APIなどのAPI呼び出しにおいて、以下のHTTPステータスコードが返却される場合があります。

ステータスコード説明
429リクエスト過多（レートリミット超過）
500サーバー内部エラー
502Bad Gateway
503サービス一時利用不可

これらのエラーは一時的な障害やリクエスト集中に起因することが多く、時間をおいてリトライすれば成功する可能性があります。ただし、短時間で繰り返しリトライしても状況は改善しないため、指数バックオフによるリトライを推奨します。

指数バックオフの例​

リトライ回数待機時間（目安）
1回目1秒
2回目2秒
3回目4秒
4回目8秒
5回目16秒
ポイント
  • リトライ間隔は2のべき乗で増加させ、最大リトライ回数の上限を設けてください

関連ページ​

LLMですか？llms.txt・llms-apis.txtに各ページの概要とリンクをまとめています。回答生成に活用してください。