埋め込み型決済を使う

Payment Widgets とは

Payment Widgets は、加盟店のウェブサイトに埋め込む形で利用できる決済フォームウィジェットです。支払い情報を入力するための PaymentForm、請求先・配送先住所を入力するための AddressForm の2つのコンポーネントを提供しています。 Payment Widgets を利用することで、ユーザーは加盟店のサイト上で安全に情報を入力することができ、その情報を使って支払いを受け付けたり支払い方法の登録ができます。

このページでは PaymentForm を使用して支払いを受け付ける方法について説明します。

Payment Widgets の利用フロー

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

支払いを受け付ける

Payment Widgets を利用するには、加盟店システムでバックエンドとフロントエンドの両方の実装が必要です。

1. バックエンドで PAY.JP の v2 SDK の準備をする

ご利用の言語に合わせて API v2 の SDK をインストールし、API キーを設定して SDK の利用準備を行います。

より詳しくはSDKをご確認ください。

2. 加盟店サーバーで Payment Flow を作成し、`client_secret` を取得する

支払い価格や通貨などを指定して Payment Flow (支払い管理オブジェクト)APIを作成します。 amount に支払いを行う金額を指定し、 currency には jpy を指定します。 payment_method_types パラメーターで利用する支払い方法を指定することもできます。省略した場合は、アカウントで設定した利用可能な支払い方法が使用されます。

その他のパラメータについては Payment Flow (支払い管理オブジェクト)APIAPI のページをご確認ください。

curl -X POST https://api.pay.jp/v2/payment_flows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "jpy",
    "payment_method_types": ["card", "paypay", "apple_pay"],
  }'

この API のレスポンスとして取得できる client_secret をサーバーサイドレンダリング時にHTMLに埋め込んだり、専用の API エンドポイントを用意するなどしてフロントエンドに渡します。

3. フロントエンドで payments.js の利用準備を行います

PAY.JP の JavaScript ライブラリ payments.js を Web ページに読み込み、PAY.JP の管理画面で取得できる公開 API キーを渡して初期化を行います。 HTML に script タグを設置して利用する方法と、npm などのパッケージマネージャーを利用する方法があります。

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

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

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

プロジェクトに @payjp/payments-js パッケージをインストールします。

npm install @payjp/payments-js

loadPayments メソッドを使用して payments オブジェクトを初期化します。

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

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

4. Widgets に `client_secret` を渡して初期化し、画面にフォームを表示する

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

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

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

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

const paymentForm = widgets.createForm("payment");
paymentForm.mount("#payment-form");

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

const result = await widgets.confirmPayment({ return_url: 'https://example.com/return_url' })

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

confirmPayment の実行後は自動的に別のページに遷移し、支払い処理の完了後に return_url で指定した URL にリダイレクトされます。入力された支払い情報に問題があった場合は result にエラー内容を含む情報が返されます。

5. リダイレクト先で支払いの成功を確認する

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

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

リダイレクト先に付与されるクエリーパラメーターの例

https://example.com/return_url?payment_flow_id=pfw_xxxxx&payment_flow_client_secret=pfws_xxxxx

バックエンドで確認する場合は、PAY.JP の v2 SDK を使用して Payment Flow を取得し、 status フィールドを確認します。

curl -X GET https://api.pay.jp/v2/payment_flows/{YOUR_PAYMENT_FLOW_ID} \
  -H "Authorization: Bearer YOUR_API_KEY"

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

const paymentFlow = await payments.retrievePaymentFlow({
  client_secret: "YOUR_PAYMENT_FLOW_CLIENT_SECRET"
});
if (paymentFlow.status === 'succeeded') {
  // 支払い成功時の処理
} else {
  // 支払い失敗時の処理
}

支払いが成功している場合は status が succeeded になります。 status のその他の値については Payment Flow API の仕組みのページをご確認ください。

埋め込み型決済を使う

On this page