コンテンツにスキップ

このページは英語のページを機械翻訳したものです。内容は英語のページが正です。 英語のページを読む

PAY.JP によるサポーターの支払い

payments = payjp にすると、ローカルユーザーはこのサーバーの支払いページで月額または年額のプランを購読でき、支払いの状態の変化に応じてプランのロールが付与・解除されます。チップを有効にすると、ユーザーは PAY.JP のホスト型ページで一回払いのチップも支払えます(チップを参照してください)。 デプロイ時の鍵は設定リファレンスで説明しています。制度全体(プラン、ロール、メンバーの一覧)については supporters.md を参照してください。 制度を有効にしてプランを作るのは、管理画面での管理者の操作です。この設定は、サーバーが PAY.JP とやり取りできるようにするだけです。

1 つのサーバーで使えるプロバイダーは 1 つだけです。Stripe から PAY.JP へ(またはその逆へ)切り替えるときは、既存の購読者に新しいプロバイダーで購読し直してもらってください。

PAY.JP には API v1 と v2 があります。v2 にはまだ定期課金の API がないため、サーバーは API v1 の定期課金(Plan と Subscription)を使います。v1 にはホスト型の支払いページも顧客ポータルもないので、このサーバーがその代わりのページを配信します。 チップは API v2 の一回払いで、API v2 にはホスト型の支払いページがあります。チップを参照してください。PAY.JP は、同じ鍵で 1 つのアカウントに両方のバージョンを使うことを認めています。

