PAY ID Checkoutを導入する

PAY ID とは

PAY IDは、メールアドレスとパスワードだけで支払いができるようになる購入用のアカウントです。BASEや各事業者のWebサービスで導入されており、多くの支払いが行われています。

先日、PAY IDリリースから1ヶ月半で10万アカウントを突破いたしました。

www.value-press.com

今回はCheckoutを使ったPAY IDを導入する方法について書きます。

f:id:payjp:20160818095529p:plain

PAY ID を組み込む

PAY IDは通常のPAY.JP APIを利用する方法と同様に導入することができ、シンプルなCheckoutを利用する方法と、より柔軟な設計が可能になるOAuth APIを直接利用する方法の2種類があります。

今回は、Checkoutを利用して組み込む「PAY ID Checkout」について説明します。PAY ID Checkoutでは、下記3つのステップでPAY IDをかんたんに組み込むことができます。

  1. OAuth Clientを作成する
  2. PAY ID Checkoutに組み込む
  3. サーバー側で処理を実行

1. OAuth Clientを作成する

PAY IDではOAuth認証を利用するので、各自でOAuth Clientを作成する必要があります。

OAuth Clientは、PAY.JPにログインしてOAuth 設定画面から作成します。

f:id:payjp:20160818095606p:plain

f:id:payjp:20160818095620p:plain

「Redirect URI」はユーザーの認証完了後に遷移するURLですが、Checkoutではリダイレクトを受ける必要がないため、 http://localhost/ と入力してください。

「Test Mode Client」はテスト用と本番用のOAauth Clientを区別するチェックで、チェックすることでテスト用のOAuth Clientを作成できます。今回はテスト用のOAuth Clientを作成します。

作成が完了したら、OAuth Clientの「詳細」を確認します。PAY ID Checkoutで使うのは「Client ID」になるので、コピーしてください。

f:id:payjp:20160818095642p:plain

f:id:payjp:20160818095705p:plain

2. PAY ID Checkoutに組み込む

Checkoutとは、 <script> タグを1行記述するだけで、 デザインされた決済フォームを生成することができるJavaScriptライブラリです。

Checkoutの <script> タグを追加し、PAY IDの設定を示す data-payjp 属性に、先ほど作成したClient IDをセットすれば、PAY IDが有効化されたフォームが表示されるようになります。

今回はテスト用のOAuth Clientを使うため、 data-key 属性にも pk_test から始まるテスト用のパブリックキーを指定します。本番用のOAuth Clientを使う場合は、本番用のパブリックキーを指定してください。

<form action="/pay" method="post">
  <script
    src="https://checkout.pay.jp/"
    data-key="pk_test_0383a1b8f91e8a6e3ea0e2a9"
    data-payjp="8e23018dc7e9078d8d02db5052dcdda3247e775c">
  </script>
</form>

PAY IDが有効化されたCheckout:

f:id:payjp:20160818105833p:plain

また data-payjp 属性をセットしない場合、PAY IDが無効化された通常のCheckoutが表示されます。

PAY IDが無効化されたCheckout:

f:id:payjp:20160818100922p:plain

3. サーバー側で処理を実行

PAY ID Checkoutでは、通常のCheckoutと同様に、利用されるカード情報はトークン化され、 <input type="hidden" name="payjp-token"> としてフォームに埋め込まれます。このトークンは、通常のCheckoutやPAY.JP APIで生成するトークンと同様に扱うことができ、PAY.JP APIでの支払い処理、顧客情報への紐付けに利用できるので、定期課金などにも柔軟に対応することが可能です。

フォームから受け取ったトークンを使って、サーバー側でAPIを叩くことで後続の処理(支払い処理、顧客情報への紐付けなど)が完了します。 例えば、支払いを行う場合、PAY ID Checkoutで生成されたトークンを使って、サーバー側で下記のようなリクエストを実行します。

$ curl https://api.pay.jp/v1/charges \
  -u sk_test_c62fade9d045b54cd76d7036 \
  -d "amount=500" \
  -d "currency=jpy" \
  -d "card=生成されたトークン"

これだけでPAY IDで支払いができるようになります。テスト用のOAuth Clientを使っているため、 シークレットキーは sk_test から始まるテスト用のものを指定しています。

以上の3ステップで、PAY IDに対応したシステムを作ることができます。

PAY ID をつかう

購入側のPAY IDの実際の利用フローについて説明します。

PAY IDをもっている購入者

フォーム上部の「PAY ID」タブから、メールアドレスとパスワードでPAY IDにログインし、登録済みのカードを選択して支払いを行うことができます。

