curl APIドキュメント

このAPIは REST を基本に構成しています。つまりは、開発者にとって予測可能で、リソース指向のURLを用い、HTTPレスポンスコードをAPIエラーの表示に用い、HTTP認証等のHTTPの機能に沿った実装を行っています。つまり、HTTP通信が利用できるあらゆるクライアント・技術で簡単に本APIを利用することが可能です。全てのAPIによるレスポンスはエラーも含めて、 JSON 形式で返します。

このAPIを最大限楽しめるように、商用モードのAPIキーだけでなく、全てのユーザーはテストモードのAPIキーを利用することができます。テストモードのAPIキーを用いることで、実際のクレジットカードへの課金や手数料の支払い等を行うことなく、全てのAPIの機能を試すことができます。

WebPayのAPIには、課金や顧客の説明など、ユーザーが値を自由に設定できる項目が含まれます。 これらの項目をAPI経由で取得した場合、すべての値はそのままエスケープされずに返されます。 自由設定項目をHTMLページに表示したりSQL内で利用する場合、文字列を適切にエスケープしないと、セキュリティ上の問題をひきおこす場合がありますので、十分ご注意ください。

APIエンドポイント

https://api.webpay.jp

リソースURLパターンの概要

  • /v1/charges
  • /v1/charges/{CHARGE_ID}
  • /v1/customers
  • /v1/customers/{CUSTOMER_ID}
  • /v1/tokens
  • /v1/tokens/{TOKEN_ID}
  • /v1/events
  • /v1/events/{EVENT_ID}
  • /v1/recursions
  • /v1/recursions/{RECURSION_ID}
  • /v1/account

認証

あなたは所有するAPIキーのうちの一つをリクエストに含めて送ることで認証することができます。 APIキーにはテスト環境用と商用環境用、非公開と公開可能の2×2の組み合わせがあります。 商用環境用のAPIキーでは実際のクレジットカード処理が行われ、テスト用カード番号などテスト専用の機能は利用できません。 開発中や試験中は常にテスト環境用のAPIキーを利用してください。 非公開APIキーはサーバからWebPayにリクエストを送信する際に一般的に利用します。課金の作成など重要な操作が可能なので、流出しないように管理してください。 公開可能APIキーはブラウザやスマートフォンから利用者のクレジットカードのトークンを作成するのに利用します。 鍵の性質上、第三者に見られることを意図しており、トークンに関連した機能以外は利用できません。 ライブラリやサービスのAPIキーの欄には通常非公開APIキーを指定します。

APIキーの管理は 設定画面 から行ってください。 非公開APIキーは、あなたのアカウントの特別な権限を必要とする操作を可能にしますので、他人に教えることなく厳重に管理してください。

APIへの認証は、 ベーシック認証 を用いて行います。あなたのAPIキーをベーシック認証のユーザー名として入力し、パスワードは空とすることで認証が行えます。 各言語向けのライブラリでは認証の操作が自動で行われるため、APIクライアントをインスタンス化する際の引数に非公開APIキーを渡してください。

全てのリクエストは、 HTTPS 経由でアクセスしてください。通常のHTTP通信でのリクエストはエラーとなります。また、APIのアクセス時には毎回のリクエストで認証を行う必要があります。

リクエスト例
$
curl "https://api.webpay.jp/v1/charges" \ 
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd:"

curlコマンドは、-uオプションによってベーシック認証に必要なデータの受け渡しを行います。(APIキーの後にコロン":"を付けることで、パスワードを求められることを回避できます。)全てのセクションにこのように、サンプルAPIキーを入れたリクエスト例を記載していますので、私達のAPIがどのように動作するのかすぐに試すことが可能です。

エラー

WebPayのAPIでは、HTTPレスポンスのステータスコードによって、「成功」、「失敗」を通知しています。 2xx (200番台)のステータスコードは「成功」を意味し、4xx (400番台)は処理の失敗を、5xx (500番台)は予期せぬサーバー側に起因するエラーを意味します。

全てのエラーは、エラーの種類、原因、具体的なエラーメッセージを記載したJSONを返します。種類によってはさらに付加的な情報を持つことがあります。

エラーの詳細についてはAPIエラーをご覧ください。

メッセージの言語設定

サーバから得られるエラーメッセージなどの言語を指定することが可能です。デフォルトでは英語設定 en となっており ja とすることで日本語でのメッセージを得ることが可能です。 Chargeオブジェクトfailure_message プロパティや Eventオブジェクト の内容など、一部の記録されるメッセージ部分については、その記録が作成されたリクエストの言語設定に依存し、その情報は事後で変わることはありません。

メッセージを日本語に設定する

以下のような手続きでjaというパラメータを与えておくことで、メッセージを日本語で得ることができます。誤ったAPIキーを指定するなどして試してみてください。

$
curl "https://api.webpay.jp/v1/charges" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-H "Accept-Language: ja"

課金 (Charges)

クレジットカードへ課金をするためには、新しい"charge"オブジェクトを作成してください。APIを用いることで、新規課金取引の作成だけでなく、全ての課金履歴の表示、個別の課金情報の閲覧、払い戻し処理等を行うことができます。

課金("charge")オブジェクト

プロパティ
id:
string (文字列)

ch_で始まる一意なオブジェクトを示す文字列

object:
object 値は"charge"です。
livemode:
boolean (真偽値 true/false)

オブジェクトが保存されている環境。trueなら商用環境、falseならテスト環境を示します。

amount:
integer (0以上の整数)

1円単位での課金額。現在の最低課金額は50円です。

card:
hash (ディクショナリ)

課金されたクレジットカードの情報を持ったハッシュ。

object:
string (文字列) 値は"card"です。
exp_year:
integer (整数)
exp_month:
integer (整数)
fingerprint:
string (文字列)

このクレジットカード番号に紐づけられた一意(他と重複しない)キー。あなたは例えばこの値を、2人の別々のユーザーが同じカードを登録することを発見・禁止するために使用することができます。

name:
string (文字列) もしくはnull

クレジットカード表面に記載されている所有者の名義。

country:
string (文字列)

国コード。現在は "JP" で固定されています。

type:
string (文字列)

カードのブランド。Visa, MasterCard, American Express, Discover, JCB, Diners Club もしくは"unknown"(不明)のどれか。

cvc_check:
string (文字列)

セキュリティコードの提示に対して、"pass"(通過)、"fail"(不正)、"unchecked"(不明)のいずれかの値になります。カード会社毎に即時判断するかどうかが異なりますため、"pass"となっていても正当なセキュリティコードが入力されたことを保証されません。

last4:
string (文字列)

カード番号の下4桁

created:
timestamp (unixタイム)

unixタイムで表示される作成日時

currency:
string (3桁のISO通貨コード) 現在は円("jpy")のみ対応

三文字のISOコードで表される通貨の名称(例: jpy)

paid:
boolean (真偽値 true/false)

カードの与信枠の確保を表します。仮売上、即時の実売上のいずれでも成功した場合はtrue、失敗した場合にはfalseとなります。

captured:
boolean (真偽値 true/false)

売上処理が完了しているかどうかを表します。仮売上として作成された場合、このプロパティはfalseとなり、仮売上が実売上化されるとtrueになります。成功した即時売上の場合は常にtrueです。

refunded:
boolean (真偽値 true/false)

課金が払い戻されたかどうか。もし一部のみ払い戻されている場合は、このプロパティはfalseのままです。全額払い戻された場合はtrueになります。仮売上が実売上化されずに期限切れになった場合、全額払い戻されたことになり、このプロパティはtrueになります。

amount_refunded:
integer (0以上の整数)

円単位で払い戻された金額(一部払い戻された場合は課金額よりも小さい値となります。)

customer:
string (文字列) もしくはnull

もし存在している場合は、この課金に紐付いている顧客のID

shop:
string (文字列) もしくはnull

もし存在している場合は、この課金を実行した店子のID

recursion:
string (文字列) もしくはnull

もし存在している場合は、この課金をひきおこした定期課金のID

description:
string (文字列) もしくはnull

課金オブジェクトに添付することのできる任意の文字列。この文字列は、ウェブ上で課金を管理する際に、課金オブジェクトとともに表示されます。後でトラッキングするために、ユーザーのIDやemailアドレス等を記載しておくと良いかもしれません。この文字列が購入者などに表示されることはありません。

failure_message:
string (文字列) もしくはnull

より詳しい課金の決済失敗に関するメッセージ。

expire_time:
timestamp (unixタイム)

unixタイムで表示される仮売上げが自動的に失効される日時。即時売上の場合は常にnullです。仮売上の場合はAPIリクエストか設定画面で指定された日数後の日時が設定されます。

fees:
hashを含んだarray

この課金に対して行った処理によって発生した手数料のリスト。払戻し処理時には手数料の払戻し分(負値の手数料徴収)が契約中の決済手数料にて計算され、追加されます。仮売上の処理には手数料が発生しないため追加されません。

object:
string (文字列) 値は"fee"です。
transaction_type:
string (文字列)

