payjp.js リファレンス

payjp.js のデフォルトのフォームデザインは、予告なく変更される場合がございますので、ご了承ください。

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

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

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

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

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

3Dセキュアに必要なカード名義やメールアドレス、電話番号などのフォームは、ご自身で用意してください（それらの情報は payjp.createToken() の引数に渡すことで管理できます）。

動作環境

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

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

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

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

API

API 表記は、引数名のすぐ隣に `?` がついているものは省略可能な任意引数となります。コロン区切りで引数の型を表記しています。

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

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

Payjp(publicKey: string, options?: object)

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

3Dセキュアを実施する場合、threeDSecureWorkflowの指定をご検討ください。
デフォルトのサブウィンドウ型を使う場合、注意事項がございます。

引数

publicKey : 管理画面から取得できる、あなたの公開鍵
options

key	型	説明
locale	string	フォームのプレースホルダーおよびエラー時のメッセージの言語を指定します。デフォルトは ja（日本語）で、他に en（英語）を指定できます。
threeDSecureWorkflow	string	3Dセキュアワークフローを変更する。 iframe : iframe型へ変更 redirect : リダイレクト型へ変更 subwindow : (デフォルト)サブウィンドウ型で自動的に認証を行う

例

const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')

// リダイレクト型へ変更
const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9', {threeDSecureWorkflow: 'redirect'})

payjp.getPublicKey()

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

payjp.elements(options?: object)

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

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

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

引数

options

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

例

const elements = payjp.elements()

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

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

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

引数

type

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

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

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

options

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 : elements.create() の引数欄を参照

戻り値

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

例

const cardElement = elements.getElement('card')

elements.update(options?: object)

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

引数

options

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

例

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

element.mount(domElement: string)

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

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

引数

domElement : 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

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, data?: object = {}, options?: object = {})

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

※3Dセキュアを行う場合、カードホルダーの名義および、メールアドレス・電話番号のどちらかの入力が求められますのでご注意ください。詳細

引数

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

key	型	説明
threeDSecureDialogOptions	object	サブウィンドウ型のトークン3Dセキュアを実施する際に内部で実行される `openThreeDSecureDialog()` の第二引数を指定

戻り値

トークンを作成 API のレスポンス(Token オブジェクトまたは Error オブジェクト)で resolve された Promise を返します。

また、reject が発生するケースもあるため、promise の catch を実装してください。

例

payjp.createToken(cardElement, {
  tenant: 'tenant_id', // Marketplace型Platform をご利用の方のみ指定。任意ですが指定を強く推奨します。
  three_d_secure: true,
  // ※3Dセキュアを行う場合、カードホルダーの名義および、メールアドレス・電話番号のどちらかの入力が求められますのでご注意ください。
  card: {name: 'PAY JP', email: 'liveaccount@example.com', phone: '+81301234567'},
}, {
  threeDSecureDialogOptions: {
    timeout: 1800000,
    windowFeatures: {
      width: 600,
      height: 500,
      top: 0,
      left: 0,
    }
  },
}).then((response) => {
  if (response.error) {
    // エラー処理
  } else {
    // response.id はトークンの ID
  }
}).catch((error) => {
    // 一般的なエラーハンドリング(payjs内からのrejectはErrorオブジェクト)
})

payjp.retrieveAvailability(options?: object)

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

引数

options :

key	型	説明
tenant	string	テナントID。Marketplace 型 Platform をご利用の方のみ指定。任意ですが指定を強く推奨します。指定が必要な理由についてはトークン作成時のテナント 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.openThreeDSecureIframe(objectId: string)

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

引数

objectId : 3D セキュア実施対象オブジェクトの ID

戻り値

認証の成功・失敗に関わらず、iframe内で3Dセキュア認証が終了したタイミングで resolve される Promise を返します。
利用者自身がクローズした場合や、すでに認証済みであったなど3Dセキュア認証中にエラーがあった場合は Error オブジェクトが reject されます。

例

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

payjp.openThreeDSecureIframe('ch_xxxxxx').then(() => {
  // 3Dセキュアフロー終了を加盟店サーバーに通知
  fetch("https://example.com/finish_3ds_authentication", {method: 'POST'}) // リクエスト例
}).catch((error) => {
  // エラーを加盟店サーバーに通知
  fetch("https://example.com/finish_3ds_authentication", {method: 'POST', body: JSON.stringify(error)}) // リクエスト例
})

payjp.openThreeDSecureDialog(objectId: string, options?: number | object)

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

引数

objectId : 3D セキュア実施対象オブジェクトの ID
options : 以下を object 型で指定、または数値型で timeout のみをミリ秒で指定できます。

key	型	説明
timeout	number	ウィンドウがクローズされるのを待つ時間(ミリ秒)。デフォルトは 1800000（30分）
windowFeatures	object	サブウィンドウのサイズなどを指定。以下参照。

windowFeatures は以下の型となります。
window.open() の第三引数に従うため、そちらの仕様も参照してください。

key	型	説明
width	number	スクロールバーを含むコンテンツ領域の幅を指定します。デフォルトは 600、必要最小値は 100 です。
height	number	スクロールバーを含むコンテンツ領域の高さを指定します。デフォルトは 500、必要最小値は 100 です。
top	number	サブウィンドウの左側からの距離をピクセル単位で指定します。デフォルトは中央付近を算出します。
left	number	サブウィンドウの左側からの距離をピクセル単位で指定します。デフォルトは中央付近を算出します。
popup	boolean	`false` を指定することで、他の設定を無視し、サブウィンドウではなくタブで開きます。

戻り値

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

例

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

payjp.openThreeDSecureDialog('ch_1122334455', {
  timeout: 1800000,
  windowFeatures: {
    width: 600, height: 500, top: 0, left: 0
  }
}).then(() => {
  // 3Dセキュアフロー終了をサーバーに通知
}).catch((e) => {
  // 一般的なエラーハンドリング(payjs内からのrejectはErrorオブジェクト)
})

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 で生成される 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 の状態に応じたスタイル調整を容易に行うことができます。