「決済 API を使えば自社 EC に最短で組み込めると聞いたが、実装工数や認証方式が分からない」

「PCI DSS の対象範囲を最小化するトークン化の流れを、コードレベルで具体的に把握したい」

「サンドボックス検証や Webhook の再送設計まで、本番運用に耐える設計指針が欲しい」

決済 API 連携 は、自社の EC サイトやアプリから決済代行会社 (PSP) の REST API を呼び出してカード決済を完結させる方式です。リダイレクト型と比較して画面遷移が発生しないため、コンバージョン率が高く、UI/UX を自社デザインに統一できます。一方で、認証・トークン化・冪等性・Webhook 設計など、API ならではの実装ポイントを押さえる必要があります。本記事では、決済 API 連携の方式比較、REST API の実装手順、認証とセキュリティ、サンドボックス検証、本番リリース後の運用まで 2026 年最新情報で解説します。

決済 API 連携とは？3 つの接続方式の違い

EC サイトに決済機能を組み込む方式は大きく分けて 3 つあります。

1. リダイレクト型 (リンク型)

顧客を PSP の決済画面に遷移させて決済を完了させる方式。実装が最も簡単で、自社サーバーがカード情報を扱わないため PCI DSS の範囲もほぼゼロです。ただし画面遷移によって離脱率が上がる傾向があります。

2. API 型 (REST API)

自社サイト内で決済を完結させ、裏側で PSP の API を呼び出す方式。UI/UX を完全に自社管理できるため、購入完了率が向上します。本記事の主題です。

3. SDK / JS ライブラリ組み込み型

PSP が提供する JavaScript SDK (Stripe.js、PAY.JP Checkout 等) をフロントに埋め込み、カード情報をクライアントから直接 PSP に送信。サーバー側にはトークンのみが返るハイブリッド方式で、PCI DSS SAQ A 範囲に収まる構成が主流です。

2026 年現在、新規 EC サイトの主流は JS SDK でトークン化 + サーバー API で決済確定 の組み合わせです。詳しくは トークン決済の仕組み をご覧ください。

決済 API 連携のメリットとデメリット

メリット

• 離脱率の低減: 決済画面に遷移しないため、カゴ落ちを最小化できる
• UI/UX の自由度: 自社デザインで決済フォームを設計可能
• 豊富な機能: リカーリング・分割・後払いなど、PSP の機能をそのまま自社サービスに統合
• マルチチャネル対応: Web・iOS・Android の各クライアントから同じ API を呼び出せる

デメリットと対策

• 実装工数: リダイレクト型より開発期間が 2〜4 倍。ただし SDK 利用で大幅に短縮可能
• 仕様変更への追従: PSP の API バージョンアップに合わせた改修が必要。バージョン pinning と Changelog 購読で対応
• 障害時の影響: PSP の API 障害がそのまま決済停止に直結。SLA 99.99% 以上の PSP を選定し、フォールバック決済手段を併設

REST API の実装パターンと認証

主要 PSP の API は REST/JSON ベースで設計されており、HTTP メソッドとリソース指向の構造が共通しています。

典型的なエンドポイント構成

• POST /v1/tokens — カード情報をトークン化
• POST /v1/charges — 決済 (オーソリ + キャプチャ) を実行
• POST /v1/customers — 顧客とトークンを紐付けて保存
• POST /v1/subscriptions — リカーリング決済を作成
• POST /v1/refunds — 返金処理
• GET /v1/charges/:id — 決済状態の取得

認証方式

多くの PSP は以下のいずれかを採用しています。

• Bearer トークン (シークレット API キー): Authorization: Bearer sk_live_xxx ヘッダーに API キーを設定。サーバー側からのみ呼び出すこと
• HMAC 署名: リクエストボディと秘密鍵から生成した署名をヘッダーに付与。改ざん検知に有効で、Webhook 受信時は必ず実装
• Basic 認証: 旧型の PSP で残存。API キーを Base64 エンコードして送信

冪等性キー (Idempotency Key)

ネットワークタイムアウト時に同じリクエストを再送しても二重課金しないように、Idempotency-Key ヘッダーに UUID を付与します。PSP 側で 24 時間程度キャッシュされ、同じキーのリクエストは初回のレスポンスを返してくれます。決済 API では事実上必須の機能です。

Webhook で非同期イベントを受信

3-D セキュアの認証完了、リカーリングの定期課金結果、チャージバック発生など、非同期で発生するイベントは Webhook (HTTPS POST) で通知されます。実装ポイントは以下です。

• HMAC 署名で送信元検証
• イベント ID で重複排除 (同じ Webhook が複数回届く前提で設計)
• 5xx を返すと PSP が指数バックオフで再送するため、200 を返してから非同期処理

カード情報のトークン化フロー

API 型決済の中核はトークン化です。事業者サーバーがカード番号 (PAN) を一切受け取らない構成にすることで、PCI DSS の対応範囲を SAQ A 相当 (年次自己問診のみ) に収められます。

典型的なフロー

1. 顧客がブラウザでカード情報を入力
2. PSP の JS SDK がカード情報を直接 PSP サーバーに送信 (事業者サーバーを経由しない)
3. PSP がトークン (例: tok_xxx) を返却
4. 事業者のフロントエンドが、注文情報と一緒にトークンを自社サーバーへ送信
5. 自社サーバーが POST /v1/charges でトークンを使って決済を実行
6. PSP が決済結果 (成功/失敗) を同期で返却し、確定処理

このフローでは、事業者サーバーは「トークン」と「金額」だけを扱うため、漏洩リスクが極小化されます。決済ゲートウェイ の役割と合わせて理解すると、設計の全体像が掴めます。

実装の 5 ステップと工数目安

