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

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

定期課金日割り機能の紹介

PAY.JPの定期課金では課金日の指定を行うことができます。例えば毎月1日に課金を実行したい場合はプランに billing_day=1 と指定することで、定期課金の作成日時に関わらず毎月1日の午前9時に課金が実行されます。

この場合、初回課金のタイミングは作成時ではなく直近の課金実行日というのが現在のデフォルト仕様です。その為、初回課金時の前に定期課金を停止、キャンセル、もしくは削除した場合、課金が一度も行われることなくサービスを提供してしまう期間が発生します。

初回課金額の日割り

上記の挙動を回避する為、課金日が指定してある場合でも定期課金作成時にプラン料金の日割り計算を行い、初回課金を即実行するオプション prorate が2015年12月2日より使えるようになりました。以下が日割り計算課金を行うリクエストの例です。

リクエスト:

curl https://api.pay.jp/v1/subscriptions     \
-u sk_test_c62fade9d045b54cd76d7036:         \
-d customer=cus_4df4b5ed720933f4fb9e28857517 \
-d plan=pln_9589006d14aad86aafeceac06b60     \
-d prorate=true

prorate=true とする事で日割り計算を有効化しています。この例ではプランにトライアル期間が設定されていない限り、必ず作成時に課金を実行します。

日割り額の計算方法

日割り金額は定期課金作成日から直近課金日までの日数、および直前課金日から直近課金日までの日数を元に算出します。

例えばプラン金額が1,000円、課金日が1日、課金作成日が11月17日だとします。この場合、作成日(11/17)から次の課金日(12/1)までの日数は14日です。また直前の課金日は11月1日なので次の課金日(12/1)までの日数は30日です。30日のうち14日分を課金するので、日割りによる課金額は1,000円 x 14 / 30 = 466円となります。

サービスの種類や金額などに応じて日割りの有効無効を切り替えることにより、柔軟に定期課金の管理を行うことが出来ます。ぜひご利用ください。