どのようなトランザクションに際して手数料が発生したか。payment(支払い)かrefund(返金)

transaction_fee:
integer (整数)

それぞれのトランザクションに対して発生する1円単位での基本手数料(現在のプライシング上は0円以外になりません)

rate:
number

課金額に対して割合で発生する手数料率。パーセント単位の小数表示

amount:
integer (整数)

実際に発生する1円単位での手数料額

created:
timestamp (unixタイム)

unixタイムで表示される発生日時

レスポンス例
{
  "id": "ch_31e2x0csD2Xnavd",
  "object": "charge",
  "livemode": false,
  "currency": "jpy",
  "description": null,
  "amount": 1554,
  "amount_refunded": 0,
  "customer": null,
  "recursion": null,
  "created": 1479345702,
  "paid": true,
  "refunded": false,
  "failure_message": null,
  "card": {
    "object": "card",
    "exp_year": 2018,
    "exp_month": 8,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "TARO YAMADA",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "captured": true,
  "expire_time": null,
  "fees": [
    {
      "object": "fee",
      "transaction_type": "payment",
      "transaction_fee": 0,
      "rate": 3.25,
      "amount": 51,
      "created": 1479345702
    }
  ]
}

新しい課金の作成

クレジットカードへの課金を行うには、新しい課金("charge")オブジェクトを作成してください。もしテストモードのAPIキーを使用中の場合は、指定されたカードへ本当に請求が行くことはありませんが、それ以外に関してはまったく商用と同等に動作します。(テストモードでは、課金は「成功」して完了したと見なして動作します。)

パラメータ
amount:
integer (0以上の整数) 必須

1円単位で正の整数で表現される課金額。最小課金額は50円、最高金額は9,999,999円です。

currency:
string (3桁のISO通貨コード) 必須

3文字のISOコードで規定されている通貨。現在は、"jpy"(日本円)のみ対応しています。

customer:
string (文字列) 任意 customerかcardのどちらかは必須ですが、両方は必要ありません。

この課金で請求を行う既存の顧客のID。

shop:
string (文字列) 任意 デフォルトはnull

この課金を店子による課金とする場合に、店子のIDを指定。

card:
hash (ディクショナリ) 任意 customerかcardのどちらかは必須ですが、両方は必要ありません。

この課金で請求を行うクレジットカードの情報。トークンIDもしくはトークン作成時に指定するカード情報を含んだハッシュが指定できますが、商用環境ではガイドラインに従い、トークンのみを利用してください。

description:
string (文字列) 任意 デフォルトはnull

課金オブジェクトに添付することのできる任意の文字列。この文字列は、ウェブ上で課金を管理する際に、課金オブジェクトとともに表示されます。後でトラッキングするために、ユーザーのIDやemailアドレス等を記載しておくと良いかもしれません。

capture:
boolean (真偽値 true/false) 任意 デフォルトはtrue

すぐに実売上にするか、仮売上として後で実売上化するかを指定します。falseの場合に与信のみが行われ、後で「仮売上の実売上化」をすることで実売上化できます。標準で7日経つと仮売上は失効します。日数は"expire_days"で指定できるほか、規定値を設定画面から変更可能です。

expire_days:
integer (整数) 任意 デフォルトはnull

仮売上の有効日数を課金ごとに設定します。初期値の7日、および設定画面で設定した日数を上書きします。1日から45日の間で設定できます。

uuid:
string (文字列) 任意 デフォルトはnull

RFC4122に準拠したUUID(例:"f81d4fae-7dec-11d0-a765-00a0c91e6bf6")を設定すると、同じUUIDを持つリクエストが複数回送信されたとき、24時間の間に高々一度だけ処理がおこなわれることを保証します。以前の同じUUIDを持つリクエストで作成済みの課金がある場合は、それを取得したときと同様に返却します。たとえ以前の課金が失敗していても、再送時のレスポンスはエラーレスポンスにはならず、課金オブジェクトがそのまま返されます。同じUUIDを別の処理に複数回利用した場合、エラーになるか、以前のデータが返り、不適当な結果になります。課金の可否を判断するために、"paid"プロパティがtrueになっていることを必ず確認してください。

返り値

課金が成功した場合は、課金オブジェクト("charge")を返します。もし何らかの理由で失敗した場合は、エラーを返します。よくあるエラーの原因としては、不正なカードの利用、カード情報の間違い、有効期限の切れたカードの利用、カード情報の不備、最大限度額を超えたカードの利用等があります。

発生するエラー
InvalidRequest

必須パラメータが指定されていない場合(param: amount, currency)

不適切な値が指定された場合(param: amount, currency, expire_days, uuid)

customerとcardのどちらも指定されていない、あるいは両方が指定された場合(paramなし)

一定時間内に規定数を越える大量の課金を作成した場合(paramなし)。APIキーが流出し不正利用された場合の被害を抑えるための対策です

CardError

カード情報が正しく入力されていない場合

customer を指定したときに、指定された顧客がカード情報を持たない場合

カードが指定額で利用できないなどの理由で、決済時にエラーが発生した場合

利用できないカードブランドのカード番号が入力された場合

NotFound

指定されたオブジェクトが存在しない場合(param: customer, shop)

定義
POST https://api.webpay.jp/v1/charges
リクエスト例
$
curl "https://api.webpay.jp/v1/charges" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-d "amount=1554" \
-d "currency=jpy" \
-d "card=tok_SampleCardToken" \
-d "description="
レスポンス例
{
  "id": "ch_31e2x0csD2Xnavd",
  "object": "charge",
  "livemode": false,
  "currency": "jpy",
  "description": null,
  "amount": 1554,
  "amount_refunded": 0,
  "customer": null,
  "recursion": null,
  "created": 1479345702,
  "paid": true,
  "refunded": false,
  "failure_message": null,
  "card": {
    "object": "card",
    "exp_year": 2018,
    "exp_month": 8,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "TARO YAMADA",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "captured": true,
  "expire_time": null,
  "fees": [
    {
      "object": "fee",
      "transaction_type": "payment",
      "transaction_fee": 0,
      "rate": 3.25,
      "amount": 51,
      "created": 1479345702
    }
  ]
}
エラー例
{
  "error": {
    "code": "incorrect_number",
    "message": "Your card number is incorrect",
    "param": "number",
    "type": "card_error"
  }
}

課金情報の取得

過去に作成済みの課金("charge")オブジェクトを取得します。課金は課金ID(charge ID)によって識別されます。ここで返す情報は、課金オブジェクトの作成時に返ってくる情報と同じです。

パラメータ
id:
string (文字列) 必須

取得する課金オブジェクトを識別するID。作成や一覧のレスポンスの"id"で示されている値です。

返り値

指定されたIDに該当する課金情報を返します。該当するオブジェクトが無いなど、それ以外の場合はエラーを返します。

発生するエラー
NotFound

指定された課金オブジェクトが存在しない場合(param: id)

定義
GET https://api.webpay.jp/v1/charges/{CHARGE_ID}
リクエスト例
$
curl "https://api.webpay.jp/v1/charges/ch_31e2x0csD2Xnavd" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "id": "ch_31e2x0csD2Xnavd",
  "object": "charge",
  "livemode": false,
  "currency": "jpy",
  "description": null,
  "amount": 1554,
  "amount_refunded": 0,
  "customer": null,
  "recursion": null,
  "created": 1479345702,
  "paid": true,
  "refunded": false,
  "failure_message": null,
  "card": {
    "object": "card",
    "exp_year": 2018,
    "exp_month": 8,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "TARO YAMADA",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "captured": true,
  "expire_time": null,
  "fees": [
    {
      "object": "fee",
      "transaction_type": "payment",
      "transaction_fee": 0,
      "rate": 3.25,
      "amount": 51,
      "created": 1479345702
    }
  ]
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such charge: ch_0123456789abcd"
  }
}

課金の払い戻し

過去に作成した課金オブジェクトの払い戻し処理を行います。払い戻された金銭は課金請求が元々行われたクレジットカードに対して行われ、決済金額に応じた手数料も払い戻されます。

一部金額を払い戻すこともできます。一度行った払い戻しは、一部払い戻しであっても取り消せません。

一度全額が払い戻されると、これ以降払い戻し処理を行うことはできなくなります。既に払い戻し処理を終えている場合や、払い戻し可能金額(当初の課金額)を超えて払い戻しを行おうとした場合にはエラーが返ります。

一部金額の払い戻しでは、内部的には新たな金額(元の金額と一部払い戻し金額の差額)による課金が行われ、元の課金が全額払い戻されるようになるため、カード明細上にはその処理が全て記載される場合があります。

仮売上として作成した課金に対して一部払い戻しをおこなった場合は仮売上金額が減算され、全額払い戻しを行った場合は仮売上が失効となります。

払い戻しは売上時刻(仮売上なら作成時、実売上なら実売上化時)から90日後の30分前(90×24×60 - 30分後)まで行えます。それ以降は一切できなくなります。

パラメータ
id:
string (文字列) 必須

払い戻しを行う課金オブジェクトの一意な識別ID

amount:
integer (0以上の整数) 任意 デフォルトは全額

円単位の正の整数で、払い戻しを行う金額を指定する。当初課金行った額から既に払い戻しを行った額を引いた金額を上限とする。

uuid:
string (文字列) 任意 デフォルトはnull

RFC4122に準拠したUUID(例:"f81d4fae-7dec-11d0-a765-00a0c91e6bf6")を設定すると、同じUUIDを持つリクエストが複数回送信されたとき、24時間の間に高々一度だけ処理がおこなわれることを保証します。以前の同じUUIDを持つリクエストで払い戻し済みの課金がある場合は、それを取得したときと同様に返却します。同じUUIDを別の処理に複数回利用した場合、エラーになるか、以前のデータが返り、不適当な結果になります。返金の可否を判断するために、"amount_refunded"プロパティが意図した金額になっていることを必ず確認してください。

返り値

もし払い戻しが成功した場合には課金("charge")オブジェクトを返す。既に全額払い戻されている場合や課金オブジェクトの識別IDが不正な場合は、エラーを返す。

発生するエラー
InvalidRequest

指定された値が不適切か、指定額が課金額より大きい場合(param: amount)

すでに全額返金済み、課金から90日以上経過しているなど、返金できない状態の場合(paramなし)

NotFound

指定された課金オブジェクトが存在しない場合(param: id)

定義
POST https://api.webpay.jp/v1/charges/{CHARGE_ID}/refund
リクエスト例
$
curl "https://api.webpay.jp/v1/charges/ch_31e2x0csD2Xnavd/refund" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-X POST -H 'Content-Length: 0'
レスポンス例
{
  "id": "ch_31e2x0csD2Xnavd",
  "object": "charge",
  "livemode": false,
  "currency": "jpy",
  "description": null,
  "amount": 1554,
  "amount_refunded": 1554,
  "customer": null,
  "recursion": null,
  "created": 1479345702,
  "paid": true,
  "refunded": true,
  "failure_message": null,
  "card": {
    "object": "card",
    "exp_year": 2018,
    "exp_month": 8,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "TARO YAMADA",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "captured": true,
  "expire_time": null,
  "fees": [
    {
      "object": "fee",
      "transaction_type": "payment",
      "transaction_fee": 0,
      "rate": 3.25,
      "amount": 51,
      "created": 1479345702
    }
  ]
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "Charge ch_0123456789abcd has already been refunded"
  }
}

仮売上の実売上化

仮売上として作成した課金を、実売上化します。仮売上とする課金は事前に「課金の作成」をcapture=falseとして作成しておきます。

仮売上は作成されてから一定の日数が経過すると失効します。その時点までに実売上化しなかった場合、払い戻し済みとして扱われ、実売上化できなくなります。

パラメータ
id:
string (文字列) 必須

実売上化を行う課金オブジェクトの一意な識別ID

amount:
integer (0以上の整数) 任意 デフォルトは仮売上を作成したときの全額

実売上化をする金額。仮売上の作成時の金額を上限とする。

返り値

capturedがtrueになった課金("charge")オブジェクトを返す。amountが仮売上作成時のamountを越えている場合、課金が支払済か、失効していた場合、または識別IDが不正な場合は、エラーを返す。

発生するエラー
InvalidRequest

指定された値が不適切か、指定額が仮売上作成時の金額より大きい場合(param: amount)

有効日数を超過しているなど、実売上化できない状態の場合(paramなし)

NotFound

指定された課金オブジェクトが存在しない場合(param: id)

定義
POST https://api.webpay.jp/v1/charges/{CHARGE_ID}/capture
リクエスト例
$
curl "https://api.webpay.jp/v1/charges/ch_31e2x0csD2Xnavd/capture" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-X POST -H 'Content-Length: 0'
レスポンス例
{
  "id": "ch_31e2x0csD2Xnavd",
  "object": "charge",
  "livemode": false,
  "currency": "jpy",
  "description": null,
  "amount": 1554,
  "amount_refunded": 0,
  "customer": null,
  "recursion": null,
  "created": 1479345702,
  "paid": true,
  "refunded": false,
  "failure_message": null,
  "card": {
    "object": "card",
    "exp_year": 2018,
    "exp_month": 8,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "TARO YAMADA",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "captured": true,
  "expire_time": 1479950502,
  "fees": [
    {
      "object": "fee",
      "transaction_type": "payment",
      "transaction_fee": 0,
      "rate": 3.25,
      "amount": 51,
      "created": 1479345702
    }
  ]
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "Charge ch_0123456789abcd is not authorized status"
  }
}

課金リストの取得

過去に作成した課金のリストを表示することができます。課金リストは、新しいものから順番(SQL的にはORDER BY updated_at DESC)に並んだ状態で返ってきます。

パラメータ
count:
integer (整数) 任意 デフォルトは10

一度にリストで返す課金オブジェクトの上限数。"count"は1から100の間の整数を指定することができます。

offset:
integer (整数) 任意 デフォルトは0

課金オブジェクトのオフセット(始値)の指定。APIは、このオフセットで指定された番号を一番目として、課金オブジェクトのリストを返します。例えばoffset=20&count=10であれば、リストの20番目から順番に10個の課金オブジェクトを返します。

created:
hash (ディクショナリ)またはtimestamp (unixタイム) 任意 デフォルトはnull

作成日でリストを絞り込むことができます。値は正確なUTCタイムスタンプ形式の文字列か、以下のオプションを持つハッシュです。

gt:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプよりも後に作成された項目のみに限定します。

gte:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプと同時かもしくはそれより後に作成された項目のみに限定します。

lt:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプよりも前に作成された項目のみに限定します。

lte:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプと同時かもしくはそれより前に作成された項目のみに限定します。

customer:
string (文字列) 任意 デフォルトはnull

顧客ID(customer)を指定した場合、指定された顧客の課金情報のみをリストにして返します。

shop:
string (文字列) 任意 デフォルトはnull

店子ID(shop)を指定した場合、指定された店子による課金情報のみをリストにして返します。

recursion:
string (文字列) 任意 デフォルトはnull

定期課金ID(recursion)を指定した場合、指定された定期課金による課金情報のみをリストにして返します。

返り値

countで指定された数を上限として、offsetで指定された番号から始まる課金オブジェクトの配列を含んだdataプロパティを持つハッシュ形式のオブジェクトが返ります。配列の中のそれぞれのエントリーが各課金情報となっています。もし課金情報がない場合は、空の配列が返ります。オブジェクトによる絞込み条件に存在しないIDが指定された場合は、エラーが返ります。

発生するエラー
NotFound

絞込み条件として指定されたオブジェクトが存在しない場合(param: customer, shop, recursion)

定義
GET https://api.webpay.jp/v1/charges
リクエスト例
$
curl "https://api.webpay.jp/v1/charges?count=3" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "object": "list",
  "url": "/v1/charges",
  "count": 3,
  "data": [
    {
      "id": "ch_31e2x0csD2Xnavd",
      "object": "charge",
      "livemode": false,
      "currency": "jpy",
      "description": null,
      "amount": 1554,
      "amount_refunded": 0,
      "customer": null,
      "recursion": null,
      "created": 1479345702,
      "paid": true,
      "refunded": false,
      "failure_message": null,
      "card": {
        "object": "card",
        "exp_year": 2018,
        "exp_month": 8,
        "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
        "name": "TARO YAMADA",
        "country": "JP",
        "type": "Visa",
        "cvc_check": "pass",
        "last4": "4242"
      },
      "captured": true,
      "expire_time": null,
      "fees": [
        {
          "object": "fee",
          "transaction_type": "payment",
          "transaction_fee": 0,
          "rate": 3.25,
          "amount": 51,
          "created": 1479345702
        }
      ]
    },
    {...},
    {...}
  ]
}

