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 DEMO

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

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より自由度の高いフォーム設計が可能です。

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

利用方法

例えば、DEMOは以下のコードで生成できます。

<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>
// 公開鍵を登録し、起点となるオブジェクトを取得します
var payjp = Payjp('pk_test_0383a1b8f91e8a6e3ea0e2a9')

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

// element(入力フォームの単位)を生成します
var 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>
var style = {
  base: {
    color: '#198fcc',
    '::placeholder': {
      fontStyle: 'italic',
      color: 'green',
    }
  },
  invalid: {
    color: 'red',
  }
}
var elements2 = payjp.elements()
var 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>
var elements4 = payjp.elements()

// 入力フォームを分解して管理・配置できます
var numberElement = elements4.create('cardNumber')
var expiryElement = elements4.create('cardExpiry')
var 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を用意いただく必要がございます。