PAY IDにまだ登録していないカードを利用したい場合は、「カード」タブから新規に利用したいカードを入力し、「PAY IDを登録」にチェックを入れた上、PAY IDで利用しているメールアドレスとパスワードを入力して「カードで支払う」を押せば、入力したカードでの支払い・PAY IDへの新規カードの登録が完了します。

PAY IDをもっていない購入者

フォーム上部の「カード」タブから、利用したいカードを入力します。 同時にPAY ID登録を行う場合、「PAY IDを登録」にチェックを入れ、メールアドレスとパスワードを入力して「カードで支払う」を押せば、入力したカードでの支払い・PAY IDのアカウント登録が完了します。

上記の2種類の決済フローは、テストモードにてご自身の環境でお試しいただくことが可能です。

テストモードでは、

  • メールアドレス、パスワードの組み合わせによらずログインが可能
  • ただしメールアドレスのフォーマット、パスワードの長さの制限は本番と同様に制限されます
  • ログインすると、テスト用のカードが1枚登録済み
  • テスト用のカードを使って、テスト決済に利用出来るトークンが取得可能

のような特徴があります。テスト用のカードについてはPAY.JP APIガイド - テストカードを参考にしてください。

まとめ

以上「PAY ID Checkout」を使ったPAY IDの導入方法についてのチュートリアルでした。

今回はPAY ID Checkoutでしたが、より自由度の高い設計が可能になる、OAuth APIを直接利用する方法も提供しています。OAuth APIについては公式リファレンスがあるので、そちらを参考にしてください。

PAY IDは先述の通り、提供開始から1ヶ月半で10万アカウントを突破し、多くの支払いシーンで利用されています。皆さんもこの機会に是非PAY IDを使ってみてください。

参考

エスケープの仕様変更について

PAY.JP ではこれまで、API, Dashboard から送信されてきたデータはエスケープした上で保存していましたが、2016年6月28日(火) 12:00よりエスケープせずに保存されるように仕様が変更になります。

対象のデータは下記となります。

  • Charge
    • metadata
    • description
    • refund_reason
  • Customer
    • metadata
    • description
  • Card
    • metadata
  • Subscription
    • metadata
  • Plan
    • metadata
    • name

これ以前にすでに保存済みのデータにつきましては、エスケープされたままで送信されます。必要に応じてお客様の側でアンエスケープしていただきますようお願いしたします。

エスケープの仕様について

&<>" および ' を HTML セーフな文字列に変換

入力データ例

<script type="text/javascript">

出力データ(変更前)

&lt;script type=&quot;text/javascript&quot;&gt;

出力データ(変更後)

<script type="text/javascript">

エスケープされているデータが返ってくることを期待しているプログラムがある場合は、ご利用する際にお客様の側でエスケープしていただく必要があります。

ご利用のお客様には大変ご迷惑をお掛け致します。どうぞよろしくお願い致します。

自由なデータを保存できるメタデータ機能追加のお知らせ

こんにちは。Takumaです。

各オブジェクトに任意のデータを持たせたいという皆様からのご要望にお応えして、本日2016年2月22日、メタデータ機能を追加しました。これにより、アップデート可能なオブジェクト(支払い、顧客、カード、プラン、定期課金)にキーバリュー型のデータを保存することが可能になりました。

例えば、請求書番号や注文番号などを支払いオブジェクトのメタデータに保存すれば、それらを特定する度にデータベースへアクセスするという手間が省けます。

利用方法

メタデータを利用するには、対象オブジェクトの作成もしくは更新リクエストに metadata[キー]=バリュー を追加します。なお、一つのオブジェクトには最大20キーまで保存できます。

利用例

支払いオブジェクトに請求書番号を示すinvoice_idというメタデータを持たせることを想定します。

メタデータ作成

以下のサンプルリクエストでは、支払いオブジェクト作成時にinvoice_idというメタデータを保存しています。

curl https://api.pay.jp/v1/charges   \
-u sk_test_c62fade9d045b54cd76d7036: \
-d "customer=takuma"                 \
-d "amount=1117"                     \
-d "currency=jpy"                    \
-d "metadata[invoice_id]=6196452"    \
-XPOST

invoice_idというキーに6196452というバリューのメタデータが保存されました。レスポンスは以下のようになります。

{
  "amount": 1117,
  "amount_refunded": 0,
  "captured": true,
  "captured_at": 1456038882,
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": "JP",
    "created": 1456038819,
    "customer": "takuma",
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2020,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_6d61ddd329c73dfb23e56bdbad0b",
    "last4": "4242",
    "metadata": null,
    "name": "TAKUMA",
    "object": "card"
  },
  "created": 1456038882,
  "currency": "jpy",
  "customer": "takuma",
  "description": null,
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_e04c680174f2b0ecbc14a0839b030",
  "livemode": false,
  "metadata": {
    "invoice_id": "6196452"
  },
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": false,
  "subscription": null
}

