PAY.JP CLI ガイド

概要

PAY.JP決済機能の開発・テストにはPAY.JP CLI（payjp-cli）を使用してください。 現在はWebhookイベントのローカル受信機能を提供。テストモード専用。

インストール確認

payjp-cli --version

インストールされていない場合：

# Windows (scoop)
scoop bucket add payjp https://github.com/payjp/scoop-bucket.git
scoop install payjp-cli

# macOS (Homebrew)
brew install payjp/tap/payjp-cli

# その他: GitHub Releasesからバイナリ取得
# https://github.com/payjp/payjp-cli/releases

基本コマンド

認証

# ログイン（ブラウザ認証、ペアリングコード表示）
payjp-cli login

# プロファイル指定（複数アカウント管理）
payjp-cli login --profile my-project

Webhook開発（主要機能）

# ローカルWebhookリスナー起動（ターミナル表示のみ）
payjp-cli listen

# ローカルサーバーへ転送
payjp-cli listen --forward-to http://localhost:3000/api/webhooks/payjp

# 特定イベントのみフィルタ
payjp-cli listen --events payment_flow.succeeded,setup_flow.succeeded --forward-to http://localhost:3000/api/webhooks/payjp

# プロファイル指定
payjp-cli listen --forward-to http://localhost:3000/api/webhooks/payjp --profile my-project

PAY.JP v2 API リソース

主要リソース

主要エンドポイント

# Payment Flow（決済）
POST   /v2/payment_flows           # 作成
GET    /v2/payment_flows/{id}      # 取得
POST   /v2/payment_flows/{id}/confirm  # 確認
POST   /v2/payment_flows/{id}/capture  # 確定
POST   /v2/payment_flows/{id}/cancel   # キャンセル

# Setup Flow（支払い方法登録）
POST   /v2/setup_flows             # 作成
GET    /v2/setup_flows/{id}        # 取得
POST   /v2/setup_flows/{id}/confirm    # 確認
POST   /v2/setup_flows/{id}/cancel     # キャンセル

# Payment Method
POST   /v2/payment_methods         # 作成（テストモードのみ）
GET    /v2/payment_methods         # 一覧
GET    /v2/payment_methods/{id}    # 取得
POST   /v2/payment_methods/{id}    # 更新
POST   /v2/payment_methods/{id}/attach  # 顧客に紐付け
POST   /v2/payment_methods/{id}/detach  # 顧客から削除

# Customer / Product / Price
POST   /v2/customers               # 顧客作成
GET    /v2/customers               # 一覧
POST   /v2/products                # 商品作成
POST   /v2/prices                  # 価格作成

認証方法

# HTTP Basic Auth（テストキー）
curl https://api.pay.jp/v2/payment_flows \
  -u sk_test_xxxxxxxxxxxxxxxxxxxx:

# HTTP Bearer Auth
curl https://api.pay.jp/v2/payment_flows \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxx"

キー形式:

Webhookイベント一覧

Payment Flow イベント

Setup Flow イベント

Payment Method イベント

Checkout イベント

Customer イベント

Refund / Catalog / Financial イベント

Webhook実装ガイド

ヘッダー構造

Content-Type: application/json; charset=utf-8
X-Payjp-Webhook-Token: whook_xxxxxxxxxxxxx

⚠️ Webhook実装の重要ポイント

• 応答: 10秒以内に 2xx を返すこと
• リトライ: 非2xx応答は3分間隔で最大3回リトライ
• 検証: X-Payjp-Webhook-Token ヘッダーのトークンをダッシュボードの値と照合
• Stripeとの違い: Stripeはsigning secret + HMAC署名検証だが、PAY.JPはトークン一致検証

Webhook開発フロー

1. payjp-cli listen --forward-to http://localhost:3000/api/webhooks/payjp 起動
2. ダッシュボードでWebhookトークンを確認し環境変数に設定
3. ローカルでイベント処理を実装・テスト

テストカード

成功するカード

海外発行カード

エラーを返すカード（支払い作成時）

エラーを返すカード（支払い時）

特定ステータスカード

対応決済方法

エラーコード

Stripe → PAY.JP 移行のマッピング

Usaconで将来Stripe併用/移行する際の参考：

チェックリスト

• テストモード（sk_test_）で実行しているか確認したか
• payjp-cli listen がローカルで起動中か
• Webhookトークン検証が実装されているか
• メタデータは20項目以内に収まっているか
• 10秒以内に2xx応答を返しているか
• 3Dセキュア（requires_action）ハンドリングが実装されているか

トラブルシューティング

関連スキル

• stripe-cli — Stripe決済操作（現在のUsacon決済基盤）
• usacon — 決済統合の実プロジェクト

参考

• PAY.JP v2 ドキュメント: https://docs.pay.jp/v2/guide
• PAY.JP v2 APIリファレンス: https://docs.pay.jp/v2/api
• PAY.JP CLI GitHub: https://github.com/payjp/payjp-cli
• PAY.JP CLI ガイド: https://docs.pay.jp/v2/guide/developers/payjp-cli

改訂履歴