顧客 (Customers)

顧客("customer")オブジェクトは、同一の顧客に対する複数回の課金を可能にします。このAPIによって、顧客の作成、削除、更新ができるようになります。その他にも、特定の顧客の情報を取得したり、顧客一覧のリストを取得したりすることができます。

顧客("customer")オブジェクト

プロパティ
id:
string (文字列)

cus_で始まる一意なオブジェクトを示す文字列

object:
string (文字列) 値は"customer"です。
livemode:
boolean (真偽値 true/false)

オブジェクトが保存されている環境。trueなら商用環境、falseならテスト環境を示します。

created:
timestamp (unixタイム)
active_card:
hash (ディクショナリ)

顧客に紐づけられたクレジットカードの情報を持ったハッシュ。

object:
string (文字列) 値は"card"です。
exp_year:
integer (整数)
exp_month:
integer (整数)
fingerprint:
string (文字列)

このクレジットカード番号に紐づけられた一意(他と重複しない)キー。あなたは例えばこの値を、2人の別々のユーザーが同じカードを登録することを発見・禁止するために使用することができます。

name:
string (文字列) もしくはnull

クレジットカード表面に記載されている所有者の名義。

country:
string (文字列)

国コード。現在は "JP" で固定されています。

type:
string (文字列)

カードのブランド。Visa, MasterCard, American Express, Discover, JCB, Diners Club もしくは"unknown"(不明)のどれか。

