payjp.js v2 ガイド

payjp.js v2のデフォルトのフォームデザインは、予告なく修正される場合があります。

ここでは、PAY.JP のクライアントサイド（ブラウザ用）JavaScript ライブラリである payjp.js v2 の概要を説明します。

API リファレンスはこちらをご確認ください。

payjp.js v2とは

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

payjp.js v2 デモ

枠線内の部分がライブラリの提供箇所となります。

v1との違い

v1 ではトークン化 API のみを提供しており、カード情報入力フォームは加盟店側で用意する必要がありました。

しかし、より安全なクレジットカード商取引のために、最新の PCI-DSS では、カード情報入力フォームを決済代行業者側で用意することが求められています。

対象となる入力フォームは以下の通りです。

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

payjp.js v2 では、これらのフォームを弊社ドメインの iframe 内に用意し、独自スタイルの適用・イベント監視など v1 で実現できた機能を提供します。さらに、カード番号入力時の自動フォーマットやレスポンシブデザインなど、ニーズの高かった機能をデフォルトで提供します。

PCI-DSSへの準拠

payjp.js v2 またはCheckoutをご利用の場合、最新の PCI-DSS に準拠するために加盟店側で追加の対応は不要です。

v1 をご利用の場合、今後、加盟店側で PCI-DSS の認定を受けていただくことが必要になる可能性があります。

必要事項（予定）

PCI-DSS SAQ(Self-Assessment Questionnaire, 自己問診) A-EPの問診結果の提出（年次）
認定スキャニングベンダー(ASV)による加盟店システムのサイトスキャン
訪問審査（年間600万件以上処理する場合のみ）

payjp.js(v1)からの移行について

PAY.JP ドメインの iframe 上にフォームを用意する都合上、payjp.js(v2)では以下の制限があります。

制限事項	代替機能
顧客のカード情報（カード番号・有効期限・CVC）の取得	PCI-DSS 準拠のため、フォームに入力されたカード情報を取得することはできません。createToken 実行前のタイミングでは、 change イベントから現在入力されているカードのブランド判定情報を取得できます
CSS ファイルや style タグから入力フォームにスタイルを適用する	こちらの方法でスタイルを適用可能です
DOM イベントの監視	`change`, `focus`, `blur` など重要なイベントは間接的に監視可能です。こちらをご参照ください

Checkoutとの違い

Checkoutより自由度の高いフォーム設計が可能です。

独自のデザインを適用できます
ユーザーアクションに応じた各種イベントを取得できるため、インタラクティブなフォームを作成できます

利用方法

たとえば、デモは以下のコードで生成できます。

<script src="https://js.pay.jp/v2/pay.js"></script>
<style>
/* 必要に応じてフォームの外側のデザインを用意します */
div.payjs-outer {
  border: thin solid #198fcc;
}
</style>
<div id="v2-demo" class="payjs-outer">
  <!-- ここにフォームが生成されます -->
</div>
<button onclick="onSubmit(event)">トークン作成</button>
<span id="token"></span>
<script>
// 公開鍵を登録し、起点となるオブジェクトを取得します
const payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')

// elementsを取得します。ページ内に複数フォームを用意する場合は複数取得してください
const elements = payjp.elements()

// element(入力フォームの単位)を生成します
const cardElement = elements.create('card')

// elementをDOM上に配置します
cardElement.mount('#v2-demo')

// ボタンが押されたらtokenを生成する関数を用意します
function onSubmit(event) {
  payjp.createToken(cardElement).then(function(r) {
    document.querySelector('#token').innerText = \
       r.error ? r.error.message : r.id
  })
}
</script>

独自デザインの適用

こちらの形式で、Element にスタイルを指定できます。

<div id="v2-styled" class="payjs-outer"></div>
<script>
const style = {
  base: {
    color: '#198fcc',
    '::placeholder': {
      fontStyle: 'italic',
      color: 'green',
    }
  },
  invalid: {
    color: 'red',
  }
}
const elements2 = payjp.elements()
const cardElement2 = elements2.create('card', {style: style})
cardElement2.mount('#v2-styled')
</script>

イベント

入力されたカード情報のうち、カードブランド情報などはイベントを通じて取得できます。

cardElement.on('change', (e) => {
  document.querySelector('#brand').innerText = e.brand
  document.querySelector('#empty').innerText = e.empty
  document.querySelector('#complete').innerText = e.complete
  document.querySelector('#error').innerText = JSON.stringify(e.error)
})

brand=?, empty=?, complete=?, error=?

入力フォームの分割

より自由度の高いデザインのために、入力フォームをカード番号/有効期限/CVC の3つの最小単位に分割して配置も可能です。

この方法を利用する場合、ブランドロゴ表示などの機能は提供されませんので、必要に応じてご自身で用意してください。

<div id="number-form" class="payjs-outer">
  <!-- ここにカード番号入力フォームが生成されます -->
</div>
<div id="expiry-form" class="payjs-outer">
  <!-- ここに有効期限入力フォームが生成されます -->
</div>
<div id="cvc-form" class="payjs-outer">
  <!-- ここにCVC入力フォームが生成されます -->
</div>
<button onclick="onSubmit2(event)">トークン作成</button>
<span id="token2"></span>
<script>
const elements4 = payjp.elements()

// 入力フォームを分解して管理・配置できます
const numberElement = elements4.create('cardNumber')
const expiryElement = elements4.create('cardExpiry')
const cvcElement = elements4.create('cardCvc')
numberElement.mount('#number-form')
expiryElement.mount('#expiry-form')
cvcElement.mount('#cvc-form')

// createTokenの引数には任意のElement1つを渡します
function onSubmit2(event) {
  payjp.createToken(numberElement).then(function(r) {
    document.querySelector('#token2').innerText = \
      r.error ? r.error.message : r.id
  })
}
</script>

IE11対応

前提として、Checkout および payjp.js v1 および v2 は IE11 をサポートしていません。

payjp.js v2 は非同期処理インターフェースを Promise で提供しており、IE11 で動作させるためには加盟店側で Polyfill を用意していただく必要があります。