PAY.JP をご利用いただきありがとうございます。payjp.js v2 のデフォルトのフォームデザインは、予告なく変更される場合がございますので、ご了承ください。

このドキュメントでは、PAY.JP のクライアントサイド（ブラウザ用）JavaScript ライブラリである payjp.js v2 の API 仕様について説明します。

基本的な使い方については、こちらのガイダンスをご確認ください。

payjp.js v2 は、最新の PCI-DSS に準拠したカード情報入力フォーム生成ライブラリです。同時に、カード情報または Apple Pay on the Web での決済情報をトークン化する API も提供しています。

PCI-DSS 準拠のため、以下の入力フォームは payjp.js v2 を利用して生成する必要があります（加盟店が独自に生成すると準拠とはみなされません）。

カード番号入力欄
有効期限入力欄（月 / 年）
CVC 入力欄

カードの名義や住所などが必要な場合は、自身でフォームを用意してください（それらの情報は payjp.createToken() の引数に渡し、管理できます）。

動作環境

payjp.js v2 は、以下のブラウザの最新バージョンで動作します。

Chrome（PC, Android）
Safari（mac, iOS）
Firefox
Edge

動作には、ブラウザが TLS 1.2 に対応している必要があります。

IE11 は正式にはサポートしていませんが、Promise API の Polyfill を用意いただくことで、現時点では動作することを確認しております。

API

payjp.js を使うには、https://js.pay.jp を直接読み込む必要があります。バンドルしたり、自身のサーバーにホストしての利用はできません。

<script src="https://js.pay.jp/v2/pay.js"></script>

Payjp(publicKey: string, options?: object)

全ての操作の起点となります。戻り値である Payjp インスタンスを使って、各種 API を利用できます。この操作は一度のみ行えます。

引数

publicKey (必須、 string) : 管理画面から取得できる、あなたの公開鍵
options (任意、 object)

key	型	説明
locale	string	フォームのプレースホルダーおよびエラー時のメッセージの言語を指定します。デフォルトは `ja`（日本語）で、他に `en`（英語）を指定できます。

例

const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')

payjp.getPublicKey()

セットされた公開鍵の文字列を取得します。

payjp.elements(options?: object)

Elements インスタンスを生成します。

Elements は Element インスタンスを束ねる単位です。1つの Elements インスタンスにつき、1 組のカード情報入力フォームを用意できます。ページ内に複数のフォームを作りたい場合は、その分だけ Elements インスタンスを生成してください。

現状、複数の Elements インスタンスを用意した場合でも、全てのインスタンスに対して同一の locale オプションが適用されます。各フォームごとに言語を分けることはできませんが、言語の切り替えは elements.update() で実現可能です。

引数

options (任意、 object)

key	型	説明
locale	string	フォームのプレースホルダーおよびエラー時のメッセージの言語を指定します。デフォルトは `ja`（日本語）で、他に `en`（英語）を指定できます。`Payjp()` での初期化時に設定していた場合は値を上書きします。

例

const elements = payjp.elements()

elements.create(type: string, options?: object)

指定された type の Element インスタンスを生成します。

Element インスタンスによって、入力フォームを操作できます。

引数

type (必須、 string)

値	説明
`card`	カード番号入力欄（ブランドアイコン付）、有効期限入力欄、CVC 入力欄の順に横並びのフォーム
`cardNumber`	カード番号入力フォーム。自動フォーマット、カードブランド画像表示機能あり
`cardExpiry`	有効期限入力フォーム。‘月 / 年’で自動フォーマット
`cardCvc`	CVC 入力フォーム

card を生成した場合、その elements から他の type は生成できません。

cardNumber を生成した場合、その elements から更に cardExpiry などを生成して組み合わせます（card は生成できません）。入力フォームを縦に並べるなど、より自由度の高い配置が可能です。

options (任意、 object)

key	型	説明
style	object	フォームに対して独自のスタイルを適用。style オブジェクトを参照
placeholder	string	type= `card` 以外でのみ適用。フォームに指定されたプレースホルダーを適用
disabled	boolean	`true` ならフォームの input タグに `disabled` をつける。デフォルトは `false`
hideIcon	boolean	type= `card` のみ適用。`true` ならカードブランドのアイコン表示機能をオフにする。デフォルトは `false`

例

const cardElement = elements.create('card', {style: {base: {color: '#fff'}}})

elements.getElement(type: string)