cvc_check:
string (文字列)

セキュリティコードの提示に対して、"pass"(通過)、"fail"(不正)、"unchecked"(不明)のいずれかの値になります。カード会社毎に即時判断するかどうかが異なりますため、"pass"となっていても正当なセキュリティコードが入力されたことを保証されません。

last4:
string (文字列)

カード番号の下4桁

description:
string (文字列) もしくはnull

顧客オブジェクトに添付することができる任意の文字列。この情報はウェブ上のダッシュボードで顧客情報を確認する際に表示されます。

recursions:
hashを含んだarray

顧客に紐づけられた定期課金オブジェクトの一覧

email:
string (文字列) もしくはnull
レスポンス例
{
  "id": "cus_4lOag156Rfh10nU",
  "object": "customer",
  "livemode": false,
  "created": 1480657306,
  "email": "email@example.com",
  "description": "Active Merchant Test Customer",
  "active_card": {
    "object": "card",
    "exp_year": 2017,
    "exp_month": 9,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "Longbob Longsen",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "recursions": [

  ]
}

新しい顧客の作成

新規の顧客オブジェクトの作成。すべてのパラメータは任意項目で、設定しない場合は"null"になります。

パラメータ
card:
hash (ディクショナリ) 任意 デフォルトはnull

この課金で請求を行うクレジットカードの情報。トークンIDもしくはトークン作成時に指定するカード情報を含んだハッシュが指定できますが、商用環境ではガイドラインに従い、トークンのみを利用してください。

email:
string (文字列) 任意 デフォルトはnull

顧客のメールアドレス。この情報はウェブ上のダッシュボードに表示され、また履歴の検索やトラッキング等に使用することができます。

description:
string (文字列) 任意 デフォルトはnull

顧客オブジェクトに添付することができる任意の文字列。この情報はウェブ上のダッシュボードで顧客情報を確認する際に表示されます。

uuid:
string (文字列) 任意 デフォルトはnull

RFC4122に準拠したUUID(例:"f81d4fae-7dec-11d0-a765-00a0c91e6bf6")を設定すると、同じUUIDを持つリクエストが複数回送信されたとき、24時間の間に高々一度だけ処理がおこなわれることを保証します。以前の同じUUIDを持つリクエストで作成済みの顧客がある場合は、それを通常の作成時と同じように返却します。同じUUIDを別の処理に複数回利用した場合、エラーになるか、以前のデータが返り、不適当な結果になります。

返り値

成功した場合には、顧客("customer")オブジェクトを返します。カード情報を与えた場合、返されたオブジェクトは、カード情報("active_card")を含んでいます。

発生するエラー
InvalidRequest

不適切な値が指定された場合(param: email, uuid)

CardError

cardパラメータを指定したときに、カード情報が正しく入力されていない場合

定義
POST https://api.webpay.jp/v1/customers
リクエスト例
$
curl "https://api.webpay.jp/v1/customers" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-d "card=tok_SampleCardToken" \
-d "description=Active Merchant Test Customer"
レスポンス例
{
  "id": "cus_4lOag156Rfh10nU",
  "object": "customer",
  "livemode": false,
  "created": 1480657306,
  "email": "email@example.com",
  "description": "Active Merchant Test Customer",
  "active_card": {
    "object": "card",
    "exp_year": 2017,
    "exp_month": 9,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "Longbob Longsen",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "recursions": [

  ]
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "You must provide a valid card"
  }
}

顧客情報の取得

顧客("customer")オブジェクト作成時に返された顧客IDを指定し、既存の顧客の詳細情報を取得します。

パラメータ
id:
string (文字列) 必須

取得する顧客("customer")のID

返り値

存在する顧客のIDを受け取った場合は、顧客オブジェクトを返します。削除済みの顧客IDを指定した場合には、"id"と"deleted"プロパティのみを持つハッシュを返します。それ以外の場合はエラーになります。APIライブラリを利用する場合は"deleted"プロパティをチェックして、返り値が削除済みオブジェクトでないことを確認してください。

発生するエラー
NotFound

指定された顧客IDが間違っている場合(param: id)

定義
GET https://api.webpay.jp/v1/customers/{CUSTOMER_ID}
リクエスト例
$
curl "https://api.webpay.jp/v1/customers/cus_4lOag156Rfh10nU" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "id": "cus_4lOag156Rfh10nU",
  "object": "customer",
  "livemode": false,
  "created": 1480657306,
  "email": "email@example.com",
  "description": "Active Merchant Test Customer",
  "active_card": {
    "object": "card",
    "exp_year": 2017,
    "exp_month": 9,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "Longbob Longsen",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "recursions": [

  ]
}

顧客情報の更新

指定した顧客の情報を必要な部分のみ更新します。パラメータとして値を指定された情報のみ更新され、それ以外は変更されません。例えば、card パラメータを指定した場合、カード情報のみが更新され、将来の全ての課金はこの更新されたカードに対して行われます。

パラメータ
id:
string (文字列) 必須

更新する顧客("customer")の識別ID

card:
hash (ディクショナリ) 任意 デフォルトはnull

この顧客に関連づけるクレジットカードの情報。トークンIDもしくはカード情報を含んだハッシュが指定できますが、商用環境ではガイドラインに従い、トークンのみを利用してください。

number:
string (文字列) 必須

カードの番号(ハイフン"-"は無くても構いません)

exp_month:
integer (整数) 必須

カード有効期限の月を示す二桁の数字

exp_year:
integer (整数) 必須

カード有効期限の年を示す四桁の数字

cvc:
integer (整数) 任意 デフォルトはnull

カードのセキュリティーコード

name:
string (文字列) 任意 デフォルトはnull

クレジットカード表面に記載されている所有者の名義。印字されているアルファベットを半角英字で指定。

email:
string (文字列) 任意 デフォルトはnull

顧客のメールアドレス。この情報はウェブ上のダッシュボードに表示され、また履歴の検索やトラッキング等に使用することができます。

description:
string (文字列) 任意 デフォルトはnull

顧客オブジェクトに添付することができる任意の文字列。この情報はウェブ上のダッシュボードで顧客情報を確認する際に表示されます。

返り値

成功した場合には、顧客("customer")オブジェクトを返します。更新に失敗した場合にはエラーを返します。

発生するエラー
InvalidRequest

不適切な値が指定された場合(param: email)

CardError

cardパラメータを指定したときに、カード情報が正しく入力されていない場合

NotFound

指定された顧客IDが間違っているか、削除済みの場合(param: id)

定義
POST https://api.webpay.jp/v1/customers/{CUSTOMER_ID}
リクエスト例
$
curl "https://api.webpay.jp/v1/customers/cus_4lOag156Rfh10nU" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-d "description=最新の顧客情報です"
レスポンス例
{
  "id": "cus_4lOag156Rfh10nU",
  "object": "customer",
  "livemode": false,
  "created": 1480657306,
  "email": "email@example.com",
  "description": "最新の顧客情報です",
  "active_card": {
    "object": "card",
    "exp_year": 2017,
    "exp_month": 9,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "Longbob Longsen",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "recursions": [

  ]
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_0123456789abcd"
  }
}

顧客の削除

顧客を永久に削除します。この操作は巻き戻すことはできませんので、慎重に行ってください。

パラメータ
id:
string (文字列) 必須

削除する顧客の識別ID

返り値

成功した場合は右のレスポンス例のような、削除されたことを表すデータを返します。顧客IDが存在しない場合は、エラーを返します。

発生するエラー
NotFound

指定された顧客IDが間違っているか、削除済みの場合(param: id)

定義
DELETE https://api.webpay.jp/v1/customers/{CUSTOMER_ID}
リクエスト例
$
curl "https://api.webpay.jp/v1/customers/cus_4lOag156Rfh10nU" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-X DELETE
レスポンス例
{
  "id": "cus_4lOag156Rfh10nU",
  "deleted": true
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_0123456789abcd",
    "param": "id"
  }
}

顧客リストの取得

顧客のリストを表示します。顧客のリストは、作成日に基づいて、新しいものから順番に並べられています。(sqlで表すと ORDER BY updated_at DESC)

パラメータ
count:
integer (整数) 任意 デフォルトは10

一度にリストで返す顧客オブジェクトの上限数。"count"は1から100の間の整数を指定することができます。

offset:
integer (整数) 任意 デフォルトは0

顧客オブジェクトのオフセット(始値)の指定。APIは、このオフセットで指定された番号を一番目として、顧客オブジェクトのリストを返します。例えば offset=20&count=10 であれば、リストの20番目から順番に10個の顧客オブジェクトを返します。

created:
hash (ディクショナリ)またはtimestamp (unixタイム) 任意 デフォルトはnull

作成日でリストを絞り込むことができます。値は正確なUTCタイムスタンプ形式の文字列か、以下のオプションを持つハッシュです。

gt:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプよりも後に作成された項目のみに限定します。

gte:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプと同時かもしくはそれより後に作成された項目のみに限定します。

