payments.js リファレンス

payments.js の導入方法、各オプション、メソッド、イベントについてのリファレンス

payments.js は、Payment Widgets を利用するための JavaScript ライブラリです。このページでは payments.js の導入方法と、利用できるオプション・メソッド・イベントについて説明します。

Payment Widgets を使った決済フローや実装手順については埋め込み型決済を使うをご確認ください。

payments.js の導入

HTML に script タグを設置して利用する方法と、npm パッケージを利用する方法があります。

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')

React を利用している場合は、React 向けラッパーの react-payments-js も利用できます。

PayjpPayments の初期化オプション

PayjpPayments(publicKey, options) の第2引数でオプションを指定できます。

const payments = PayjpPayments('YOUR_PUBLIC_KEY', {
  locale: 'en',
});

パラメーター	型	デフォルト	説明
`locale`	`"ja"` \| `"en"`	`"ja"`	UI の表示言語

Widgets の作成オプション

payments.widgets(options) でウィジェットのインスタンスを作成します。

const widgets = payments.widgets({
  clientSecret: 'YOUR_CLIENT_SECRET',
});

パラメーター	型	必須	説明
`clientSecret`	`string`	はい	Payment Flow (支払い管理オブジェクト)API または Setup FlowAPI の client_secret
`locale`	`"ja"` \| `"en"`	いいえ	PayjpPayments の設定を上書きする場合に指定

PaymentForm の作成オプション

widgets.createForm("payment", options) で支払いフォームを作成します。

const paymentForm = widgets.createForm('payment', {
  layout: 'tab',
  fields: {
    billingDetails: {
      name: 'auto',
      email: 'never',
      phone: 'never',
    },
  },
  paymentMethodOrder: ['card', 'paypay'],
});
paymentForm.mount('#payment-form');

`layout`

フォームのレイアウト形式を指定します。文字列またはオブジェクトで指定できます。

文字列で指定する場合

値	説明
`"accordion"`	アコーディオン形式（デフォルト）
`"tab"`	タブ形式

オブジェクトで指定する場合

プロパティ	型	デフォルト	説明
`type`	`"tab"` \| `"accordion"`	`"accordion"`	レイアウトの種類
`defaultCollapsed`	`boolean`	`"accordion"` の場合 `true`、`"tab"` の場合 `false`	初期状態で折りたたむかどうか

const paymentForm = widgets.createForm('payment', {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
  },
});

`fields`

請求先情報の各フィールドの表示を制御します。

プロパティ	型	デフォルト	説明
`billingDetails.name`	`"auto"` \| `"never"`	`"auto"`	名前フィールドの表示
`billingDetails.email`	`"auto"` \| `"never"`	`"auto"`	メールアドレスフィールドの表示
`billingDetails.phone`	`"auto"` \| `"never"`	`"auto"`	電話番号フィールドの表示

"auto" を指定すると、支払い方法に応じてフィールドが自動的に表示されます。 "never" を指定すると、フィールドは常に非表示になります。

billingDetails に文字列で "auto" または "never" を指定すると、全フィールドに一括で適用されます。

加盟店側ですでに請求先情報を取得済みの場合は、fields で該当フィールドを非表示にし、confirmPayment や confirmSetup の呼び出し時に payment_method_data.billing_details で値を渡すことができます。

// 加盟店側で取得済みの請求先情報はフォームに表示せず、確定時に渡す
const paymentForm = widgets.createForm('payment', {
  fields: {
    billingDetails: 'never',
  },
});

const result = await widgets.confirmPayment({
  return_url: 'https://example.com/return',
  payment_method_data: {
    billing_details: {
      name: '山田 太郎',
      email: 'taro@example.com',
    },
  },
});

`defaultValues`

フォームの初期値を設定します。加盟店側で取得済みの情報をフォームにあらかじめ入力した状態で表示したい場合に使用します。

const paymentForm = widgets.createForm('payment', {
  defaultValues: {
    billingDetails: {
      name: '山田 太郎',
      email: 'taro@example.com',
    },
  },
});

指定可能なプロパティは以下の通りです。

{
  billingDetails: {
    name?: string
    email?: string
    phone?: string
    address?: {
      line1: string
      line2: string
      city: string
      state: string
      zip: string
      country: string
    }
  }
}

`paymentMethodOrder`

支払い方法の表示順を配列で指定します。指定しない場合はデフォルトの順序で表示されます。

使用可能な値は "card", "paypay", "apple_pay" です。

const paymentForm = widgets.createForm('payment', {
  paymentMethodOrder: ['card', 'paypay', 'apple_pay'],
});

AddressForm の作成オプション

widgets.createForm("address", options) で住所フォームを作成します。

const addressForm = widgets.createForm('address', {
  mode: 'shipping',
  fields: {
    phone: 'always',
  },
});
addressForm.mount('#address-form');

`mode`（必須）

住所フォームの用途を指定します。

値	説明
`"shipping"`	配送先住所
`"billing"`	請求先住所

`defaultValues`

住所フォームの初期値を設定します。

