こんにちは。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である6196452は1122334に更新されました。
メタデータ削除
最後にこの支払いオブジェクトの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全般の利用方法や仕様について、質問や要望がございましたらお問い合わせよりお気軽にご連絡ください。