CheckoutHelperを使いこなす

本記事はWebPayのCheckoutHelperを使いこなす - Qiitaの再録です。 Qiitaの方はWebPay Advent Calendar 2013のものであるため当時の状態を維持し こちらの記事では最新の情報に合わせて加筆、編集を加えております。

CheckoutHelperの概要

WebPayのクライアントサイドでのカード番号のトークン化をコード一行で導入できるCheckoutHelperの機能を網羅していきたいと思います。 CheckoutHelperの公式ドキュメントもあわせて参考にしてください。

CheckoutHelperは - 少しのRubyのコードでWebPayを導入する でも触れましたが

CheckoutHelperは数行のHTMLを記述しておくだけで

  • クレジットカード情報のバリデート
  • クレジットカードの有効性チェック
  • 利用可能なカード種類の判別
  • クレジットカード情報の代替トークン化

をWebPayと直接通信をユーザインタフェースを含め全て行ってくれるWebPay.jsのヘルパーです。

HTML中に

1
2
<form action="/purchase" method="post">
  <script src="https://checkout.webpay.jp/v2/" class="webpay-button" data-key="test_public_bMj6ai5NZbYSbNraz51jkf7j" data-lang="ja"></script>

と書けば

images

のようなボタンが表示され、クリックすると

images

が表示され、ユーザがカード情報を入力すると、フォームの情報をバリデートの上、トークンを取得してフォームが送信されます。(このコードだと/purchasePOSTリクエストですね)

余談ではありますが、CheckoutHelperの元のコードはCoffeeScript, Haml, Sassで書かれています。

設定可能なパラメータ

ただ貼れてトークンを送信してくれるというだけでは、少し融通が利かない面もあるため、いくつか<script>タグにdata-*なパラメータを設定しておくことで挙動を操ることも出来るようになっています。

ちなみに、data-keyはWebPayの公開可能鍵(トークンの生成に関連するAPIにしか使えないキー)をセットしておく必要があります。

data-text / data-submit-text

data-textdata-submit-textは、 クリックするとカード情報の入力フォームが表示されるボタンや、入力フォームの「カードで支払う」という文字列を変更することが出来ます。

カード情報を登録しておきたいだけで、今すぐ支払うわけじゃなかったり、具体的なことを伝えたかったりする場合にこれらのデフォルトで設定されているテキストが不自然な場合に任意のテキストへ置き換えることが可能です。

少しのRubyのコードでWebPayを導入するで作成したサンプルアプリケーションでは、

  • 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は、フォームを自動送信するかどうかを制御出来ます。 例えば、ユーザのプロフィール画面でクレジットカードの情報も編集出来るようなページを想定すると、 名前やメールアドレスなど、他の情報も支払い用のカード情報と一緒にフォームで入力を要求する場合に勝手に送信されてしまうと、ユーザに入力の順番を強制してしまうことになってしまいます。

それを防ぐ為に

1
2
3
4
5
<form action="/purchase" method="post">
  <script src="https://checkout.webpay.jp/v2/" class="webpay-button" data-key="test_public_bMj6ai5NZbYSbNraz51jkf7j" data-lang="ja" data-partial="true"></script>
  <input type="text" name="other" value="他の情報" />
  <input type="submit" value="ユーザが送信するボタン" />
</form>

のように、data-partial="true"を与えることで、カード情報が入力され、トークンが取得されると、カード情報の入力ボタンが

images

のように変わり、フォーム自体の送信は行われません。 これを再度クリックするとカード情報を再度入力することも可能です(hiddenフィールド上の値は新しいものが発行されるまで削除されません)。

動作確認用のサンプルをHerokuで動くようにしているのでお試しください。

data-previous-token

data-previous-tokenは既に取得しているトークンを再度埋め込み、カード情報を入力後である「✔ カード情報入力済み」にボタンが変更され、hiddenフィールドにトークンが入れられた状態を再現する為のパラメータです。 data-partial="true"とあわせてご利用ください。

既にトークンは取得したが、送信先で何らかの問題があり再度フォームを表示する場合に、ユーザに財布に戻したばかりのクレジットカードを舌打ちと共に取り出させ、再度カード情報を入力させるのは酷な話です。エラーハンドリングの際には是非ご活用ください。

data-lang

カードの情報が誤っていたり、使えない場合にユーザに表示されるエラーメッセージの言語を指定します。 エラーメッセージは各言語で購入者にもわかりやすいように書かれています。 現在指定できる言語は"en"と"ja"です。

指定しなかったときのデフォルトは"en"です。 英語のメッセージが表示されると購入者がアレッと思ってしまいますので、日本語のサービスを作成している場合は忘れずdata-lang="ja"を指定しましょう。

data-on-created

トークンの生成に成功し、フォームの値が設定された直後に、生成したトークンデータを引数に呼び出される関数を指定します。 JavaScriptコードなどではなく、関数名を指定してください。

自動送信を行う設定(data-partial="false")になっており、かつ関数がfalseを返した場合は、自動送信を行わずに処理を終了します。 カード情報入力インタフェースはあるものを使いたいけど、入力後の動作はこまかくカスタマイズしたい開発者におすすめです。

data-on-failed

data-on-createdと対になる存在です。 トークンの生成に失敗した時に、HTTPステータスコードを第一引数、エラーの内容を第二引数として呼び出される関数を指定します。

おわりに

CheckoutHelperを利用するとJavaScriptの高度な知識がなくても簡単に安全な決済機能を導入できます。 CheckoutHelperの今持てる機能の全てを紹介しました。

もっと開発者のニーズに合わせて柔軟に機能を持たせていきたいところです。 ご使用の際は是非フォーラムなどにフィードバックを頂けますと幸いです。