{
  name?: string
  phone?: string
  address?: {
    country?: string
    zip?: string
    state?: string
    city?: string
    line1?: string
    line2?: string
  }
}

`fields`

プロパティ	型	デフォルト	説明
`phone`	`"always"` \| `"auto"` \| `"never"`	`"auto"`	電話番号フィールドの表示

Form のメソッド

PaymentForm と AddressForm で共通して利用できるメソッドです。

`mount(selector)`

指定したセレクターまたは HTMLElement にフォームをマウントして表示します。

paymentForm.mount('#payment-form');
// または
paymentForm.mount(document.getElementById('payment-form'));

`unmount()`

フォームをアンマウントして非表示にします。再度 mount で表示できます。

`update(options)`

フォームのオプションを更新します。layout（PaymentForm）や mode（AddressForm）は作成後に変更できません。

paymentForm.update({
  defaultValues: {
    billingDetails: {
      name: '山田 太郎',
    },
  },
});

`collapse()`

フォームを折りたたみます。

`on(eventType, handler)` / `off(eventType, handler)`

イベントリスナーの登録・解除を行います。利用可能なイベントについては次のセクションをご確認ください。

Form のイベント

on メソッドで以下のイベントを購読できます。

`ready`

フォームの準備が完了したときに発火します。

paymentForm.on('ready', () => {
  console.log('フォームの準備完了');
});

`change`

フォームの値が変化したときに発火します。

PaymentForm の場合

paymentForm.on('change', (event) => {
  console.log(event.complete); // フォームの入力が完了しているか
  console.log(event.empty);    // フォームが空か
  console.log(event.value.type); // 選択中の支払い方法（"card", "paypay" など）
});

AddressForm の場合

addressForm.on('change', (event) => {
  console.log(event.complete);
  console.log(event.empty);
  console.log(event.value.name);    // 入力された名前
  console.log(event.value.phone);   // 入力された電話番号
  console.log(event.value.address); // 入力された住所
});

`focus` / `blur`

フォームのフィールドにフォーカスが当たったとき、外れたときに発火します。

paymentForm.on('focus', () => {
  console.log('フォーカスされました');
});

paymentForm.on('blur', () => {
  console.log('フォーカスが外れました');
});

Widgets のメソッド

`createForm(formType, options)`

フォームを作成します。formType には "payment" または "address" を指定します。オプションの詳細は PaymentForm の作成オプションと AddressForm の作成オプションをご確認ください。

`getForm(formType)`

作成済みのフォームを取得します。AddressForm の場合は mode の指定が必要です。

const paymentForm = widgets.getForm('payment');
const shippingForm = widgets.getForm('address', { mode: 'shipping' });

`update(options)`

Widgets のオプションを更新します。clientSecret は作成後に変更できません。

widgets.update({
  locale: 'en',
});

`fetchUpdates()`

サーバーから最新の情報を取得してフォームを更新します。

await widgets.fetchUpdates();

`on("updateEnd", handler)`

fetchUpdates や update による更新が完了したときに発火するイベントを購読します。

widgets.on('updateEnd', () => {
  console.log('更新完了');
});

`confirmPayment(confirmParams)`

支払いを確定します。確定後、return_url で指定した URL へリダイレクトされます。入力内容に問題がある場合はエラーが返されます。

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

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

`confirmSetup(confirmParams)`

支払い方法の登録を確定します。動作は confirmPayment と同様です。

const result = await widgets.confirmSetup({
  return_url: 'https://example.com/return',
});

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

confirmParams

confirmPayment と confirmSetup に渡すパラメーターです。

パラメーター	型	必須	説明
`return_url`	`string`	はい	処理完了後のリダイレクト先 URL
`payment_method_data.billing_details`	`object`	いいえ	請求先情報の上書き

payment_method_data.billing_details では以下のプロパティを指定できます。

{
  name?: string
  email?: string
  phone?: string
  address?: {
    line1: string
    line2: string
    city: string
    state: string
    zip: string
    country: string
  }
}

PayjpPayments のメソッド

PayjpPayments インスタンスから直接呼び出すメソッドです。

`retrievePaymentFlow(clientSecret)`

client_secret を使って Payment Flow (支払い管理オブジェクト)API の情報を取得します。リダイレクト先で支払い結果を確認する際に使用します。

const paymentFlow = await payments.retrievePaymentFlow('YOUR_CLIENT_SECRET');
if (paymentFlow.status === 'succeeded') {
  // 支払い成功
}

`retrieveSetupFlow(clientSecret)`

client_secret を使って Setup FlowAPI の情報を取得します。

const setupFlow = await payments.retrieveSetupFlow('YOUR_CLIENT_SECRET');
if (setupFlow.status === 'succeeded') {
  // 登録成功
}

`handleNextAction({ clientSecret })`

追加のアクション（3Dセキュア認証など）が必要な場合に、処理を継続します。

await payments.handleNextAction({
  clientSecret: 'YOUR_CLIENT_SECRET',
});

payments.js リファレンス

On this page