サブスクリプションの仕組みでは、支払いページ、Webhook、照合、プランのロール、収入がどうつながるかを図で示しています。

  • プラン: サーバーは価格ごとに、ID が my_<plan ID>_<month|year>_<amount>(metadata.my_plan_id)の Plan を作ります。PAY.JP の Plan は金額を変えられないため、金額を変えると新しい Plan が作られ、古い Plan は削除されずに metadata.my_archived=1 が付きます。古い Plan のサブスクリプションは、その金額で更新されます。 PAY.JP の管理画面でこれらの Plan を編集・削除しないでください。通貨は日本円だけで、金額は 50 円から 9,999,999 円までです。
  • 購読: サーバーはユーザーのブラウザーを自身の支払いページ(/payments/pages/payjp/checkout)に送ります。このページは payjp.js(PAY.JP の iframe)のカード入力欄を表示し、トークンを作るときに 3-D セキュア認証を行います(iframe 型)。 サーバーは 3-D セキュアが完了したトークン(three_d_secure_status が verified または attempted)だけを受け付け、そのカードを顧客の既定のカードとして登録し(初回は ID my_<the server's subscription ID> で)、metadata.my_subscription_id にサーバーのサブスクリプション ID を入れてサブスクリプションを作ります。最初の課金はサブスクリプションの作成時に行われます。 ページの URL は有効期間が短く、サーバーが署名した状態を持ちます(作成から 1〜2 時間有効です)。 ページを離れてやり直したユーザーは、同じプランでも別のプランでも、いま求めたプランの新しい URL を受け取ります。以前の URL も期限が切れるまでは使え、最初に支払われたページが唯一のサブスクリプションを作ります。ほかのページはそのサブスクリプションに進みます。以前のページがすでに支払われていれば、ユーザーは戻り先の画面に進み、新しい URL は受け取りません。 署名した URL は取り消せないため、保留中のサブスクリプションが閉じたあと(プランの終了、アカウントの削除)もページは支払える状態のままです。そこで支払っても何も得られません。サーバーはそのサブスクリプションを削除し、その課金を全額返金します(PAY.JP は売上から 180 日間返金を受け付けます)。 API v1 は冪等キーを受け付けないので、ページからの 1 回の送信がサブスクリプションを作っているあいだ、サーバーはデータベースで決済を処理中として印を付けます。2 回目の送信(ダブルクリック、別のタブ、同じロードバランサーの背後にある別のサーバープロセス)は最大 30 秒待ち、最初の送信が作ったサブスクリプションに進みます。印を持っていたプロセスが止まった場合、印は 5 分後に期限切れになります。
  • カードと支払い履歴のページ(Stripe の顧客ポータルの代わり): 購読者は自分のサブスクリプションの画面から /payments/pages/payjp/portal を開き、カードを変えたり最近の支払いを確認したりできます(URL は 1 時間で期限切れになります)。フォームには最初から PAY.JP の顧客のメールアドレスが入っています。これは最初の支払いのときに入力したアドレスで、そのあとアカウントのアドレスを変えても反映されません。 カードを変えると、支払いの失敗で止まっていたサブスクリプションが再開し、すぐに課金されます。解約とプランの変更は、このサーバーのサブスクリプションの画面で行います。
  • 支払いの失敗: 更新の課金に失敗したサブスクリプションを、PAY.JP は一時停止(paused)し、再試行しません。サーバーは一時停止を支払いの遅れとして扱い、一時停止の時点から 7 日間の猶予期間はロールを保ちます。そのあいだに購読者がカードを変えればサブスクリプションは再開し、変えなければ 7 日後にロールが外されます(PAY.JP 側ではサブスクリプションは一時停止のままで、課金されません)。
  • プランの変更: アップグレードでは、現在の期間の残りについて差額を日割りで 1 回だけ課金し(50 円未満は課金しません)、プランを入れ替えて、期間の終わりに新しいプランの全額を課金します(期間の始まりは動きません)。差額の課金が拒否されると、プランは変わりません。 ダウングレードと、年額から月額への変更は、next_cycle_plan で期間の終わりに切り替わります。
  • 状態の読み直し: サーバーは Webhook を合図として扱い、PAY.JP の API からサブスクリプションとお金の動きを読み直して状態を決めます。 さらに、payments_reconcile_interval ごとの照合で、イベントの一覧、お金の動き、すべてのサブスクリプションの一巡を読み、サーバーが受け取り損ねた Webhook を補います。
  • 収入: サーバーは支払いごとに、総額、手数料(課金の fee_rate から計算し、1 円未満は切り捨て)、純額を記録します。返金とチャージバックでは、戻ってきた手数料をマイナスの手数料として記録します。 期間が締まって明細が発行されると、明細の手数料とサーバーの計算(サブスクリプションの課金と、その期間のチップの手数料)との差を手数料の動き(ID は明細の ID)として記録し、その期間の手数料の合計が明細と一致するようにします。 明細はアカウント全体の手数料を含むので、このサーバー専用の PAY.JP アカウントを使ってください。
  • 日付: 収入の日付は日本時間で数えます。

サーバーが送るリクエストは、API v1 と v2 を合わせて 1 秒あたり最大 20 件(テストモードでは 2 件)です。これは PAY.JP のレート制限(秘密鍵によるリクエストで、本番モードは 1 秒あたり 30 件、テストモードは 2 件)の範囲内です。429 が返ると、サーバーは 1 秒待ち、そのたびに待ち時間を倍にして、最大 3 回再試行します。 テストモードでは 1 回の照合に時間がかかります(1,000 リクエストの上限で約 8 分)。続きのジョブが引き継ぐので、対応は必要ありません。

チップ(supporters.mdを参照してください)は、サブスクリプションと同じ鍵と Webhook のトークンで、PAY.JP の API v2 を使います。PAY.JP は、チップを審査で承認しにくい商材に挙げています。アカウントでチップを受け付けてよいかどうかは、PAY.JP の審査と規約に照らして、PAY.JP との間で決めてください。

  • 支払い: サーバーは、1 つの金額、カードのみ、1 時間で期限切れになる Checkout Session(mode=payment)を作り、ユーザーを PAY.JP 上のそのページに送ります(pay.jp 上の https のページで、サーバーはそれ以外のアドレスを拒否します)。サーバーのチップの ID は、セッションの client_reference_id と、セッションとその PaymentFlow の metadata.my_tip_id に入ります。作成には Idempotency-Key を付けるので、再試行しても同じセッションが返ります。カード会社が求めたときは、PAY.JP がホスト型ページで 3-D セキュアを行います。 チップは、そのセッションが complete で、PaymentFlow が成功したときに支払われたことになります。ユーザーが別のチップを始めるとき、サーバーは開いているセッションを先に期限切れにします(POST /v2/checkout/sessions/{id}/expire)。そのあいだにユーザーが支払っていた場合は、その支払いが記録されます。
  • 収入: チップのお金は、アカウントの API v2 の支払いトランザクションから得ます。支払い(ID は PaymentFlow の ID)、返金、チャージバック、チャージバックの取り消しで、それぞれ PAY.JP が報告する手数料が付きます。返金とチャージバックでは、サブスクリプションと同様に、戻ってきた手数料をマイナスの手数料として記録します。
  • 異議申し立て: PAY.JP がイベントを送るのは、異議申し立てが開かれたときだけです。照合のたびに、あなたに有利に終わった異議申し立て(状態 cancel)も読み、支払いトランザクションが自分では報告しないチャージバックの取り消しを記録します。チャージバックなしで終わった異議申し立て(問い合わせ)は、何も記録しません。
  • 返金: チップの返金は PAY.JP のダッシュボードで行います。全額の返金とチャージバックはチップとともに記録され、一部の返金は収入にだけ記録されます。

カード番号、有効期限、セキュリティコードは、payjp.js が表示する PAY.JP の iframe の中でだけ入力されます。このサーバーのページとスクリプトがそれらに触れることはありません。サーバーが受け取るのは、payjp.js が作ったトークンの ID と、3-D セキュアに必要なカード名義とメールアドレスだけです。 サーバーが保存するのは、PAY.JP のオブジェクトの ID(cus_、sub_、ch_、Plan の ID、イベントの ID、チップの Checkout Session、PaymentFlow、返金、異議申し立て)、金額、期間、状態だけです。チップのカードは PAY.JP 自身のページで入力され、このサーバーがそのページを配信することはありません。カード番号、下 4 桁、有効期限は保存しません(カードのページは、下 4 桁、有効期限、顧客のメールアドレスを PAY.JP から読んで表示するだけです)。Webhook の本文と PAY.JP の応答は、ログにもデータベースにも残しません。

支払いページはこのサーバーのオリジンから配信されるため、PCI DSS v4 の支払いページのスクリプトの管理(要件 6.4.3)と改ざんの検知(要件 11.6.1)を念頭に置いて作られています。

  • ページは Web クライアントの一部で、サーバーのバイナリに組み込まれています。Web クライアント自身のスクリプトをこのサーバーから、それぞれ Subresource Integrity を付けて読み込み、PAY.JP が配信して更新する https://js.pay.jp/v2/pay.js を読み込みます。解析や広告のスクリプトは読み込みません。
  • リリースごとに payment-scripts.json が付きます。これは、ページが読み込むすべてのスクリプトの一覧で、Web クライアントの各スクリプトとそのハッシュ、そして payjp.js が入っています。ページは Web クライアントのほかの部分とスクリプトを共有するため、一覧はリリースごとに変わります。動かしているリリースの一覧を保管してください。サーバーは、一覧がスクリプトと一致しないビルドでは起動を拒否します。
  • ページは常に独自の Content-Security-Policy(script-src はこのサーバーと https://js.pay.jp だけ、frame-src は https://js.pay.jp と https://api.pay.jp だけ、form-action 'self'、frame-ancestors 'none')、Referrer-Policy: no-referrer、Cache-Control: no-store、X-Content-Type-Options: nosniff を付けます。CSP を変える設定はありません。フォームの送信は同じオリジンからのものだけを受け付けます。

その結果、運営者の対象範囲は、支払いの入力を PAY.JP の iframe に任せる加盟店のもの(SAQ A)になると見込まれます。当てはまる対象範囲と自己問診票の種類は、PAY.JP の案内とカードブランドの要件に照らして確認してください。 その際、次の点を記録しておくと役に立ちます。支払いページの URL(/payments/pages/payjp/checkout と /portal)、ページが読み込むスクリプトの一覧(そのリリースの payment-scripts.json)、ページの CSP、そしてサーバーへの通信が TLS を使うこと(リバースプロキシの設定)です。

1. PAY.JP のアカウントを用意する

Section titled “1. PAY.JP のアカウントを用意する”
  1. PAY.JP のアカウントを作り、テストモードで始めます。本番モードで課金するには、本番利用の申請と審査が必要です。
  2. PAY.JP のダッシュボードで「API 設定 > 3D セキュア」を確認します。サーバーはトークンを作るたびに 3-D セキュアを求めるので、すべてのトークン作成で 3-D セキュアを必須にすることもできます。
  3. 特定商取引法に基づく表記のページは、このサーバーの管理画面で設定します(supporters.md を参照してください)。

PAY.JP のダッシュボードの「API」で、次の 2 つの鍵を確認します。鍵の接頭辞がモードを決め、テスト用の鍵では課金されません。2 つの鍵は同じモードでなければなりません。

鍵 例 用途
秘密鍵 sk_test_... / sk_live_... サーバーがこれで API を呼びます。ページの URL に署名する鍵の元にもなります
公開鍵 pk_test_... / pk_live_... 支払いページとカードのページの payjp.js

秘密鍵は環境変数 MY_PAYMENTS_PAYJP_SECRET_KEY(または MY_PAYMENTS_PAYJP_SECRET_KEY_FILE にファイルのパス)で渡します。設定ファイルには書けません。 秘密鍵が漏れたら、ダッシュボードで再発行し、新しい鍵で再デプロイします。再デプロイ前に開かれていた支払いページとカードのページの URL は使えなくなります。

PAY.JP のダッシュボードの「設定 > Webhook」で、送信先を追加します。テストモードと本番モードは別々に登録します。

  • URL: https://<server domain>/payments/webhooks/payjp
  • モード: 鍵と同じ

PAY.JP の Webhook は、アカウントの origin token(whook_...、ヘッダー X-Payjp-Webhook-Token)で送信元を示します。ダッシュボードに表示されるトークンを、環境変数 MY_PAYMENTS_PAYJP_WEBHOOK_TOKEN(または _FILE)で渡します。 エンドポイントはトークンを定数時間で比較し、本番の鍵で受け取ったテストのイベント(とその逆)を 400 で拒否します。署名もタイムスタンプもないため、トークンを知っている人なら誰でも通知を送れますが、サーバーは通知の内容から状態を書き込むことはなく、PAY.JP から状態を読み直すだけです。

サーバーが使うイベントは次のとおりです(ほかの種類も受け付けますが、記録しません)。

  • subscription.created, subscription.updated, subscription.deleted, subscription.paused, subscription.resumed, subscription.canceled, subscription.renewed
  • charge.succeeded, charge.failed, charge.refunded
  • dispute.created
  • statement.created
  • チップ(API v2)の場合: checkout.session.completed, checkout.session.expired, payment_flow.succeeded, refund.created, refund.updated, refund.failed, dispute.created

サーバーは API v1 と v2 のイベントを形で見分けるので、どちらのバージョンも同じ URL と同じトークンに送られます。

PAY.JP が通知を再送するのは 3 分ごとに最大 3 回だけで、それを過ぎた通知はダッシュボードから再送するまで届きません。受け取り損ねたものは照合が補うので、payments_reconcile_interval を 1 時間にすることをおすすめします。 プロバイダーの状態(モード、最後に Webhook が届いた時刻、最後の照合の結果)は、管理画面の /admin/supporters にある「決済の事業者」の欄に表示されます。

ターミナルウィンドウ
MY_PAYMENTS=payjp
MY_PAYMENTS_PAYJP_SECRET_KEY=sk_test_...
MY_PAYMENTS_PAYJP_PUBLIC_KEY=pk_test_...
MY_PAYMENTS_PAYJP_WEBHOOK_TOKEN=whook_...
# The recommended reconciliation interval (15m to 168h, default 6h) and the most requests one reconciliation sends (default 1000)
MY_PAYMENTS_RECONCILE_INTERVAL=1h
MY_PAYMENTS_RECONCILE_MAX_REQUESTS=1000

my config check で設定を確認できます。

テスト用の鍵で始めます。テストモードと本番モードでは、Plan、顧客、サブスクリプション、Webhook、トークンがそれぞれ別です。本番に移るには、本番モードで Webhook を登録し、鍵とトークンを本番のものに替えて再デプロイします。プランの Plan は本番のアカウントに新しく作られます。

テストカード(PAY.JP のドキュメント):

番号 動作
4242 4242 4242 4242 成功する
4000 0000 0008 0319 カードは登録できるが、課金が拒否される(サブスクリプションの失敗と、カード変更後の再開の失敗)
4000 0000 0000 4012 カードは登録できるが、期限切れとして課金に失敗する
4000 0000 0000 0002 カードの登録(トークンの作成)が拒否される

有効期限には未来の日付を使います。セキュリティコードと名義は任意です。テストモードでは、PAY.JP の 3-D セキュアのテスト用認証画面で結果を選べます。

更新をすぐに試すには、API でサブスクリプションの trial_end を数分先に設定します。更新の課金はその時刻ちょうどではなく、その数分後に行われます。最初の更新を待っているあいだに trial_end をもう一度更新すると、待ち時間が最初からになります。 支払いの失敗と猶予期間を試すには、購読してから、カードのページでカードを拒否されるカード(4000 0000 0008 0319)に変え、サブスクリプションの更新を待ちます。

PAY.JP の Webhook は公開 URL に届くため、手元のマシンのサーバーで受け取るには、トンネル(cloudflared、ngrok など)でポートを公開し、その URL をテストモードの送信先として登録します。 payjp-cli の payjp listen --forward-to http://localhost:8080/payments/webhooks/payjp もイベントを転送できると見込まれますが、v1 のイベントを転送できるかは確認されていません。

支払いページとカードのページは、このサーバーのオリジンで開いてください(http://localhost:8080 でも動きますが、payjp.js と 3-D セキュアの動作はブラウザーの設定によって変わります)。

  • 種類が permission の照合の失敗は、秘密鍵が誤っていることを意味します。
  • 「決済の事業者」の欄の警告にある duplicate_charge は、閉じたサブスクリプションへの支払いの返金を、サーバーが終えられなかったことを意味します。ログの行 a second subscription could not be canceled and refunded がそのサブスクリプションを示し、照合のたびに、サブスクリプションが削除されたあとも再試行します。続くようならダッシュボードでその課金を返金してください。PAY.JP が削除されたサブスクリプションの課金を一覧に出し続けるかぎり、次の再試行で返金済みと分かり、警告が消えます(確認が必要な点を参照してください)。180 日より前の課金は返金できません。サーバーはそれをログに出して先に進みます。
  • そのほかの返金は PAY.JP のダッシュボードで扱います。全額返金とチャージバックでは、ロールが外れ、サブスクリプションがすぐに削除されます。一部返金ではロールは外れません。
  • チャージバックの取り消しは、PAY.JP がそのイベントも API も提供していないため(チップのものはあります。チップを参照してください)、自動では記録されません。起きたときは、費用のページ(finance)の収入の画面に、取り消された金額を記録してください。ロールは自動では戻りません。
  • PAY.JP の有料プランの料金と振込手数料は、収入から差し引かれません。finance に費用として記録してください。
  • 照合がよくリクエストの上限に達するときは、payments_reconcile_max_requests を上げるか、payments_reconcile_interval を長くしてください。

アップグレードでは、まず日割りの差額を課金し、その課金が成功してからプランを移します。課金が拒否されると、プランはそのままで、ユーザーにはカードを更新する方法を示すエラーが表示されます。猶予期間も支払い失敗の通知もなく、正常なカードでやり直すと 1 回だけ課金されます。課金のあとでプランの移動に失敗した場合、やり直しても再び課金されることはありません。差額が最低額の 50 円に満たないときと、同じプランの年額への変更(正の差額がありません)では、その場では何も課金せず、すぐにプランを移します。新しい価格は期間の終わりに課金され、そこで失敗すると更新の失敗になります。

次の動作は、PAY.JP のドキュメントでもテストモードでも確定していません。

  • チャージバックで戻る手数料がどう計算されるか、そして期間の明細がサーバーの手数料と一致するか(テストモードでは、手数料は切り捨てられ、返金の手数料はその金額から計算されていました)。
  • 実際のチャージバックで何が起きるか。PAY.JP は、テストモードでチャージバックを起こす方法も、dispute.created の本文も記載していません。ダッシュボードからこのイベントをテスト送信すると 200 が返り、何も変わりません。
  • イベントの一覧がどこまでさかのぼれるか。
  • Plan を削除すると既存のサブスクリプションに影響するか(サーバーは Plan を削除しません)、そして Plan の ID の最大長。
  • 支払いページを読み込むときの CSP の報告が問題になるか。pay.js は style-src 'self' に反してインラインのスタイルを適用しますが、Chromium ではカード入力欄と 3-D セキュアが動きます。ほかのブラウザーは確認していません。
  • payjp-cli が v1 のイベントを転送できるか。
  • 顧客の保存済みのカードへの課金で、リクエストが求めないかぎり 3-D セキュアが求められないこと。拒否された課金は GET /v1/charges に paid: false で一覧に出ますが、サーバーは支払われていない課金を無視します。
  • API v2 のチップについて。これらは PAY.JP のガイドと公式 SDK から作ったもので、まだテストモードで試していません。PAY.JP が v2 のイベントを v1 のイベントと同じ送信先に同じトークンで送ること。ホスト型ページが pay.jp かそのサブドメインにあること。Checkout Session の作成が Idempotency-Key を尊重すること。支払いトランザクションの resource_id が、支払いでは PaymentFlow、返金では返金、チャージバックとその取り消しでは異議申し立てであること。一覧が新しい順で、starting_after と ending_before が使えること。トランザクションの金額と手数料の符号。そして v1 の期間の明細に v2 の手数料が含まれること。
  • subscription を指定した GET /v1/charges が、削除されたサブスクリプションの課金も一覧に出すこと。サーバーは削除の前に返金するので、これに頼るのは返金が完全に失敗したあとの再試行だけです。API リファレンスはこの絞り込みを記載していますが、削除されたサブスクリプションについては何も述べていません。一覧が空で返ると、サーバーは返金ではなく失敗を報告し、手作業で課金を返金しても duplicate_charge が残ります。

LLM とコーディングエージェント向け:llms.txt,llms-full.txt, llms-small.txt

このサイトのアクセス解析