STEP 1: PSP 選定と API 仕様の精査 (1〜2 週間)

必要決済手段、月次取扱規模、開発リソース、リカーリングや後払いの要否を整理。候補 PSP のサンドボックスでハロー決済を試し、ドキュメントの整備度を比較します。

STEP 2: 加盟店審査と API キー発行 (2〜4 週間)

カードブランドの加盟店審査。販売商品やサイト構成によっては追加書類が必要。審査と並行してテスト用 API キーで開発を開始できます。

STEP 3: フロント実装 (1〜2 週間)

JS SDK を埋め込み、カード入力フォーム、トークン取得、エラー表示、3-D セキュア認証用の iframe / ポップアップを実装。スマホでの入力体験 (数字キーボード強制等) も検証。

STEP 4: バックエンド実装 (2〜3 週間)

決済確定 API 呼び出し、Idempotency Key 管理、Webhook 受信エンドポイント、注文 DB との整合性担保、リトライ・補償トランザクションの設計。

STEP 5: サンドボックス検証と本番リリース (2〜3 週間)

サンドボックスで正常系・異常系・3-D セキュア・部分返金・全額返金・リカーリングなど全パターンを検証。本番リリース後 2 週間は決済成功率と Webhook 受信率を毎日モニタリングします。

合計で 2〜3 ヶ月 が一般的な目安。SDK 充実度と既存サイト構成によって前後します。

失敗時の設計指針

エラー分類とリトライ戦略

• 4xx (クライアントエラー): カード情報不正・限度額超過など。リトライ禁止。ユーザーに再入力を促す
• 5xx (PSP 側エラー): 一時的な障害。指数バックオフで最大 3 回リトライ。同じ Idempotency Key を再利用
• タイムアウト: 決済が成功したか不明な状態。GET で状態確認 してから再送判断

サンドボックスで必ず検証すべきパターン

• テストカード番号で 200 / 4xx / 5xx の挙動
• 3-D セキュア認証の成功・失敗・タイムアウト
• Webhook 受信の重複・順序逆転・遅延
• 部分返金・複数回返金
• リカーリング初回成功 / 2 回目以降の失敗 (カード期限切れ等)

本番リリース後のモニタリング指標

• 決済成功率 (オーソリ通過率)
• 3-D セキュア認証完了率
• Webhook 受信遅延 (P95)
• API レスポンスタイム (P95/P99)
• カゴ落ち率 (決済画面到達後の離脱率)

PSP 選定の 5 つの観点

API 連携で重要な選定軸は、料金以外にも多数あります。決済代行サービスの比較 もあわせてご参照ください。

1. API ドキュメントの品質: サンプルコード (curl/Node/Ruby/PHP/Python)、エラーコード一覧、Changelog の整備度
2. SDK の提供状況: JS SDK、iOS/Android SDK、サーバーサイド SDK の言語カバレッジ
3. サンドボックスの利便性: 即時アカウント発行、テストカード網羅性、Webhook テスト機能
4. SLA と障害情報の透明性: ステータスページの有無、障害履歴の公開、SLA 99.99% 以上
5. サポート体制: 日本語技術サポート、開発者コミュニティ、レスポンス時間 SLA

選定の早い段階で複数 PSP のサンドボックスを実際に触り、Hello World 決済までの所要時間を計測することをおすすめします。PSP (決済サービスプロバイダ) とは もご参照ください。

よくある質問

Q1. 決済 API の実装は最短で何日くらいで完了しますか？

SDK が充実した PSP を使い、シンプルな単発決済のみであれば 1〜2 週間 で本番リリース可能なケースもあります。ただし加盟店審査に 2〜4 週間かかるため、トータルでは 1 ヶ月以上を見込むのが現実的です。

Q2. 自社で PCI DSS 認証を取得する必要はありますか？

JS SDK 経由でトークン化する構成 (SAQ A 相当) であれば、自社で PCI DSS 認証を取得する必要は基本的にありません。サーバー側でカード情報を一度でも受け取る設計にすると SAQ D 相当となり、対応コストが大幅に増えます。

Q3. Webhook が届かない場合のフォールバックは？

Webhook は届かないことを前提に設計してください。決済結果は同期 API レスポンスで判定し、Webhook は補助的な通知と位置付けるのが鉄則です。リカーリングなど Webhook 必須のケースでは、定期的な GET ポーリングを併用します。

Q4. 既存サイトでリダイレクト型から API 型に移行できますか？

可能です。ただし、既存顧客のカード情報を新 PSP に移管する場合は PSP 間でのトークン移行プロジェクトが必要です。多くの PSP がカード情報移行サービスを提供しており、契約前に対応可否と費用を確認してください。

Q5. テスト環境のカード情報はどう用意しますか？

各 PSP がテストカード番号 (例: 4242 4242 4242 4242 が正常決済) を公開しています。3-D セキュア成功用、失敗用、限度額エラー用など、ケース別の番号も用意されているため、ドキュメントを参照してテストケースを網羅してください。

まとめ｜決済 API 連携は「設計」で 9 割決まる

決済 API 連携は単なる実装作業ではなく、認証・冪等性・Webhook・エラー設計・モニタリングまで含めた総合的な設計が成功の鍵です。本記事のポイント:

• 新規構築は JS SDK でトークン化 + サーバー API で決済確定 が主流
• Idempotency Key と Webhook 重複排除は 事実上必須
• サンドボックスで 正常系より異常系を優先検証
• PSP 選定は料金より ドキュメント品質と SLA を重視
• 本番リリース後 2 週間は決済成功率と Webhook 遅延を毎日確認

JPCC では、REST API ベースの決済ゲートウェイと、SDK・サンドボックス・日本語技術サポートを揃えた API 連携サービスをご提供しています。