payjp.js v2のデフォルトのフォームデザインについて、予告なく修正を加えさせていただく場合がございます。
ここではPAY.JPのクライアントサイド(ブラウザ用)JavaScriptライブラリであるpayjp.js v2のAPI仕様を記載します。
基本的な使い方はこちらをご確認ください。
payjp.js v2は、最新のPCI-DSSに準拠したカード情報入力フォーム生成ライブラリです。 同時に、カード情報またはApple Pay on the Webでの決済情報をトークン化するAPIも提供します。
payjp.js v2を利用しなければならない(加盟店が独自で生成するとPCI-DSS準拠とみなされない)入力フォームは、
- カード番号入力欄
- 有効期限入力欄 (月 / 年)
- CVC入力欄
となります。
カードの名義や住所などが必要な場合は、自身でフォームを用意下さい(それらの情報は payjp.createToken()
の引数に渡し、管理することができます)。
動作環境
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 | フォームのplaceholderおよびエラー時のメッセージの言語を指定します。デフォルトはja (日本語)で、他にen (英語)を指定できます。 |
・例
const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')
payjp.getPublicKey()
セットされた公開鍵の文字列を取得します。
payjp.elements(options?: object)
Elements
インスタンスを生成します。
Elements
とは Element
インスタンスを束ねる単位です。
Elements
インスタンス1つにつき、1組のカード情報入力フォームを用意できます。
ページ内に複数のフォームを作りたい場合は、その分だけ Elements
インスタンスを生成ください。
注. 現状、複数の Elements
インスタンスを用意した場合でも、全てのインスタンスに対して同一のlocaleオプションが適用されます。
各フォーム毎に言語を分けることはできませんが、言語の切り替えは、elements.update()
で実現可能です。
・引数
options object
key | 型 | 説明 |
---|---|---|
locale | string | フォームのplaceholderおよびエラー時のメッセージの言語を指定します。デフォルトは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 以外でのみ適用。フォームに指定されたplaceholderを適用 |
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 | フォームのplaceholderおよびエラー時のメッセージの言語を指定します。 |
・例
elements.update({locale: 'en'})
element.mount(domElement: string)
引数を document.querySelector()
で検索し、
その子エレメントに Element
(iframeタグ)を追加することで入力フォームを生成します。
戻り値はありません。
マウント先を囲んでいるlabelタグ、または、マウント先のidを指定したfor属性を持つlabelタグがある場合、そのlabel要素がclickされるとフォームへ自動的にfocusされます。
・引数
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タグに focus()
します。
・例
cardElement.focus()
element.blur()
Element
のinputタグに blur()
します。
・例
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 以外でのみ適用。フォームに指定されたplaceholderを適用 |
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
のように複数ある場合、いずれか一つを指定ください。
options object
トークンを作成API の引数を渡すことができます。
ただし number/exp_month/exp_year/cvc は第1引数の Element
から取得し送信するため、指定できません。
e.g.
- カードホルダーの名義を送信:
{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) {
// handle error
} else {
// response.id is token ID
}
})
payjp.retrieveAvailability(options?: object)
PAY.JPのサーバーと通信し、利用可能なカードブランドを取得します。
・引数
options object
Marketplace型Platformをご利用の方は {tenant: 'tenant_id'}
を指定することを強く推奨します。
指定が必要な理由についてはトークン作成時のテナントIDについてをご参照ください。
・戻り値
card_types_supported
(Array<string>, 利用可能なカードブランドの配列)と livemode
(boolean, ライブモードか否か)を含むオブジェクト、
またはErrorオブジェクトのいずれかでresolveされたPromiseを返します。
・例
payjp.retrieveAvailability({tenant: 'test_tenant'}).then((response) => {
if (response.error) {
// handle 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
3Dセキュア実施対象オブジェクトのID
timeout number
ウィンドウがクローズされるのを待つ時間をミリ秒で指定します。 デフォルトは1800000(30分)
・戻り値
開かれたサブウィンドウが閉じられたタイミングでresolveされるPromiseを返します 3Dセキュアフローが正常に終了した場合、最終ページのjavascriptによりウィンドウは自動的に閉じられます。ユーザー操作によりフローに関係なく閉じられた場合にもresolveされるため、対象オブジェクトの3Dセキュア状態は別途確認する必要があります。 timeoutまでサブウィンドウが閉じられなかった場合はrejectされます。
・例
payjp.openThreeDSecureDialog('ch_1122334455').then(() => {
// 3Dセキュアフロー終了をサーバーに通知
}).catch(() => {
console.log('timeout')
})
Event
element.on(‘change’, listener: function)
Element
のフォームの 'change'
イベントを監視します。
・引数
‘change’ 必須 string
listener 必須 function
第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 | カードの有効期限(月)が過ぎています。 | 上記以外の有効期限不正 |
・例
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
listener 必須 function
第1引数に以下のkeyをもつオブジェクトが渡されます。 戻り値は使われません。
key | 型 | 説明 |
---|---|---|
elementType | string | イベントが起きた Element インスタンスのtype |
element.on(‘focus’, listener: function)
Element
の 'focus'
イベントを監視します。
・引数
‘focus’ 必須 string
listener 必須 function
第1引数に以下のkeyをもつオブジェクトが渡されます。 戻り値は使われません。
key | 型 | 説明 |
---|---|---|
elementType | string | イベントが起きた Element インスタンスのtype |
element.on(‘blur’, listener: function)
Element
の 'blur'
イベントを監視します。
・引数
‘blur’ 必須 string
listener 必須 function
第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
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
textAlign string
text-alignを参照
cardNumber
, cardExpiry
, cardCvc
にのみ効果があります。
textDecoration string
textShadow string
text-shadowを参照
textTransform string
・例
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 |
入力フォームがfocus状態 |
PayjpElement--complete |
適切な入力値がある |
PayjpElement--invalid |
入力値があるが不正 |