lt:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプよりも前に作成された項目のみに限定します。

lte:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプと同時かもしくはそれより前に作成された項目のみに限定します。

返り値

countで指定された数を上限として、offsetで指定された番号から始まる顧客オブジェクトの配列を含んだdataプロパティを持つハッシュ形式のオブジェクトが返ります。配列の中のそれぞれのエントリーが各顧客情報となっています。もし顧客情報がない場合は、空の配列が返ります。

発生するエラー
なし
定義
GET https://api.webpay.jp/v1/customers
リクエスト例
$
curl "https://api.webpay.jp/v1/customers?count=3" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "object": "list",
  "url": "/v1/customers",
  "count": 3,
  "data": [
    {
      "id": "cus_4lOag156Rfh10nU",
      "object": "customer",
      "livemode": false,
      "created": 1480657306,
      "email": "email@example.com",
      "description": "Active Merchant Test Customer",
      "active_card": {
        "object": "card",
        "exp_year": 2017,
        "exp_month": 9,
        "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
        "name": "Longbob Longsen",
        "country": "JP",
        "type": "Visa",
        "cvc_check": "pass",
        "last4": "4242"
      },
      "recursions": [

      ]
    },
    {...},
    {...}
  ]
}

顧客のカード情報を削除

顧客からカード情報のみを削除します。カード情報を持たない顧客に対しては何も行いません。不要になった顧客のカード情報を定期的に削除することを強く推奨します。

パラメータ
id:
string (文字列) 必須

カード情報を削除する顧客の識別ID

返り値

成功した場合には、顧客("customer")オブジェクトを返します。カード情報を持たない顧客に対して行った場合も何も処理は行わず、顧客("customer")オブジェクトを返します。失敗した場合にはエラーを返します。

発生するエラー
NotFound

指定された顧客IDが間違っているか、削除済みの場合(param: id)

定義
DELETE https://api.webpay.jp/v1/customers/{CUSTOMER_ID}/active_card
リクエスト例
$
curl "https://api.webpay.jp/v1/customers/cus_4lOag156Rfh10nU/active_card" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-X DELETE
レスポンス例
{
  "id": "cus_4lOag156Rfh10nU",
  "object": "customer",
  "livemode": false,
  "created": 1480657306,
  "email": "email@example.com",
  "description": "Active Merchant Test Customer",
  "active_card": {
    "object": "card",
    "exp_year": 2017,
    "exp_month": 9,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "Longbob Longsen",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  },
  "recursions": [

  ]
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such customer: cus_0123456789abcd",
    "param": "id"
  }
}

トークン (Tokens)

あなたは厳重な管理を必要とするクレジットカードの重要な情報をあなた自身で保持することなくクレジットカード決済を行う方法がないかと考えることがあるでしょう。トークンを使用すると、まさにそのような、クレジットカードの情報をあなたが保持することなくクレジットカード決済・課金を行うことができるようになります。

トークンオブジェクトはWebPayに保存されたクレジットカードの情報を表します。トークンオブジェクトはトークンID(例えば"tok_0123456789abcd")で識別されます。

トークンは、継続課金のために顧客("customer")オブジェクトと紐づけるか、もしくは課金("charge")を行うかの、どちらかの操作を行うために、一度だけ使用することが可能です。APIでカード情報の代わりにトークンIDを指定してください。

通常、サーバサイドからAPIを利用してトークンを作成することはありません。ブラウザやスマートフォンからトークンを作成するためのライブラリについてはトークン決済CheckoutHelperのドキュメントをご覧ください。このセクションはWebPay Extendのshared customer機能を使う際か、まだライブラリが存在しない環境でトークンを作成するクライアントを実装する際にのみ参考にしてください。

トークン("token")オブジェクト

プロパティ
id:
string (文字列)

tok_で始まる一意なオブジェクトを示す文字列

object:
string (文字列) 値は"token"です。
livemode:
boolean (真偽値 true/false)

オブジェクトが保存されている環境。trueなら商用環境、falseならテスト環境を示します。

card:
hash (ディクショナリ)

クレジットカードの情報を持ったハッシュ。

object:
string (文字列) 値は"card"です。
exp_year:
integer (整数)
exp_month:
integer (整数)
fingerprint:
string (文字列)

このクレジットカード番号に紐づけられた一意(他と重複しない)キー。あなたは例えばこの値を、2人の別々のユーザーが同じカードを登録することを発見・禁止するために使用することができます。

name:
string (文字列) もしくはnull

クレジットカード表面に記載されている所有者の名義。

country:
string (文字列)

国コード。現在は "JP" で固定されています。

type:
string (文字列)

カードのブランド。Visa, MasterCard, American Express, Discover, JCB, Diners Club もしくは"unknown"(不明)のどれか。

cvc_check:
string (文字列)

セキュリティコードの提示に対して、"pass"(通過)、"fail"(不正)、"unchecked"(不明)のいずれかの値になります。カード会社毎に即時判断するかどうかが異なりますため、"pass"となっていても正当なセキュリティコードが入力されたことを保証されません。

last4:
string (文字列)

カード番号の下4桁

created:
timestamp (unixタイム)
used:
boolean (真偽値 true/false)

このトークンが既に使用済みかどうか。トークンは一度のみ使用可能です。

レスポンス例
{
  "id": "tok_2SYbM5d1rdtvd97",
  "object": "token",
  "livemode": false,
  "created": 1479266736,
  "used": false,
  "card": {
    "object": "card",
    "exp_year": 2017,
    "exp_month": 8,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "TARO YAMADA",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  }
}

新しいトークンの作成

クレジットカード詳細を隠蔽する一度だけ使用可能な使い切りトークンを作成します。このトークンは、このAPIのあらゆる操作で、クレジットカード情報のハッシュの代わりとして使用することができます。このAPIは"test_public"または"live_public"で始まる公開可能鍵を利用してリクエストできます。アプリケーションなど利用者に配布するデータに鍵を埋め込む場合には、必ず公開可能鍵を利用してください。

パラメータ
card:
hash (ディクショナリ) 任意 通常は必須です。WebPay Extendでのみかわりにcustomerを指定できます。

このトークンが実際に表すクレジットカードの詳細情報。商用環境では、自動的にカードの正当性チェックをおこないます。正当性チェックの失敗をテスト環境で再現するにはテスト用クレジットカード番号を利用してください。

number:
string (文字列) 必須

カードの番号(ハイフン"-"は無くても構いません)

exp_month:
integer (整数) 必須

カード有効期限の月を示す二桁の数字

exp_year:
integer (整数) 必須

カード有効期限の年を示す四桁の数字

cvc:
integer (整数) 必須

カードのセキュリティーコード

name:
string (文字列) 必須

クレジットカード表面に記載されている所有者の名義。印字されているアルファベットを半角英字で指定。

customer:
任意 WebPay Extendでのみcardのかわりに指定できます。

WebPay Extendで、アプリケーション提供者の顧客を指定します。 顧客のカード情報をコピーしたトークンを作成します。

uuid:
string (文字列) 任意 デフォルトはnull

RFC4122に準拠したUUID(例:"f81d4fae-7dec-11d0-a765-00a0c91e6bf6")を設定すると、同じUUIDを持つリクエストが複数回送信されたとき、24時間の間に高々一度だけ処理がおこなわれることを保証します。以前の同じUUIDを持つリクエストで作成済みのトークンがある場合は、それを通常の作成時と同じように返却します。同じUUIDを別の処理に複数回利用した場合、エラーになるか、以前のデータが返り、不適当な結果になります。

返り値

成功した場合は、トークン("token")オブジェクトが返ります。失敗した場合はエラーが返ります。

発生するエラー
InvalidRequest

不適切な値が指定された場合(param: uuid)

WebPay Extend 以外からのリクエストで customer が指定された場合(param: customer)

customerとcardのどちらも指定されていない、あるいは両方が指定された場合(paramなし)

WebPay.jsやCheckoutHelperからのリクエストで改竄など、不正が検出された場合(paramなし)

Unauthorized

WebPay.jsやCheckoutHelperからのリクエストで非公開鍵が使われた場合

CardError

カード情報が正しく入力されていない場合

customer を指定したときに、指定された顧客がカード情報を持たない場合

定義
POST https://api.webpay.jp/v1/tokens
リクエスト例
$
curl "https://api.webpay.jp/v1/tokens" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-d "card[number]=4242-4242-4242-4242" \
-d "card[exp_month]=11" \
-d "card[exp_year]=2018" \
-d "card[cvc]=123" \
-d "card[name]=KEI KUBO"
レスポンス例
{
  "id": "tok_2SYbM5d1rdtvd97",
  "object": "token",
  "livemode": false,
  "created": 1479266736,
  "used": false,
  "card": {
    "object": "card",
    "exp_year": 2017,
    "exp_month": 8,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "TARO YAMADA",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  }
}

作成済みトークンの取得

指定したトークンIDと一致する作成済みのクレジットカードトークンオブジェクトを取得します。

パラメータ
id:
string (文字列) 必須

