更新のおしらせ
この記事ではCheckoutHelperのversion 1を利用しています。
現在ではより新しいバージョンを公開し、セキュリティ、設定の容易さ、UXの点で改善を行っています。
この記事のほか、CheckoutHelperのドキュメントも参考に、ぜひ最新のバージョンをご利用ください。
CheckoutHelperの概要
初週だというのに早々に2度目の投稿です。明日胃カメラを飲む状況ですが、
WebPayのクライアントサイドでのカード番号のトークン化を実現するWebPay.jsのヘルパであるCheckoutHelperの機能を網羅していきたいと思います。
CheckoutHelperは
- 少しのコードでWebPayを導入する
でも触れましたが
CheckoutHelperは数行のHTMLを記述しておくだけで
クレジットカード番号、有効期限のバリデート
クレジットカードの有効性チェック
クレジットカード情報の代替トークン化
をWebPayと直接通信をユーザインタフェースを含め全て行ってくれるWebPay.jsのヘルパーです。
HTML中に
<form action="/purchase" method="post">
<script src="https://checkout.webpay.jp/v1/" class="webpay-button" data-key="test_public_bMj6ai5NZbYSbNraz51jkf7j"></script>
</form>
と書けば
のようなボタンが表示され、クリックすると
が表示され、ユーザがカード情報を入力すると、フォームの情報をバリデートの上、トークンを取得してフォームが送信されます。（このコードだと/purchaseにPOSTリクエストですね）
余談ではありますが、CheckoutHelperの元のコードはCoffeeScript, Haml, Sassで書かれています。
設定可能なパラメータ
ただ貼れてトークンを送信してくれるというだけでは、少し融通が利かない面もあるため、いくつか<script>タグにdata-*なパラメータを設定しておくことで挙動を操ることも出来るようになっています。
ちなみに、data-keyはWebPayの公開可能鍵（トークンの生成にしか使えないキー）をセットしておく必要があります。
data-text / data-submit-text
data-textやdata-submit-textは、
クリックするとカード情報の入力フォームが表示されるボタンや、入力フォームの「カードで支払う」という文字列を変更することが出来ます。
カード情報を登録しておきたいだけで、今すぐ支払うわけじゃなかったり、具体的なことを伝えたかったりする場合にこれらのデフォルトで設定されているテキストが不自然な場合に任意のテキストへ置き換えることが可能です。
- data-text => WEB+DB PRESS vol.76 を購入する
- data-submit-text' => 代金1554円をカードで支払う
というように何だかカード情報が何に使われるかわかるようになっていて安心してWEB+DB PRESS vol.76を購入出来そうな感じが醸されていました。
data-token-name
data-token-nameを使うと取得したトークンがセットされるhiddenなフィールドのパラメータ名を変更することが出来ます。デフォルトではwebpay-tokenとなっていますが、これが微妙に気に入らない場合に変えることが出来ます。
例えば、フォームの送信先がRuby on Railsで、送られて来たパラメータをハンドルする場合にハイフンが好ましくない方もいるでしょう。
シンボル派にとってparams[:"webpay-token"]は何とも辛い（個人の見解）です。
というような場面や、処理上パラメータ名を何らかの規則に合わせたい場合のために準備しています。
data-partial
data-partialは、フォームを自動送信するかどうかを制御出来ます。
例えば、ユーザのプロフィール画面でクレジットカードの情報も編集出来るようなページを想定すると、
名前やメールアドレスなど、他の情報も支払い用のカード情報と一緒にフォームで入力を要求する場合に勝手に送信されてしまうと、ユーザに入力の順番を強制してしまうことになってしまいます。
それを防ぐ為に
<form action="/purchase" method="post">
<script src="https://checkout.webpay.jp/v1/" class="webpay-button" data-key="test_public_bMj6ai5NZbYSbNraz51jkf7j" data-partial="true"></script>
<input type="text" name="other" value="他の情報" />
<input type="submit" value="ユーザが送信するボタン" />
</form>
のように、data-partial="true"を与えることで、カード情報が入力され、トークンが取得されると、カード情報の入力ボタンが
のように変わり、フォーム自体の送信は行われません。
これを再度クリックするとカード情報を再度入力することも可能です（hiddenフィールド上の値は新しいものが発行されるまで削除されません）
動作確認用のサンプルをHerokuで動くようにしているのでお試しください
data-previous-token
data-previous-tokenは既に取得しているトークンを再度埋め込み、カード情報を入力後である「✔ カード情報入力済み」にボタンが変更され、hiddenフィールドにトークンが入れられた状態を再現する為のパラメータです。
（data-partial="true"なことが前提です）
既にトークンは取得したが、送信先で何らかの問題があり再度フォームを表示する場合に、ユーザに財布に戻したばかりのクレジットカードを舌打ちと共に取り出させ、再度カード情報を入力させるのは酷な話です。エラーハンドリングの際には是非ご活用ください。
おわりに
CheckoutHelperの今持てる機能の全てを紹介しました。最初にIE8で全く動かなかった時は涙ものでしたが、ここで紹介する機会に巡り会えて良かったです。
まだまだリリースしたばかりのCheckoutHelperですが、もっと開発者のニーズに合わせて柔軟に機能を持たせていきたいところです。ご使用の際は是非フィードバックを頂けますと幸いです。
渡すはずのバトンは今日も宙を舞いますが、キャッチされることを願って明日6日目へ託します。またお会いしましょう。