生成済みの Element インスタンスを返します。

引数

type (必須、 string) : elements.create() の引数欄を参照

戻り値

指定された type の Element インスタンスが生成済みであればそれを、なければ null を返します。

例

const cardElement = elements.getElement('card')

elements.update(options?: object)

Elements インスタンスの一部の設定値を更新できます。たとえば locale オプションを更新することで SPA での多言語対応が可能です。

引数

options (任意、 object)

key	型	説明
locale	string	フォームのプレースホルダーおよびエラー時のメッセージの言語を指定します。

例

elements.update({locale: 'en'})

element.mount(domElement: string)

引数を document.querySelector() で検索し、その子要素に Element（iframe タグ）を追加することで入力フォームを生成します。戻り値はありません。

マウント先を囲んでいる label タグ、または、マウント先の id を指定した for 属性を持つ label タグがある場合、その label 要素がクリックされるとフォームへ自動的にフォーカスされます。

引数

domElement (必須、 string) : CSS セレクターを表す文字列。document.querySelector() へ渡すため、この時点で domElement がレンダリングされている必要がある点に注意してください。

例

<label for="card-element">カード</label><!-- label タグは任意 -->
<div id="card-element"></div>

<script>
  cardElement.mount('#card-element')
</script>

label タグはマウント先を囲む形式でも動作します。

<label>カード
  <div class="card-element"></div>
</label>

<script>
  cardElement.mount('.card-element')
</script>

element.on(event: string, listener: function)

Element のフォームのイベントを監視します。詳細はこちらをご参照ください。

element.addEventListener(event: string, listener: function)

element.on() と同じです。

element.focus()

Element の input タグにフォーカスします。

例

cardElement.focus()

element.blur()

Element の input タグからフォーカスを外します。

例

cardElement.blur()

element.clear()

Element のフォームに入力されている値を全て削除します。

例

cardElement.clear()

element.unmount()

DOM 上から Element を取り除きます。再度 element.mount() を行うことで再配置できます。

例

cardElement.unmount()

element.update(options)

Element 生成時のオプションを更新します。elements.create() 時の options を引き継いで上書きします。

レスポンシブデザインなどに活用できます。

引数

options (必須、 object)

key	型	説明
style	object	フォームに対して独自のスタイルを適用。style オブジェクトを参照
placeholder	string	type= `card` 以外でのみ適用。フォームに指定されたプレースホルダーを適用
disabled	boolean	`true` ならフォームの input タグに `disabled` をつける。デフォルトは `false`
hideIcon	boolean	type= `card` のみ適用。`true` ならカードブランドのアイコン表示機能をオフにする。デフォルトは `false`

例

window.addEventListener('resize', (event) => {
  cardNumber.update({style: {base: {fontSize: window.innerWidth <= 320 ? '11px' : '12px'}}})
})

payjp.createToken(element: Element, options?: object)

PAY.JP のサーバーと通信し、カード情報の認証を行い、トークンを作成します。

引数

element (必須、 Element) : 送信したいフォームの Element インスタンスを指定します。Element インスタンスが cardNumber、cardExpiry、cardCvc のように複数ある場合、いずれか1つを指定してください。
options (任意、 object) : トークンを作成 API の引数を渡すことができます。ただし number / exp_month / exp_year / cvc は第1引数の Element から取得し送信するため、指定できません。

例：
- カードホルダーの名義を送信： {card: {name: 'PAY JP'}}
- 郵便番号も送信： {card: {name: 'PAY JP', address_zip: '106-6237'}}
Marketplace 型 Platform をご利用の方は {tenant: 'tenant_id'} を指定することを強く推奨します。指定が必要な理由についてはトークン作成時のテナント ID についてをご参照ください。

戻り値

トークンを作成 API のレスポンスで resolve された Promise を返します。

具体的には Token オブジェクト、または Error オブジェクトのいずれかとなります。

例

payjp.createToken(cardElement).then((response) => {
  if (response.error) {
    // エラー処理
  } else {
    // response.id はトークンの ID
  }
})

payjp.retrieveAvailability(options?: object)

PAY.JP のサーバーと通信し、利用可能なカードブランドを取得します。

引数

options (object, optional):
- Marketplace型Platformをご利用の方は {tenant: 'tenant_id'} を指定することを強く推奨します。指定が必要な理由についてはトークン作成時のテナントIDについてをご参照ください。