取得したいトークンのID

返り値

正当なトークンIDが指定された場合はトークンオブジェクトを返します。それ以外の場合はエラーを返します。

発生するエラー
NotFound

指定されたオブジェクトが存在しない場合(param: id)

定義
GET https://api.webpay.jp/v1/tokens/{TOKEN_ID}
リクエスト例
$
curl "https://api.webpay.jp/v1/tokens/tok_2SYbM5d1rdtvd97" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "id": "tok_2SYbM5d1rdtvd97",
  "object": "token",
  "livemode": false,
  "created": 1479266736,
  "used": false,
  "card": {
    "object": "card",
    "exp_year": 2017,
    "exp_month": 8,
    "fingerprint": "215b5b2fe460809b8bb90bae6eeac0e0e0987bd7",
    "name": "TARO YAMADA",
    "country": "JP",
    "type": "Visa",
    "cvc_check": "pass",
    "last4": "4242"
  }
}

定期課金 (Recursions)

定期課金("recursion")オブジェクトは、指定された顧客("customer")に対して定期的に自動で課金をおこないます。このAPIによって定期課金の作成、削除、停止中の定期課金の再開ができるようになります。その他にも、特定の定期課金の情報を取得したり、定期課金一覧のリストを取得したりすることができます。

利用する際は定期課金の内容も参照し、失敗した時にどうするかなど運用の設計を行ってください。

定期課金("recursion")オブジェクト

プロパティ
id:
string (文字列)

rec_で始まる一意なオブジェクトを示す文字列

object:
string (文字列) 値は"recursion"です。
livemode:
boolean (真偽値 true/false)

オブジェクトが保存されている環境。trueなら商用環境、falseならテスト環境を示します。

shop:
string (文字列) もしくはnull

もし存在している場合は、この課金を作成した店子のID

created:
timestamp (unixタイム)

unixタイムで表示される作成日時

amount:
integer (0以上の整数)

1円単位での課金額。現在の最低課金額は50円です。

currency:
string (3桁のISO通貨コード) 現在は円("jpy")のみ対応

三文字のISOコードで表される通貨の名称(例: jpy)

period:
string (文字列)

課金間隔。現在はmonth(毎月)、year(毎年)が利用可能です。

description:
string (文字列) もしくはnull

定期課金オブジェクトに添付することができる任意の文字列。ウェブ上のダッシュボードで定期課金情報を確認する際に表示されます。2016/06/01より、この内容は定期課金によって作成された課金オブジェクトにも引き継がれます。

customer:
string (文字列)

この定期課金に紐付いている顧客のID。関連づけられている顧客は誤操作防止のため削除できなくなります。

last_executed:
timestamp (unixタイム) もしくはnull

最後に課金を実行した日時。失敗した場合も更新されます。

next_scheduled:
timestamp (unixタイム) もしくはnull

次回の課金実行予定時刻。状態が"suspended"か"closed"の場合はnilになります。

status:
string (文字列)

active(次回の実行予定あり)、suspended(一時停止中。次回の実行予定はないが再開可能)、closed(停止。次回の実行予定がなく、再開できない)

レスポンス例
{
  "id": "rec_7WM5FA4sd6QU1wD",
  "object": "recursion",
  "livemode": false,
  "created": 1484203605,
  "amount": 32400,
  "currency": "jpy",
  "period": "month",
  "description": "cus_7WM5FA4U4eNP16M / 定期課金",
  "customer": "cus_7WM5FA4U4eNP16M",
  "last_executed": 1491015612,
  "next_scheduled": 1493607600,
  "status": "active"
}

新しい定期課金の作成

新規の定期課金オブジェクトを作成し、開始します。

パラメータ
amount:
integer (0以上の整数) 必須

1円単位で正の整数で表現される課金額。最小課金額は50円、最高金額は9,999,999円です。

currency:
string (3桁のISO通貨コード) 必須

3文字のISOコードで規定されている通貨。現在は、"jpy"(日本円)のみ対応しています。

customer:
string (文字列) 必須

この請求を行う既存の顧客のID。

shop:
string (文字列) 任意 デフォルトはnull

この課金を店子による課金とする場合に、店子のIDを指定。

period:
string (文字列) 必須

課金を行う間隔。現在はmonth(毎月)とyear(毎年)が指定できます。

description:
string (文字列) 任意 デフォルトはnull

定期課金オブジェクトに添付することができる任意の文字列。ウェブ上のダッシュボードで定期課金情報を確認する際に表示されます。2016/06/01より、この内容は定期課金によって作成された課金オブジェクトにも引き継がれます。

first_scheduled:
timestamp (unixタイム) 任意 デフォルトは現在時刻

最初に定期課金を行う日時。1周期前(periodが"month"なら1ヶ月、"year"なら1年前)以降の時刻を指定できます。

uuid:
string (文字列) 任意 デフォルトはnull

RFC4122に準拠したUUID(例:"f81d4fae-7dec-11d0-a765-00a0c91e6bf6")を設定すると、同じUUIDを持つリクエストが複数回送信されたとき、24時間の間に高々一度だけ処理がおこなわれることを保証します。以前の同じUUIDを持つリクエストで作成済みの定期課金がある場合は、それを通常の作成時と同じように返却します。同じUUIDを別の処理に複数回利用した場合、エラーになるか、以前のデータが返り、不適当な結果になります。

返り値

成功した場合には、定期課金("recursion")オブジェクトを返す。

発生するエラー
InvalidRequest

必須パラメータが指定されていない場合(param: amount, currency, period, customer)

不適切な値が指定された場合(param: amount, currency, period, first_scheduled, uuid)

NotFound

指定されたオブジェクトが存在しない場合(param: customer, shop)

定義
POST https://api.webpay.jp/v1/recursions
リクエスト例
$
curl "https://api.webpay.jp/v1/recursions" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-d "amount=32400" \
-d "currency=jpy" \
-d "customer=cus_4lOag156Rfh10nU" \
-d "period=month" \
-d "description=cus_7WM5FA4U4eNP16M / 定期課金"
レスポンス例
{
  "id": "rec_7WM5FA4sd6QU1wD",
  "object": "recursion",
  "livemode": false,
  "created": 1484203605,
  "amount": 32400,
  "currency": "jpy",
  "period": "month",
  "description": "cus_7WM5FA4U4eNP16M / 定期課金",
  "customer": "cus_7WM5FA4U4eNP16M",
  "last_executed": 1491015612,
  "next_scheduled": 1493607600,
  "status": "active"
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required param: customer"
  }
}

定期課金情報の取得

既存の定期課金の詳細情報を取得します。

パラメータ
id:
string (文字列) 必須

取得する定期課金("recursion")の識別ID

返り値

もし正当な識別IDを受け取った場合は、APIは定期課金オブジェクトを返します。削除済みの定期課金IDを指定した場合には、"id"と"deleted"プロパティのみを持つオブジェクトを返します。APIライブラリを利用する場合は"deleted"プロパティをチェックして、返り値が削除済みオブジェクトでないことを確認してください。

発生するエラー
NotFound

指定された定期課金IDが間違っている場合(param: id)

定義
GET https://api.webpay.jp/v1/recursions/{RECURSION_ID}
リクエスト例
$
curl "https://api.webpay.jp/v1/recursions/rec_7WM5FA4sd6QU1wD" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "id": "rec_7WM5FA4sd6QU1wD",
  "object": "recursion",
  "livemode": false,
  "created": 1484203605,
  "amount": 32400,
  "currency": "jpy",
  "period": "month",
  "description": "cus_7WM5FA4U4eNP16M / 定期課金",
  "customer": "cus_7WM5FA4U4eNP16M",
  "last_executed": 1491015612,
  "next_scheduled": 1493607600,
  "status": "active"
}

一時停止中の定期課金の再開

一時停止中の(statusがsuspendedである)定期課金を再度有効にします。

自動実行時に課金処理が失敗した場合、自動的に定期課金を一時停止状態に変更します。原因を究明し、再開しても問題がないことがわかった場合、このAPIを利用して該当の定期課金を再度有効にすることができます。

一時停止中の定期課金には期限が設定されており、これは最後の失敗した課金が予定されていた日時から1期間後(課金間隔がmonthの場合は1ヶ月後)です。この期限を越えた定期課金はstatusがclosedになり、再開できません。

パラメータ
id:
string (文字列) 必須

再開する定期課金("recursion")の識別ID

retry:
boolean (真偽値 true/false) 任意 デフォルトはtrue

前回失敗した自動課金に相当する課金をこのAPI呼び出し時に実施します。実施したくない場合は明示的に"false"を指定してください。

返り値

成功した場合には、再開された定期課金("recursion")オブジェクトを返します。更新に失敗した場合にはエラーを返します。

発生するエラー
InvalidRequest

一時停止中でないか、再開可能期間を過ぎたため再開できない場合(paramなし)

CardError

カードが指定額で利用できないなどの理由で、決済時にエラーが発生した場合

NotFound

指定された定期課金IDが間違っているか、削除済みの場合(param: id)