"metadata": {"invoice_id": "6196452"} が追加されているのが確認できます。全てのバリューは文字列として保存される点にご注意ください。

メタデータ更新

次に上で作成した支払いオブジェクトのinvoice_idを更新したいとします。その場合は更新リクエストに同キーで新しいバリューのメタデータをのせます。

リクエスト:

curl https://api.pay.jp/v1/charges/ch_e04c680174f2b0ecbc14a0839b030 \
-u sk_test_c62fade9d045b54cd76d7036: \
-d "metadata[invoice_id]=1122334"    \
-XPOST

これで古いinvoice_idである61964521122334に更新されました。

メタデータ削除

最後にこの支払いオブジェクトのinvoice_idを削除したいとします。その場合は更新リクエストに同キーで空バリューのメタデータをのせます。

リクエスト:

curl https://api.pay.jp/v1/charges/ch_e04c680174f2b0ecbc14a0839b030 \
-u sk_test_c62fade9d045b54cd76d7036: \
-d "metadata[invoice_id]="           \
-XPOST

上のリクエストのレスポンスには"metadata": {},が含まれていることが確認できます。これでinvoice_idの削除が完了しました。

メタデータ機能の追加により、各オブジェクトの柔軟性が格段に高くなりました。上記の例は、メタデータ利用方法を解説する為のシンプルなケースですが、サービス内容に合わせて様々な利用の仕方が出来ます。

メタデータに限らずPAY.JP全般の利用方法や仕様について、質問や要望がございましたらフォーラムにて、気軽にご質問ください。

通知設定ができるようになりました

PAY.JPでは以前からWebhookをサポートしていますが、よりお手軽にイベント通知を受信できるように、メールとSlackによる通知設定をリリースしました。 設定はアカウント設定の通知タブから行うことができます。

f:id:payjp:20160218213842p:plain

通知は本番環境のイベントのみが対象となっています。 対象イベントは下記の3種類です。

  • 支払い作成時
  • 定期課金作成時
  • 入金実行時

メール設定では通知先のメールアドレスを、Slack設定ではIncoming Webhook URLとチャンネルを指定し、対象イベントを選択して登録します。

f:id:payjp:20160216191254p:plain

f:id:payjp:20160218213855p:plain

以上の手順で連携した対象に通知が届くようになります。

f:id:payjp:20160216191853p:plain

f:id:payjp:20160216190051p:plain

フォーラム開設のお知らせ

PAY.JPではペイピーの皆様が気軽に質問などを行える場として、2016年1月20日にフォーラムを設置しました。

フォーラムに投稿する内容はPAY.JPに関する内容であれば何でも構いません。開発や技術関連のみではなく、審査に関することや要望など気になる事があれば、どんどん投稿してください。我々PAY.JP運営開発メンバーが回答致します!

ご利用方法

フォーラムにはこちらよりアクセスできます。フィード検索や閲覧はログイン不要でご利用できます。

ログインについて

新しいフィードの投稿または他のフィードに対する回答をする為にはログインが必要です。フォーラムページに右上にある "ログイン" ボタンをクリックしてログインしてください。ログインには各種ソーシャルアカウント(Facebook, Twitter等)が使用できます。フォーラムへのログインはPAY.JPへのログインとは異なりますのでご注意ください。

ご利用に関する注意点

投稿または回答された内容は一般公開されます。その為、以下の点には十分注意した上でフォーラムをご利用ください。

  • 個人の特定できる内容(自他問わず)
  • 他の利用者に対して誹謗中傷など迷惑のかかる投稿(回答)
  • PAY.JPとは関係の無い内容

運営側が不適切と判断した投稿および回答は削除させて頂きますのでご了承ください。なお個人情報が含まれる場合は、お問い合わせより直接ご連絡頂けますようお願い致します。

気にはなるけれど、問い合わせする程でもない疑問や要望などあると思います。そのような痒いところをこのフォーラムを通して取り除いていきますので、どうぞご利用ください。

定期課金プラン変更機能の紹介

こんにちは。PAY.JPのAPIを書いてるTakumaです。

今までは一度作成した定期課金のプランを変更することは出来ませんでしたが、2015年12月2日よりプランの変更が可能になりました。これによりプランのアップグレードやダウングレードがリクエスト一つで手軽に行えます。以下はプラン変更のサンプルリクエストです。

リクエスト:

curl https://api.pay.jp/v1/subscriptions/sub_hi1im1takuma1i7love9you0allx \
-u sk_test_c62fade9d045b54cd76d7036: \
-d plan=pln_9589006d14aad86aafeceac06b60 \
-XPOST

上の例では plan に新しいプランのidを渡すことにより、そのプランへ変更しています。

プラン変更時の挙動

初回課金のタイミング

