CheckoutHelper

CheckoutHelperはカード情報の入力フォームの処理と クライアントサイドでのカード情報のトークン化 を行える、JavaScriptのライブラリです。

このライブラリをフォーム中から読み込むように数行のHTMLを記述するだけで、 カードに関する入力情報のバリデートと、カード情報を直接取り扱わないセキュアな形で決済に利用出来るトークンを取得し、サーバサイドに送信することができます。

デモ

以下の「CheckoutHelperでカード情報を入力を試す」をクリックすると、カード入力フォームが表示されます。 表示されたフォームには

  • カード番号: 4242 4242 4242 4242
  • 有効期限: 08 / 18
  • カード名義: TARO YAMADA
  • セキュリティコード: 123
と入力して、「トークンを作成してみる」をクリックしてください。カード情報によるトークンが作成された後自動でフォームの送信が行われます。

使い方

CheckoutHelperは、HTML上で

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

と書くだけで設置できます。 data-key には ユーザの公開可能鍵 を利用します。この例では、 /purchasewebpay-token パラメータの値としてトークンが送られるので、これ(コード中では [created token] としています)を受け取るサーバ側では、 課金を行うなら

$
curl "https://api.webpay.jp/v1/charges" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-d "amount=1554" \
-d "currency=jpy" \
-d "card=[created token]"
>>
require 'webpay'
webpay = WebPay.new('test_secret_eHn4TTgsGguBcW764a2KA8Yd')
webpay.charge.create(
   amount: 1554,
   currency: "jpy",
   card: "[created token]"
)
php >
require "vendor/autoload.php";
use WebPay\WebPay;
$webpay = new WebPay('test_secret_eHn4TTgsGguBcW764a2KA8Yd');
$webpay->charge->create(array(
   "amount"=>1554,
   "currency"=>"jpy",
   "card"=>"[created token]"
));
>
import jp.webpay.webpay.WebPay;
WebPay webpay = new WebPay("test_secret_eHn4TTgsGguBcW764a2KA8Yd");
webpay.charge.createRequest()
        .amount(1554)
        .currency("jpy")
        .card("[created token]")
        .execute();
>>>
import webpay
client = webpay.WebPay('test_secret_eHn4TTgsGguBcW764a2KA8Yd')
client.charge.create(amount=1554, currency="jpy", card="[created token]")
>
var WebPay = require('webpay');
webpay = new WebPay('test_secret_eHn4TTgsGguBcW764a2KA8Yd');
webpay.charge.create({
  amount: 1554,
  currency: "jpy",
  card: "[created token]"
}, function(err, res) { ... });

として、すぐに課金を行えます。

また、後から定期課金などで何度も利用したり、違うタイミングで課金をするつもりなら

$
curl "https://api.webpay.jp/v1/customers" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-d "card=[created token]"
>>
require 'webpay'
webpay = WebPay.new('test_secret_eHn4TTgsGguBcW764a2KA8Yd')
webpay.customer.create(card: "[created token]")
php >
require "vendor/autoload.php";
use WebPay\WebPay;
$webpay = new WebPay('test_secret_eHn4TTgsGguBcW764a2KA8Yd');
$webpay->customer->create(array("card"=>"[created token]"));
>
import jp.webpay.webpay.WebPay;
WebPay webpay = new WebPay("test_secret_eHn4TTgsGguBcW764a2KA8Yd");
webpay.customer.createRequest()
        .card("[created token]")
        .execute();
>>>
import webpay
client = webpay.WebPay('test_secret_eHn4TTgsGguBcW764a2KA8Yd')
client.customer.create(card="[created token]")
>
var WebPay = require('webpay');
webpay = new WebPay('test_secret_eHn4TTgsGguBcW764a2KA8Yd');
webpay.customer.create({card: "[created token]"}, function(err, res) { ... });

として、カード情報を結びつけた顧客オブジェクトを保存しておくことができます。

フォーム中に埋め込む場合(自動送信を行わない)

カード情報の入力だけでなく、他の情報もフォームから送信をする場合にカードの情報の入力次第で自動送信を行われては困ることがあるでしょう。そのような場合、

<form action="/purchase" method="post">
  <script src="https://checkout.webpay.jp/v3/" class="webpay-button" data-key="test_public_19DdUs78k2lV8PO8ZCaYX3JT" data-lang="ja" data-partial="true"></script>
  <input type="text" name="other" value="他の情報" />
</form>

というように data-partial="true" と設定することで自動的な送信を止めることができます。トークンの取得後、ボタンには ✔ カード情報入力済み と表示され、フォーム自体は送信されません。

設定可能なパラメータ

CheckoutHelperを柔軟に利用するために以下のパラメータを利用することが出来ます。

パラメータ名 説明 既定値
data-key (必須) あなたのアカウントの公開可能鍵 test_public_19DdUs78k2lV8PO8ZCaYX3JT なし
data-partial true と設定することで、カード情報フォーム入力後の自動的な送信を行わない false
data-text ページ上に表示されるカード情報入力フォームを開くためのボタンのテキスト data-partial="false" のとき「カードで支払う」
data-partial="true" のとき「カード情報を入力する」
data-submit-text カード情報入力フォームのボタンのテキスト data-partial="false" のとき「カードで支払う」
data-partial="true" のとき「カード情報を送信する」
data-token-name 作成されたトークンが挿入されるhiddenなinputのname webpay-token
data-previous-token エラーにより戻ってきた場合など、ユーザに再入力をさせないために作成済みのトークンを入れるパラメータ
自動送信が行われない設定 data-partial="true" になっていることが前提
なし
data-lang サーバからのエラーメッセージなどを表示する言語 jaen が利用可能 en
data-on-created トークンの生成に成功し、フォームの値が設定された直後に、生成したトークンデータを引数に呼び出される関数。関数名で指定。自動送信を行う設定 data-partial="false" になっていることが前提
指定された関数が false を返した場合は、自動送信を行わずに処理を終了する
なし
data-on-failed トークンの生成に失敗した時に、HTTPステータスコードを第一引数、エラーの内容を第二引数として呼び出される関数。関数名で指定 なし

利用上の注意点

  • 最新版のChrome, FireFox, SafariおよびInternet Explorer 9以降で動作します
  • モバイル環境については、iOS7での最新版のSafari, Android4.0以降での最新版のChrome, Firefox, デフォルトブラウザ(com.android.browser)で動作します
  • スタイルシートによりフォームのデザイン等へ変更を加えることは可能ですが、レイアウトやDOMの名称、構成を予告無く変更する場合がありますのでご注意ください
  • HTTPS(SSL)を用いてWebPayとの通信を行いますが、CheckoutHelperが埋め込まれるページもHTTPSでの公開を行うようにしてください
  • 文字エンコーディングがUTF-8のページへの設置を前提としております。 charset="UTF-8" とscriptタグで指定することでそれ以外のエンコーディングのページでも動作致しますが、正しく動作することを保証しておりません
  • どちらの使用方法の場合でも、1ページ内に設置できるCheckoutHelperは1つのみです。複数の支払いフォームを設置する場合はJavaScript向けライブラリWebPay.jsをご利用ください。