定義
POST https://api.webpay.jp/v1/recursions/{RECURSION_ID}/resume
リクエスト例
$
curl "https://api.webpay.jp/v1/recursions/rec_7WM5FA4sd6QU1wD/resume" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-X POST -H 'Content-Length: 0'
レスポンス例
{
  "id": "rec_7WM5FA4sd6QU1wD",
  "object": "recursion",
  "livemode": false,
  "created": 1484203605,
  "amount": 32400,
  "currency": "jpy",
  "period": "month",
  "description": "cus_7WM5FA4U4eNP16M / 定期課金",
  "customer": "cus_7WM5FA4U4eNP16M",
  "last_executed": 1491015612,
  "next_scheduled": 1493607600,
  "status": "active"
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "This recursion cannot be resumed, because it passed resume limit date"
  }
}

定期課金の削除

定期課金を永久に削除します。この操作は巻き戻すことはできませんので、慎重に行ってください。

パラメータ
id:
string (文字列) 必須

削除する定期課金の識別ID

返り値

成功した場合は右のレスポンス例のような、成功を表すデータを返します。もし定期課金IDが存在しない場合は、エラーを返します。

発生するエラー
NotFound

指定された定期課金IDが間違っているか、削除済みの場合(param: id)

定義
DELETE https://api.webpay.jp/v1/recursions/{RECURSION_ID}
リクエスト例
$
curl "https://api.webpay.jp/v1/recursions/rec_7WM5FA4sd6QU1wD" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-X DELETE
レスポンス例
{
  "id": "rec_7WM5FA4sd6QU1wD",
  "deleted": true
}
エラー例
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such recursion: rec_0123456789abcd",
    "param": "id"
  }
}

定期課金リストの取得

定期課金のリストを表示します。リストは、作成日に基づいて、新しいものから順番に並べられています。(sqlで表すと ORDER BY updated_at DESC)

パラメータ
count:
integer (整数) 任意 デフォルトは10

一度にリストで返す定期課金オブジェクトの上限数。"count"は1から100の間の整数を指定することができます。

offset:
integer (整数) 任意 デフォルトは0

定期課金オブジェクトのオフセット(始値)の指定。APIは、このオフセットで指定された番号を一番目として、定期課金オブジェクトのリストを返します。例えば offset=20&count=10 であれば、リストの20番目から順番に10個の定期課金オブジェクトを返します。

created:
hash (ディクショナリ)またはtimestamp (unixタイム) 任意 デフォルトはnull

作成日でリストを絞り込むことができます。値は正確なUTCタイムスタンプ形式の文字列か、以下のオプションを持つハッシュです。

gt:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプよりも後に作成された項目のみに限定します。

gte:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプと同時かもしくはそれより後に作成された項目のみに限定します。

lt:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプよりも前に作成された項目のみに限定します。

lte:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプと同時かもしくはそれより前に作成された項目のみに限定します。

customer:
string (文字列) 任意 デフォルトはnull

顧客ID(customer)を指定した場合、指定された顧客と関連づけられた定期課金のみを対象とします。

shop:
string (文字列) 任意 デフォルトはnull

店子ID(shop)を指定した場合、指定された店子による定期課金のみを対象とします。

suspended:
boolean (真偽値 true/false) 任意 デフォルトはnull

"true"を指定した場合、suspendedclosed状態の定期課金のみを対象とします。"false"を指定した場合、active状態の定期課金のみを対象とします。指定しない場合は絞込みをおこないません。

返り値

対象となる定期課金のなかから、countで指定された数を上限として、offsetで指定された番号から始まる定期課金オブジェクトの配列を含んだdataプロパティを持つハッシュ形式のオブジェクトが返ります。配列の中のそれぞれのエントリーが各定期課金情報となっています。もし定期課金情報がない場合は、空の配列が返ります。オブジェクトによる絞込み条件に存在しないIDが指定された場合は、エラーが返ります。

発生するエラー
NotFound

絞込み条件として指定されたオブジェクトが存在しない場合(param: customer, shop)

定義
GET https://api.webpay.jp/v1/recursions
リクエスト例
$
curl "https://api.webpay.jp/v1/recursions?count=3" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "object": "list",
  "url": "/v1/recursions",
  "count": 3,
  "data": [
    {
      "id": "rec_7WM5FA4sd6QU1wD",
      "object": "recursion",
      "livemode": false,
      "created": 1484203605,
      "amount": 32400,
      "currency": "jpy",
      "period": "month",
      "description": "cus_7WM5FA4U4eNP16M / 定期課金",
      "customer": "cus_7WM5FA4U4eNP16M",
      "last_executed": 1491015612,
      "next_scheduled": 1493607600,
      "status": "active"
    },
    {...},
    {...}
  ]
}

イベント (Events)

イベントは、あなたのアカウントにどんなことが起こっているかを知る術として提供している機能です。何らかの興味深いイベントが起こった時に、WebPayは新しいイベントオブジェクトを作成します。例えば、課金が成功した際に発生するcharge.succeededイベントや顧客が作成された時に作成されるcustomer.createdなどがあります。

他のAPIのメソッドと同じように、イベントもAPI経由で取得することが可能です。また、webhook機能を利用すると、登録したサーバ宛のHTTPリクエストで新規に発生したイベントを受け取ることができます。

注意点: 私達は現在のところ、直近90日のイベントに対してのみアクセスを保証しています。

イベント("event")オブジェクト

プロパティ
id:
string (文字列)

evt_で始まる一意なオブジェクトを示す文字列

object:
string (文字列) 値は"event"です。
livemode:
boolean (真偽値 true/false)

オブジェクトが保存されている環境。trueなら商用環境、falseならテスト環境を示します。

created:
timestamp (unixタイム)
data:
hash (ディクショナリ)

イベントに関連したデータを持つハッシュ。

object:
hash (ディクショナリ)

イベントの内容についての概要。例えば、charge.succeededイベントの場合は、課金(Charges)オブジェクトが入ります。

previous_attributes:
hash (ディクショナリ)

更新系の操作の場合に、変更された属性とその変更前後の値が入ります。それ以外ではキーが存在しません。

pending_webhooks:
integer (0以上の整数)

設定されたURLにまだきちんと送信できていない(20xのレスポンスが得られていない)webhookの数。

type:
string (文字列)

イベントの概要。例えば、customer.created, charge.refundedなど。イベントの種類に一覧があります。

レスポンス例
{
  "id": "evt_9G83SL5W7bo7clX",
  "object": "event",
  "livemode": false,
  "type": "charge.succeeded",
  "created": 1485918010,
  "data": {
    "object": {
      "id": "ch_9G83SL5c5dE6bww",
      "object": "charge",
      "livemode": false,
      "currency": "jpy",
      "description": "cus_7WM5FA4U4eNP16M / 定期課金",
      "amount": 32400,
      "amount_refunded": 0,
      "customer": "cus_7WM5FA4U4eNP16M",
      "recursion": "rec_7WM5FA4sd6QU1wD",
      "created": 1485918010,
      "paid": true,
      "refunded": false,
      "failure_message": null,
      "card": {
        "object": "card",
        "exp_year": 2017,
        "exp_month": 1,
        "fingerprint": "1953ab62a8e812fb44332d7b22d2ffe50bb2b57a",
        "name": "AAA",
        "country": "JP",
        "type": "MasterCard",
        "cvc_check": "pass",
        "last4": "4444"
      },
      "captured": true,
      "expire_time": null,
      "fees": [
        {
          "object": "fee",
          "transaction_type": "payment",
          "transaction_fee": 0,
          "rate": 3.25,
          "amount": 1053,
          "created": 1485918010
        }
      ]
    }
  },
  "pending_webhooks": 0
}

イベント詳細の取得

イベントの詳細を取得する。webhook等で受け取ったイベントのIDを指定してください。

パラメータ
id:
string (文字列) 必須

取得するイベントのID

返り値

正当なIDが指定された場合にはイベントオブジェクトを返します。全てのイベントは右に記載している通り、共通の構造を持っています。

dataハッシュは"object"と呼ばれるプロパティを持っており、その中身は同じオブジェクトをAPI経由で取得したものとまったく同じ物が入っています。

オブジェクトのプロパティの変化を取得するために、dataプロパティは変更を示す内容も含んだハッシュを持っています。

発生するエラー
NotFound

指定されたイベントオブジェクトが存在しない場合(param: id)

