Subscribed unsubscribe Subscribe Subscribe

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

こんにちは。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全般の利用方法や仕様について、質問や要望がございましたらフォーラムにて、気軽にご質問ください。