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()の引数に渡すことで管理できます）。

動作環境Copy Anchor Link

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

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

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

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

APICopy Anchor Link

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

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

Payjp(publicKey: string, options?: object)Copy Anchor Link

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

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

引数

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

例

const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')

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

payjp.getPublicKey()Copy Anchor Link

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

payjp.elements(options?: object)Copy Anchor Link

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

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

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

引数

• options

例

const elements = payjp.elements()

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

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

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

引数

• type

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

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

• options

例

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

elements.getElement(type: string)Copy Anchor Link

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

引数

• type : elements.create() の引数欄を参照

戻り値

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

例

const cardElement = elements.getElement('card')

elements.update(options?: object)Copy Anchor Link

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

引数

• options

例

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

element.mount(domElement: string)Copy Anchor Link

引数を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)Copy Anchor Link

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

element.addEventListener(event: string, listener: function)Copy Anchor Link

element.on() と同じです。

element.focus()Copy Anchor Link

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

例

cardElement.focus()

element.blur()Copy Anchor Link

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

例

cardElement.blur()

element.clear()Copy Anchor Link

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

例

cardElement.clear()

element.unmount()Copy Anchor Link

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

例

cardElement.unmount()

element.update(options)Copy Anchor Link

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

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

引数

• options

例

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

payjp.createToken(element: Element, data?: object = , options?: object = )Copy Anchor Link

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

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

引数

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

戻り値

トークンを作成 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)Copy Anchor Link

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

引数Copy Anchor Link

• options :

戻り値Copy Anchor Link

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

例Copy Anchor Link

以下のコードは、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)Copy Anchor Link

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

引数Copy Anchor Link

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

戻り値Copy Anchor Link

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

例Copy Anchor Link

以下のコードは、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)Copy Anchor Link

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

引数Copy Anchor Link

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

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

戻り値Copy Anchor Link

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

例Copy Anchor Link

以下のコードは、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オブジェクト)
})

EventCopy Anchor Link

element.on('change', listener: function)Copy Anchor Link

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

引数Copy Anchor Link

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

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

例Copy Anchor Link

以下のコードは、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)Copy Anchor Link

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

引数Copy Anchor Link

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

element.on('focus', listener: function)Copy Anchor Link

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

引数Copy Anchor Link

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

element.on('blur', listener: function)Copy Anchor Link

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

引数Copy Anchor Link

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

styleオブジェクトCopy Anchor Link

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プロパティCopy Anchor Link

• 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を参照

例Copy Anchor Link

以下のコードは、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コンテナCopy Anchor Link

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

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

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