定義
GET https://api.webpay.jp/v1/events/{EVENT_ID}
リクエスト例
$
curl "https://api.webpay.jp/v1/events/evt_9G83SL5W7bo7clX" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "id": "evt_9G83SL5W7bo7clX",
  "object": "event",
  "livemode": false,
  "type": "charge.succeeded",
  "created": 1485918010,
  "data": {
    "object": {
      "id": "ch_9G83SL5c5dE6bww",
      "object": "charge",
      "livemode": false,
      "currency": "jpy",
      "description": "cus_7WM5FA4U4eNP16M / 定期課金",
      "amount": 32400,
      "amount_refunded": 0,
      "customer": "cus_7WM5FA4U4eNP16M",
      "recursion": "rec_7WM5FA4sd6QU1wD",
      "created": 1485918010,
      "paid": true,
      "refunded": false,
      "failure_message": null,
      "card": {
        "object": "card",
        "exp_year": 2017,
        "exp_month": 1,
        "fingerprint": "1953ab62a8e812fb44332d7b22d2ffe50bb2b57a",
        "name": "AAA",
        "country": "JP",
        "type": "MasterCard",
        "cvc_check": "pass",
        "last4": "4444"
      },
      "captured": true,
      "expire_time": null,
      "fees": [
        {
          "object": "fee",
          "transaction_type": "payment",
          "transaction_fee": 0,
          "rate": 3.25,
          "amount": 1053,
          "created": 1485918010
        }
      ]
    }
  },
  "pending_webhooks": 0
}

イベントリストの取得

90日以内のイベントのリストの取得。

パラメータ
count:
integer (整数) 任意 デフォルトは10

返すオブジェクトの上限数。1から100の間で指定できます。

offset:
integer (整数) 任意 デフォルトは0

返された項目のリストの始まりの値。このオフセットで指定された場所を起点とする要求された数のアイテムをAPIは返します。

created:
hash (ディクショナリ)またはtimestamp (unixタイム) 任意 デフォルトはnull

作成日でリストを絞り込むことができます。値は正確なUTCタイムスタンプ形式の文字列か、以下のオプションを持つハッシュです。

gt:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプよりも後に作成された項目のみに限定します。

gte:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプと同時かもしくはそれより後に作成された項目のみに限定します。

lt:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプよりも前に作成された項目のみに限定します。

lte:
timestamp (unixタイム) 任意 デフォルトはnull

このタイムスタンプと同時かもしくはそれより前に作成された項目のみに限定します。

type:
string (文字列) 任意 デフォルトはnull

特定のイベント名を*をワイルドカードとして使用して指定された文字列。ここで指定されたものに一致したイベントのみが表示対象になります。

shop:
string (文字列) 任意 デフォルトはnull

店子ID(shop)を指定した場合、指定された店子によるイベントのみをリストにして返します。

返り値

offsetで指定された場所から始まる、countで指定された数を上限とする配列を含むdataプロパティを持つハッシュを返します。配列ないの各エントリーは独立したイベントオブジェクトです。もしこれ以上のイベントが取得可能ではない場合には、空の配列が返ります。

発生するエラー
NotFound

絞込み条件として指定されたオブジェクトが存在しない場合(param: shop)

定義
GET https://api.webpay.jp/v1/events
リクエスト例
$
curl "https://api.webpay.jp/v1/events" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "object": "list",
  "url": "/v1/events",
  "count": 3,
  "data": [
    {
      "id": "evt_9G83SL5W7bo7clX",
      "object": "event",
      "livemode": false,
      "type": "charge.succeeded",
      "created": 1485918010,
      "data": {
        "object": {
          "id": "ch_9G83SL5c5dE6bww",
          "object": "charge",
          "livemode": false,
          "currency": "jpy",
          "description": "cus_7WM5FA4U4eNP16M / 定期課金",
          "amount": 32400,
          "amount_refunded": 0,
          "customer": "cus_7WM5FA4U4eNP16M",
          "recursion": "rec_7WM5FA4sd6QU1wD",
          "created": 1485918010,
          "paid": true,
          "refunded": false,
          "failure_message": null,
          "card": {
            "object": "card",
            "exp_year": 2017,
            "exp_month": 1,
            "fingerprint": "1953ab62a8e812fb44332d7b22d2ffe50bb2b57a",
            "name": "AAA",
            "country": "JP",
            "type": "MasterCard",
            "cvc_check": "pass",
            "last4": "4444"
          },
          "captured": true,
          "expire_time": null,
          "fees": [
            {
              "object": "fee",
              "transaction_type": "payment",
              "transaction_fee": 0,
              "rate": 3.25,
              "amount": 1053,
              "created": 1485918010
            }
          ]
        }
      },
      "pending_webhooks": 0
    },
    {...},
    {...}
  ]
}

イベントの種類

これはWebPayが現在送る全てのイベントの種類の一覧です。将来的には変わる可能性もありますので、この既存のイベントリストのみに依存した実装は推奨しません。

これらのイベントは、名前に一定のパターンがあります。つまり、resource(リソース).event(イベント)の形になっています。

イベント
charge.succeeded:
課金(charge)関連

新規課金が行われて成功した際に発生します。

charge.failed:
課金(charge)関連

課金の試行が失敗した際に発生します。

charge.refunded:
課金(charge)関連

一部払い戻しも含めて、課金の払い戻し処理が行われた際に発生します。 仮売上が実売上化されることなく、失効した場合にも発生します。

charge.captured:
課金(charge)関連

仮売上が実売上化された際に発生します。

customer.created:
顧客(customer)関連

新規の顧客が作成された際に発生します。

customer.updated:
顧客(customer)関連

顧客が更新された際に発生します。

customer.deleted:
顧客(customer)関連

顧客が削除された際に発生します。

recursion.created:
定期課金(recursion)関連

定期課金が作成された際に発生します。

recursion.succeeded:
定期課金(recursion)関連

定期課金による課金が成功した際に発生します。

recursion.failed:
定期課金(recursion)関連

定期課金による課金が失敗した際に発生します。

recursion.resumed:
定期課金(recursion)関連

定期課金が再開された際に発生します。

recursion.deleted:
定期課金(recursion)関連

定期課金が削除された際に発生します。

account.application.deauthorized:
アプリケーション(application)関連

ユーザーがアプリケーションの認可を取り消した際に発生します。関連のあるアプリケーションにのみ送信されます。

ping:
関連なし

Webhookの設定画面からテストのイベントを発行したときに送信されます。

アカウント (Accounts)

これは、あなたのWebPayアカウントを表現するオブジェクトです。あなたはこのオブジェクトを現在の登録済みメールアドレスを確認したり、利用可能なカードブランドを取得するために利用できます。

アカウント("account")オブジェクト

プロパティ
id:
string (文字列)

アカウントの一意な識別子。

object:
string (文字列) 値は"account"です。
charge_enabled:
boolean (真偽値 true/false)

このアカウントが商用環境での課金を行うことができるかどうか。

currencies_supported:
stringを含んだarray

課金を作成する際にこのアカウントが利用することができる通貨の一覧。

details_submitted:
boolean (真偽値 true/false)

アカウントの審査用の詳細情報が既に入力済みかどうか。

email:
string (文字列) もしくはnull

アカウントの登録済みメールアドレス

statement_descriptor:
string (文字列) もしくはnull

クレジットカードの明細書に記載される文字列。カードの持ち主の契約するカード会社によって表記がカタカナになる場合があります。

card_types_supported:
stringを含んだarray

このアカウントが取り扱えるカードブランド。要素となりうる文字列はVisa, MasterCard, JCB, American Express, Diners Club。テスト環境用の鍵でアクセスしている場合、商用環境が利用可能であれば商用環境と同じ配列が、まだであれば全ブランドを含む配列が返ります。

レスポンス例
{
  "object": "account",
  "id": "acct_7Kh0pZ7ufeE7g0F",
  "email": "hmsk@webpay.jp",
  "statement_descriptor": null,
  "details_submitted": false,
  "charge_enabled": false,
  "currencies_supported": [
    "jpy"
  ],
  "card_types_supported": [
    "Visa",
    "American Express",
    "MasterCard",
    "JCB",
    "Diners Club"
  ]
}

アカウント情報の取得

リクエストを行ったAPIキーの情報を基にして、APIキーの持ち主のアカウントの詳細情報を取得します。

返り値

使用されたAPIキーに紐付くアカウントオブジェクトを返します。

発生するエラー
なし
定義
GET https://api.webpay.jp/v1/account
リクエスト例
$
curl "https://api.webpay.jp/v1/account" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd":
レスポンス例
{
  "object": "account",
  "id": "acct_7Kh0pZ7ufeE7g0F",
  "email": "hmsk@webpay.jp",
  "statement_descriptor": null,
  "details_submitted": false,
  "charge_enabled": false,
  "currencies_supported": [
    "jpy"
  ],
  "card_types_supported": [
    "Visa",
    "American Express",
    "MasterCard",
    "JCB",
    "Diners Club"
  ]
}

テスト環境のデータの全削除

ユーザのテスト環境のデータを全て削除します。ユーザ設定画面から行える操作と同じです。リクエスト時は、テスト環境用非公開鍵を指定する必要があります。この操作を行った後、元に戻すことは出来ません。

返り値

削除成功時は右のレスポンス例のような、成功を表すデータを返します。

発生するエラー
InvalidRequest

商用環境の非公開鍵を用いて削除を試みた場合

定義
DELETE https://api.webpay.jp/v1/account/data
リクエスト例
$
curl "https://api.webpay.jp/v1/account/data" \
-u "test_secret_eHn4TTgsGguBcW764a2KA8Yd": \
-X DELETE
レスポンス例
{
  "deleted": true
}