新しいプランへの課金は変更時に行います。これは新しいプランにtrial_daysやbilling_dayが付いている場合でも変わりません。プラン変更時に改めてトライアル期間を付与したい場合は上のリクエストに -d trial_end=1479340800 と追加する事でトライアル終了時を指定することが出来ます。

初回課金額と新しい課金周期

上記の通り、プラン変更時の課金は即時行われます。その時の課金金額は新しいプラン金額で、変更時を基点に新しく一ヶ月の課金周期が設定されます。新しいプランにbilling_dayが付いている場合も即時課金が行われますが、次回更新時は直近の課金日になります。後述の日割りを適用することにより、この挙動を変える事が出来ます。

プラン変更での日割り適用

定期課金日割り機能の紹介では課金日が指定されている定期課金作成時の課金額に日割りを適用する方法を紹介しました。プラン変更時にも同様に日割りを適用させる事ができます。

適用方法

上のリクエストに -d prorate=true と追加する事で日割りを適用させる事が出来ます。

日割り適用時の初回課金額と新しい課金周期

日割りが有効の場合、課金周期を変えずに更新日までの日数分だけ課金します。また、新しいプランにbilling_dayがある場合、直近の課金日までの日数分を課金します。計算方法について詳しくはこちらの記事を参照ください。

未使用日数分の返金

日割りが有効の場合、古いプランの金額に対して、残っている課金周期日数分の金額を返金します。返金額の計算方法は基本的に課金時のと同じですが、当日分は返金額に加算されません。

例えば、古いプランの金額が1,000円で、課金周期期間が11月1日から12月1日までの30日間、プラン変更日が11月17日だとします。周期開始日(11月1日)からプラン変更時(11月17日)までの日数(当日含め)は17日なので、残りの日数である13日(11月18日から12月1日まで)が返金対象です。30日のうち13日を返金するので、この場合の返金額は 1,000円 x 13 / 30 = 433円となります。

プラン変更と日割り機能を組みわせて利用する事により、煩わしい課金/返金額の計算から実行までを全てPAY.JPに任せる事が出来ます。支払いに関わる部分は出来る限りPAY.JPに任せる事で、デベロッパーのみなさんがサービスの開発に集中出来る事を願ってます。

PostCSSの基本的なところ

フロントエンドエンジニアの @7jin16 です。

今回は最近フロントエンド界隈でよく耳にするPostCSSの基本的な部分を書こうと思います。 PAY.JPでも導入しているので、PostCSSってなんだろうって方の参考になればとても嬉しいです。

PostCSSとは

PostCSSの公式ページにも書かれていますが、一言で説明すると『CSSを変換するために書かれたnode.js製のパーサー』です。 Google や Twitter、阿里巴巴やShopifyも使っているとのこと。

PostCSS is a tool for transforming styles with JS plugins. These plugins can lint your CSS, support variables and mixins, transpile future CSS syntax, inline images, and more. PostCSS is used by industry leaders including Google, Twitter, Alibaba, and Shopify. The Autoprefixer PostCSS plugin is one of >the most popular CSS processors.

PostCSS自体は、AST(Abstract Syntax Tree)を操るAPIを提供していて、そこに細かいプラグインが乗っかっているというイメージです。 パフォーマンスも非常によく、ruby-SassやLess よりも速いらしいです。

postcss/benchmark · GitHub

どんなプラグインがあるのか

  • autoprefixer - ベンダープレフィックスをつけてくれます
  • precss - mixinやextendなどのSassライクな記法を使えるようにしてくれます。
  • cssnano - minify含め、いろいろと良しなにやってくれます。
  • cssnext - 策定途中で、現状のブラウザでは未実装の記法をトランスパイルしてくれます。
  • chinese stylesheets - 中国語でStyleを書くことができるようになります。
  • postcss-style-guide - Styleガイドラインを作ってくれます。

中国語でStyleを書けるなど、ネタ系プラグインも出てきているので良くも悪くも勢いがあるなぁと感じますね。

どうやって使うのか

まずはインストール。

$ npm install --save-dev gulp-postcss

次に使用しているタスクランナーにあわせてタスクを書きます。

gulp.js

//使いたいプラグインをrequireする
var postcss = require('gulp-postcss');
var autoprefixer = require('autoprefixer');

gulp.task('styles', => {
  var processors = [
    autoprefixer({browsers: ['last 1 version']}),
  ];
  return gulp.src([
    '/css/style.css',
  ])
  .pipe(postcss(processors))
  .pipe(gulp.dest('build/css'))
});

こんな風に各プラグインを使うことができます。

記事中に紹介したプラグイン以外も PostCSS Partsというサイトで探せるので探してみてください。 PostCSS.parts | A searchable catalog of PostCSS plugins