戻り値

card_types_supported（Array<string>, 利用可能なカードブランドの配列）と livemode（boolean, ライブモードか否か）を含むオブジェクト、またはErrorオブジェクトのいずれかで resolve された Promise を返します。

例

以下のコードは、payjp.retrieveAvailability メソッドを使用して、利用可能なカードブランドを取得する例です。

payjp.retrieveAvailability({tenant: 'test_tenant'}).then((response) => {
  if (response.error) {
    // エラーハンドリング
  } else {
    console.log(response)
    // {
    //   card_types_supported:
    //     ["Visa", "MasterCard", "JCB", "American Express", "Diners Club", "Discover"],
    //   livemode: true
    // }
  }
})

payjp.openThreeDSecureDialog(objectId: string, timeout: number = 1800000)

objectId で指定したオブジェクトに対する 3D セキュアフローを進めるためのサブウィンドウを開きます。

引数

objectId (string, required): 3D セキュア実施対象オブジェクトの ID
timeout (number, optional): ウィンドウがクローズされるのを待つ時間をミリ秒で指定します。デフォルトは 1800000（30分）

戻り値

開かれたサブウィンドウが閉じられたタイミングで resolve される Promise を返します。3D セキュアフローが正常に終了した場合、最終ページの JavaScript によりウィンドウは自動的に閉じられます。ユーザー操作によりフローに関係なく閉じられた場合にも resolve されるため、対象オブジェクトの 3D セキュア状態は別途確認する必要があります。timeout までサブウィンドウが閉じられなかった場合は reject されます。

例

以下のコードは、payjp.openThreeDSecureDialog メソッドを使用して、3D セキュアフローを開始する例です。

payjp.openThreeDSecureDialog('ch_1122334455').then(() => {
  // 3Dセキュアフロー終了をサーバーに通知
}).catch(() => {
  console.log('timeout')
})

Event

element.on(‘change’, listener: function)

Element のフォームの 'change' イベントを監視します。

引数

'change' (string, required)
listener (function, required): 第1引数に以下の key をもつオブジェクトが渡されます。戻り値は使われません

key	型	説明
elementType	string	イベントが起きた `Element` インスタンスのtype
complete	boolean	`true` ならフォームの入力が有効な可能性のある値で埋まったことを示します。この値を利用して `payjp.createToken()` を実行することは推奨されません（e.g. 入力後、ユーザーは別のカードに変更するため再度入力をするかもしれません）
empty	boolean	フォームに入力がない状態だと `true`
error	object	入力内容にエラーがある場合に `type`, `message` および `code` のkeyを持つobject。ない場合は `null`
brand	string	カード番号から判定されたブランド名。 `elementType` が `card` または `cardNumber` の時のみ存在。値: “Visa”, “Mastercard”, “JCB”, “American Express”, “Diners Club”, “Discover” または “unknown”

エラーメッセージには error.message の値をご利用いただけますが、 error.code の値からご自身で生成いただいても構いません。code と message は一対一対応し、change イベントにおける error.type の値は現在は validation_error で固定となっています。

code	message	詳細
incomplete_error	入力が完了していません。	入力値の桁数が不正
invalid_number	カード番号が無効です。	カード番号のLuhnアルゴリズム判定が不正
invalid_expiry_year_past	カードの有効期限が過ぎています。	有効期限（年）が昨年以前
invalid_expiry_month_past	カードの有効期限（月）が過ぎています。	上記以外の有効期限不正

例

以下のコードは、change イベントを監視し、イベント情報をコンソールに出力する例です。

cardElement.on('change', (event) => {
  console.log(event)
  /*
  {
    brand: 'Visa',
    complete: false,
    elementType: 'card',
    empty: false,
    error: {
      message: '入力が完了していません。',
      type: 'validation_error',
      code: 'incomplete_error'
    }
  }
  */
})

element.on(‘ready’, listener: function)

Element がレンダリングされ、操作可能になった際に、 listener を実行します。

引数

'ready' (string, required)
listener (function, required): 第1引数に以下の key をもつオブジェクトが渡されます。戻り値は使われません。

key	型	説明
elementType	string	イベントが起きた `Element` インスタンスのtype

element.on(‘focus’, listener: function)

Element の 'focus' イベントを監視します。

引数

'focus' (string, required)
listener (function, required): 第1引数に以下の key をもつオブジェクトが渡されます。戻り値は使われません。

