トークン決済

WebPayのユーザがクレジットカード情報を極力取り扱わなくて良いように、その代替となるトークンを用いるしくみを提供しています。

カード利用者のパソコンやスマートフォンから直接WebPayと通信を行って得られたトークンをサーバサイドに送信することで、 クレジットカード情報をサーバサイドに伝送、サーバサイド上で処理しなくて済みます。

右図のとおり、クレジットカード情報は加盟店のユーザからWebPayへの通信でしか伝送されず、 WebPayのユーザは一切クレジットカード情報に触れることなく、課金の処理を行うことができます。 なお、クライアントサイドからWebPayの通信では必ず伝送する情報の暗号化を行っています。

Payments_with_token

トークンの作成

さまざまな環境で最小限のプログラミングでトークン機能を利用できるよう、以下のライブラリを用意しています。

CheckoutHelper
カード情報の入力フォームの処理とトークン化を行う、JavaScriptのライブラリです。数行のHTMLコードだけで導入できます。
WebPay.js
トークン化ための通信機能だけを提供する、シンプルなJavaScriptライブラリです。 CheckoutHelperより細かなカスタマイズをしたい場合や、CheckoutHelperが動作しない場合にご利用ください。
webpay-token-ios
スマートフォンアプリケーションに埋め込める、iOS向けのライブラリです。 利用方法については 開発者ブログでの記事 をご覧ください。
webpay-token-android
スマートフォンアプリケーションに埋め込める、Android向けのライブラリです。 利用方法については 開発者ブログでの記事 をご覧ください。

トークンの使用

サーバサイドにクレジットカード情報を直接送信しないために、 トークン(Token)オブジェクト を使用します。 WebPayへの送信の際にcardパラメータへトークンのidが渡された場合、クレジットカードの情報と同等の入力があったものとして扱われます。 例えば、トークンのidを tok_fBvfz0c2N5V1guv だとした場合、

課金を行う(Chargeを作成する)とき

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

顧客の情報を保存する(Customerを作成する)とき

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

というように利用することが出来ます。

なお、一度送信に使用したトークンは無効となり、二度と使えなくなります。(オブジェクトの used プロパティは true となります。)

WebPay.jsの使用方法

ウェブアプリケーションにおけるトークン化のために、JavaScriptライブラリWebPay.jsを提供しています。

WebPay.jsはHTML上で

<script type="text/javascript" src="https://js.webpay.jp/v1/"></script>

として利用することが出来ます。トークンの作成はJavaScriptで

WebPay.setPublishableKey("test_public_19DdUs78k2lV8PO8ZCaYX3JT");
WebPay.createToken({
  number: "4242-4242-4242-4242",
  name: "KENGO HAMASAKI",
  cvc: "123",
  exp_month: "12",
  exp_year: "2015"
}, webpayResponseHandler);

とすることで行われます。この時 setPublishableKey で与えている文字列は テスト環境用公開可能鍵で、トークンの作成以外には利用することが出来ません。 また、 webpayResponseHandler にはHTTP(S)のステータスコードとレスポンスが引数としてコールバックが行われます。

ステータスコードについては APIドキュメント を参照してください。 リクエストに成功するとレスポンスには、 トークン(Token)オブジェクト が返されます。これらの情報を含むレスポンスをハンドリングして、サーバサイドにトークンのidを送るなどの処理を行ってください。例を以下に示します。

WebPay.createToken のレスポンスをハンドルする例

以下の例は、DOMの操作を簡便にするために jQuery の利用を前提としています。

var webpayResponseHandler = function(status, response) {
  var form = $("#payment-form");
  if (response.error) {
    // 必要に応じてエラー処理を入れてください
    form.find("button").prop("disabled", false);
  } else {
    // 伝送させたくない情報をフォームから削除する
    $(".card-number").removeAttr("name");
    $(".card-cvc").removeAttr("name");
    $(".card-expiry-year").removeAttr("name");

    var token = response.id;
    var input = document.createElement("input");
    input.type = "hidden";
    input.name = "token";
    input.value = token;
    $(input).appendTo(form);

    form.get(0).submit();
  }
};

レスポンスに応じてエラーを処理して、正しくトークンの情報を得られた場合に、必要のないフォームの情報を削除した上で、 トークンのidをフォームに含めてから送信しています。 これで受け取ったサーバサイドでは先に述べたように、cardパラメータにトークンのidを与えて利用します。

また、 CheckoutHelper を利用すれば、WebPay.jsを直接用いずに数行のHTMLを記述するだけでフォームの表示、カードに関する入力情報のチェック、トークンの作成と送信を行うことができます。

WebPay.jsで提供している機能

下記の表に記載のないメソッドやパラメータは非公開APIです。予告なく機能を変更することがありますので利用する場合はご注意下さい。

メソッド/パラメータ 説明
WebPay.setPublishableKey(
  publishableKey:string
)
WebPayとの通信に用いる公開可能鍵を設定します。 公開可能鍵は設定画面で確認できます。
WebPay.createToken(
  card:object
  callback:function
)
入力されたカード情報をトークン化するAPIを呼び出します。
WebPay.setLanguage(
  lang:string
)
WebPayからのレスポンスの言語を、2文字の言語コードで設定します。 現在 "en" , "ja" が利用できます。デフォルトは "en" です。
WebPay.retrieveAvailability(
  callback:function
)
利用しているWebPayアカウントで利用可能な通貨、カードブランドを取得するAPIを呼びだします。結果はcallback関数に (statusCode:number, result:object) を引数として与えられます。 result は次のような値です。
{
  currencies_supported: ["jpy"]
  card_types_supported: ["Visa", "American Express", "MasterCard", "JCB", "Diners Club"]
}
WebPay.validateCardNumber(
  cardNumber:string,
  cardTypesSupported:array = null
)
ユーザが入力したカード番号のフォーマットを検証します。 カード番号の文字列を引数に呼び出し、検証に成功したら true が、失敗したら false が返ります。 オプショナル引数 cardTypesSupported にカードブランド名("Visa", "American Express", "MasterCard", "JCB", "Diners Club")の配列を与えることで、 指定したブランドのいずれかが発行しているカードであるかを合わせて検証できます。
WebPay.validateCVC(
  cvc:string
)
ユーザが入力したCVCのフォーマットを検証します。 CVCの文字列を引数に呼び出し、検証に成功したら true が、失敗したら false が返ります。
WebPay.validateExpiry(
  month:number,
  year:number
)
ユーザが入力した有効期限を検証します。 year は4桁(例:2014)にしてください。 検証に成功したら true が、失敗したら false が返ります。
WebPay.validateName(
  name:string
)
ユーザが入力した名前を検証します。 検証に成功したら true が、失敗したら false が返ります。
WebPay.testMode この変数に true を設定すると、テストモードが有効になります。 テストモードではWebPay.jsは外部との通信を行いません。 ライブラリ内で作成したダミーのレスポンスを返します。