支払い方法を登録する

Setup Flow とは

Setup FlowAPIは、支払い方法をCustomer (顧客)APIに紐づけて登録するための仕組みです。 Payment Flow (支払い管理オブジェクト)APIが支払いを行うためのフローであるのに対し、Setup Flow は支払い方法の登録のみを行い、実際の決済は行いません。

Setup Flow を使用することで、以下のようなユースケースに対応できます。

• 会員登録時に支払い方法を登録しておき、次回以降の決済で利用できるようにしたい場合
• ユーザーがマイページで支払い方法を変更できるようにしたい場合

対応する支払い方法

Setup Flow では以下の支払い方法を登録できます。

• クレジットカード
• Apple Pay

各支払い方法の詳細については支払い方法のページをご確認ください。

Setup Flow の利用フロー

処理の流れは以下の図のようになります。

1. 加盟店サーバーで Setup Flow を作成し、顧客に紐づけます。
2. フロントエンドで Payment Widgets を使用して支払い情報の入力フォームを表示します。
3. ユーザーが支払い情報を入力し、登録を確定します。
4. 3D セキュアなどの追加認証が必要な場合は、認証ページへリダイレクトされます。
5. 登録完了後、return_url で指定したページへリダイレクトされます。

支払い方法を登録する

Setup Flow を利用するには、加盟店システムでサーバーサイドとフロントエンドの両方の実装が必要です。

1. サーバーサイドで Setup Flow を作成する

支払い方法を登録する顧客を指定してSetup FlowAPIを作成します。 customer に顧客 ID を指定し、payment_method_types で登録可能な支払い方法を指定します。

curl -X POST https://api.pay.jp/v2/setup_flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_xxxxx",
    "payment_method_types": ["card"]
  }'

レスポンスとして取得できる client_secret をフロントエンドに渡します。

{
  "id": "sflw_xxxxx",
  "object": "setup_flow",
  "client_secret": "sflw_secret_xxxxx",
  "customer": "cus_xxxxx",
  "status": "requires_payment_method",
  "payment_method_types": ["card"],
  ...
}

2. フロントエンドで payments.js の利用準備を行う

PAY.JP の JavaScript ライブラリ payments.js を Web ページに読み込み、公開鍵を渡して初期化を行います。

HTML に script タグを設置する場合

<script src="https://js.pay.jp/payments.js"></script>
<script>
  const payments = PayjpPayments('pk_test_xxx');
  ...
</script>

npm などのパッケージマネージャーを利用する場合

npm install @payjp/payments-js

import { loadPayments } from '@payjp/payments-js'

const payments = await loadPayments('pk_test_xxx')
...

3. Widgets を初期化してフォームを表示する

Widgets を初期化します。 この時に「ステップ 1」で取得した client_secret を使用します。

const widgets = payments.widgets({
  clientSecret: "sflw_secret_xxxxx",
});

以下のように、指定した HTML 要素に Widgets をマウントすることで画面に決済フォームを表示します。

<div id="payment-form"></div>

const paymentForm = widgets.createForm("payment", {
  layout: "tab",
});
paymentForm.mount("#payment-form");

4. 支払い方法を確認・登録する

ユーザーがフォームに支払い情報を入力した後、登録を確定するには confirmSetup メソッドを実行します。

const result = await widgets.confirmSetup({
  return_url: 'https://example.com/setup-complete'
});

if (result.error) {
  // エラー処理
  console.error(result.error);
}

confirmSetup の実行後は自動的に別のページに遷移し、登録処理の完了後に return_url で指定した URL にリダイレクトされます。

5. リダイレクト先で登録完了を確認する

return_url にリダイレクトされた後、支払い方法の登録が成功しているかどうかを確認する必要があります。

リダイレクト先の URL にはクエリーパラメーターとして setup_flow_id に Setup Flow のID、setup_flow_client_secret に client_secret が付与されているため、 バックエンド、フロントエンドのどちらでも該当の Setup Flow を取得し状態を確認できます。

https://example.com/setup-complete?setup_flow_id=sflw_xxxxx&setup_flow_client_secret=sflw_secret_xxxxx

フロントエンドで確認する場合は、payments.js の retrieveSetupFlow メソッドを使用して Setup Flow を取得し、status フィールドを確認します。

const setupFlow = await payments.retrieveSetupFlow(
  "sflw_secret_xxxxx"
);

if (setupFlow.status === 'succeeded') {
  // 登録成功
  const paymentMethodId = setupFlow.payment_method;
  console.log('登録された支払い方法:', paymentMethodId);
} else {
  // 登録失敗時の処理
}

登録が成功している場合は status が succeeded になり、payment_method に登録されたPayment Method (支払い方法)APIの ID が格納されます。

登録した支払い方法で支払う

Setup Flow で登録した支払い方法を使って決済を行うには、Payment Flow を作成する際に payment_method パラメーターを指定します。

詳しくは埋め込み型決済を使うのページをご確認ください。

Setup Flow のステータス

Setup FlowAPIは作成から完了またはキャンセルまで、以下の状態を持ちます。