key	型	説明
elementType	string	イベントが起きた `Element` インスタンスのtype

element.on(‘blur’, listener: function)

Element の 'blur' イベントを監視します。

引数

'blur' (string, required)
listener (function, required): 第1引数に以下の key をもつオブジェクトが渡されます。戻り値は使われません。

key	型	説明
elementType	string	イベントが起きた `Element` インスタンスのtype

styleオブジェクト

payjp.js v2 で生成される input 要素は PAY.JP ドメインの iframe 内にあるため、CSS ファイルなどからスタイルを適用はできません。

代わりに、以下の構造の JavaScript object を初期化時や更新時の引数 style に指定することで、任意の CSS を適用できます。

const style = {
  [inputStatus]: {
    [cssProperty]: [value],
  },
}

inputStatus はスタイルが適用されるべきフォームの入力状態を示します。inputStatus には以下の値が利用できます。

invalid : フォームに無効な文字列が入っている場合のみ適用
complete : フォームに invalid ではない文字列が埋まった場合のみ適用
empty : フォームにユーザー入力がない場合のみ適用
base : 上記いずれでもない場合に適用。また、上記全てはこのスタイルを継承する

inputStatus は複数指定可能です。全てを指定する必要はありません。

cssProperty には CSS プロパティ名を、 value にはその値を指定します。プロパティ名が JavaScript の慣習に則りキャメルケースで定義されている点にご注意ください。なお、利用可能なCSSプロパティ以外の値が指定された場合はエラーにはならずに無視されます。

例：文字色をエラー時は赤、それ以外は灰色にし、カーソルの色は常に緑色にする

const style = {
  base: {
    color: 'grey',
    caretColor: 'green',
  },
  invalid: {
    color: 'red'
  }
}

また、 : で始まる擬似クラス・擬似要素も指定できます。書き方は以下の例を参考にしてください。

:hover
:focus
:disabled
:-webkit-autofill
::placeholder
::selection

例：プレイスホルダーの色を指定する

const style = {
  base: {
    '::placeholder': {
      color: '#87BBFD',
    },
  },
}

利用可能なCSSプロパティ

backgroundColor (string): background-colorを参照
boxShadow (string): box-shadowを参照。ブラウザの自動入力（autofill）時のデフォルトの背景色を変えたい、などのニーズに対応できます。
caretColor (string): caret-colorを参照
color (string): colorを参照
fontFamily (string): font-familyを参照
fontSize (string): font-sizeを参照。相対単位を使用すると、基準は利用者側のサイトではなく iframe 内になるため、 px での指定をお勧めします。
fontStyle (string): font-styleを参照
fontVariant (string): font-variantを参照
fontWeight (string): font-weightを参照
lineHeight (string): line-heightを参照
letterSpacing (string): letter-spacingを参照
textAlign (string): text-alignを参照。cardNumber , cardExpiry , cardCvc にのみ効果があります。
textDecoration (string): text-decorationを参照
textShadow (string): text-shadowを参照
textTransform (string): text-transformを参照

例

以下のコードは、elements.create メソッドを使用して、カスタムスタイルを適用したカードフォームを作成する例です。

const cardElement = elements.create('card', {
  style: {
    base: {
      color: '#fff',
      fontFamily: 'Roboto, Open Sans, Segoe UI, sans-serif',
      fontSize: '16px',
      ':-webkit-autofill': {
        color: 'green',
      },
      '::placeholder': {
        color: '#87BBFD',
      },
    },
    invalid: {
      fontWeight: 500,
    },
  },
})

Elementコンテナ

element.mount() を使用して DOM エレメントにマウントされた Element には、その状態に応じて自動的に HTML の class 属性が付与されます。

初期状態では、PayjpElement と PayjpElement--empty のクラス名が設定されています。その後、ユーザーの入力状態に応じて、以下のクラス名が適宜更新されます（複数の状態を満たす場合は、対応するクラス名が複数適用されます）。

クラス名	状態
PayjpElement	常に存在
PayjpElement–empty	入力値が空の場合
PayjpElement–focus	入力フォームがフォーカスされている場合
PayjpElement–complete	適切な入力値が存在する場合
PayjpElement–invalid	入力値が存在するが不正な場合

この自動的なクラス付与により、開発者は CSS を使って Element の状態に応じたスタイル調整を容易に行うことができます。

payjp.js v2 リファレンス