NAV
curl Python Ruby PHP node Java

PAY.JP API

PAY.JP は、RESTをベースに構成された決済APIです。都度の支払い、定期的な支払い、顧客情報の管理など、ビジネス運用における様々なことができます。

共通項目

認証

curl https://api.pay.jp/v1/charges \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = "sk_test_c62fade9d045b54cd76d7036"
require "payjp"
Payjp.api_key = "sk_test_c62fade9d045b54cd76d7036"
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036")
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";

PAY.JPのAPIを利用するには、ユーザー登録を行い、APIページからAPIキーを取得してください。 テスト用のキーでは、本番の支払い処理を行うサーバーへは接続されず、実際の支払い情報として計上されることもありません。本番用のキーは、本番申請を行うことで利用できるようになります。

種類 用途
パブリックキー HTML内に埋め込むトークン生成用のパブリックキー
シークレットキー サーバー側からBasic認証のユーザーネームとして渡すシークレットキー

通常の認証は、シークレットキーをユーザーネームとして扱い、Basic認証経由で行われます。パブリックキーは、あなたの決済画面のHTML内に組み込む公開用のAPIキーで、クレジットカードのトークンを生成する際に使用します。 シークレットキーは、全てのAPIリクエスト操作が可能となる重要なキーなので、くれぐれ も取扱いにご注意ください。

プロトコル

セキュリティのため、PAY.JPに対する全てのAPI通信は必ずHTTPSで行うようにしてください。

リクエスト

PAY.JP APIへのリクエストでは、GET、POST、DELETEの3種類のHTTPメソッドを利用できます。

引数は、GETの場合はクエリーパラメータで、POSTではContent-Type: application/x-www-form-urlencodedのボディで送信ください。

レスポンス

APIからのレスポンスデータは正常・異常とも全てUTF-8のJSON形式(Content-Type: application/json; charset=utf-8)で返されます。

タイムスタンプ

日次に関するデータは、UTCタイムゾーンのUNIXタイムスタンプで表示されます。一部入金予定日や入金実行日など秒数の関係ないものは、Date型(e.g. 2015-09-07) で表示されます。

Error

エラーハンドリング例

# レスポンス例を記載
{
  "error": {
    "message": "Unrecognized request URL: GET /v1/not_found",
    "status": 404,
    "type": "client_error"
  }
}
try:
    # Use Payjp's library to make requests...
    pass
except payjp.error.CardError as e:
    # Since it's a decline, payjp.error.CardError will be caught
    body = e.json_body
    err  = body['error']

    print('Status is: %s' % e.http_status)
    print('Type is: %s' % err['type'])
    print('Code is: %s' % err['code'])
    # param is '' in this case
    print('Param is: %s' % err['param'])
    print('Message is: %s' % err['message'])
except payjp.error.InvalidRequestError as e:
    # Invalid parameters were supplied to Payjp's API
    pass
except payjp.error.AuthenticationError as e:
    # Authentication with Payjp's API failed
    # (maybe you changed API keys recently)
    pass
except payjp.error.APIConnectionError as e:
    # Network communication with Payjp failed
    pass
except payjp.error.PayjpException as e:
    # Display a very generic error to the user, and maybe send
    # yourself an email
    pass
except Exception as e:
    # Something else happened, completely unrelated to Payjp
    pass
begin
  # Use Payjp's library to make requests...
rescue Payjp::CardError => e
  # Since it's a decline, Payjp::CardError will be caught
  body = e.json_body
  err  = body[:error]

  puts "Status is: #{e.http_status}"
  puts "Type is: #{err[:type]}"
  puts "Code is: #{err[:code]}"
  # param is '' in this case
  puts "Param is: #{err[:param]}"
  puts "Message is: #{err[:message]}"
rescue Payjp::InvalidRequestError => e
  # Invalid parameters were supplied to Payjp's API
rescue Payjp::AuthenticationError => e
  # Authentication with Payjp's API failed
  # (maybe you changed API keys recently)
rescue Payjp::APIConnectionError => e
  # Network関連でエラーが発生した場合の例外
  # ex1, PAY.JPが障害中などでサーバーとのコネクションが切れた場合
  # ex2, api.pay.jpの名前解決に失敗した場合
  # ex3, リクエストからレスポンス受信までに90秒以上経過した場合
  # => 3の場合リクエストが成功している可能性があるため、成否を確認下さい
  # => 3の秒数は`Payjp.read_timeout = 100`のように任意に設定可能です
rescue Payjp::APIError => e
  # 上記以外の特殊なケースの例外
  # ex, レスポンスのボディがJSON形式でない場合(PAY.JP障害時など)
  # ex, レスポンスのHTTPステータスが400,401,402,404以外の場合
rescue Payjp::PayjpError => e
  # PayjpErrorは上記5種類の独自例外クラスの親クラスです
  # 本SDK内ではこの例外を直接raiseしておりません
  # 上記5種類の独自例外クラスを包括的にrescueする目的でご利用下さい
rescue => e
  # Something else happened, completely unrelated to Payjp
end
try {
  // Use Payjp's library to make requests...
} catch(\Payjp\Error\Card $e) {
  // Since it's a decline, \Payjp\Error\Card will be caught
  $body = $e->getJsonBody();
  $err  = $body['error'];

  print('Status is:' . $e->getHttpStatus() . "\n");
  print('Type is:' . $err['type'] . "\n");
  print('Code is:' . $err['code'] . "\n");
  // param is '' in this case
  print('Param is:' . $err['param'] . "\n");
  print('Message is:' . $err['message'] . "\n");
} catch (\Payjp\Error\InvalidRequest $e) {
  // Invalid parameters were supplied to Payjp's API
} catch (\Payjp\Error\Authentication $e) {
  // Authentication with Payjp's API failed
} catch (\Payjp\Error\ApiConnection $e) {
  // Network communication with Payjp failed
} catch (\Payjp\Error\Base $e) {
  // Display a very generic error to the user, and maybe send
  // yourself an email
} catch (Exception $e) {
  // Something else happened, completely unrelated to Payjp
}
// Any API rejects Promise when response HTTP status is 4xx or 5xx.
// The 1st argument has the following properties.

// status (Number): the same as HTTP response status
// response (Object): response body (or undefined when nextwork error)
// message (String): error message

const payjp = require('payjp')('sk_invalid_key');
payjp.customers.create().catch(function(err) {
  console.log(err.status) // 401
  console.log(err.response.body)
  /*
  {
    error: {
      message: 'Invalid API Key: sk_***',
      status: 401,
      type: 'auth_error'
    }
  }
  */
  console.log(err.message) // Unauthorized
});

// e.g. Network Error
payjp.customers.create().catch(function(err) {
  console.log(err.status) // undefined
  console.log(err.response) // undefined
  console.log(err.message) // socket hang up
});
import jp.pay.exception.*;

try {
  // Use Payjp's library to make requests...
} catch (CardException e) {
  // Since it's a decline, CardException will be caught
  System.out.println("Status is: " + e.getCode());
  System.out.println("Message is: " + e.getMessage());
} catch (InvalidRequestException e) {
  // Invalid parameters were supplied to Payjp's API
} catch (AuthenticationException e) {
  // Authentication with Payjp's API failed
  // (maybe you changed API keys recently)
} catch (APIConnectionException e) {
  // Network communication with Payjp failed
} catch (PayjpException e) {
  // Display a very generic error to the user, and maybe send
  // yourself an email
} catch (Exception e) {
  // Something else happened, completely unrelated to Payjp
}

エラーとなるリクエストには、"error"というキーが含まれたエラーレスポンスが返されます。 エラーレスポンス “error” 内の “status” にはHTTPステータスコードと同様の値が入ります (下表)。 エラーレスポンス “error” 内の “message” にはエラーメッセージが含まれます。エラーメッセージは事業者向けの内容となっており、エンドユーザーへ提示する内容として利用することを推奨しておりません。

error[type] 詳細
client_error リクエストエラー
card_error カードに関するエラー
server_error PAY.JPや決済ネットワーク側のエラー
not_found_error 存在しないオブジェクト
not_allowed_method_error 許可されていないメソッドエラー
auth_error 認証エラー
invalid_request_error 無効なリクエスト
error[code] 詳細
invalid_number 不正なカード番号
invalid_cvc 不正なCVC
invalid_expiration_date 不正な有効期限年、または月
invalid_expiry_month 不正な有効期限月
invalid_expiry_year 不正な有効期限年
expired_card 有効期限切れ
card_declined カード会社によって拒否されたカード
processing_error 決済ネットワーク上で生じたエラー
missing_card 顧客がカードを保持していない
unacceptable_brand 対象のカードブランドが許可されていない
invalid_id 不正なID
no_api_key APIキーがセットされていない
invalid_api_key 不正なAPIキー
invalid_plan 不正なプラン
invalid_expiry_days 不正な失効日数
unnecessary_expiry_days 失効日数が不要なパラメーターである場合
invalid_flexible_id 不正なID指定
invalid_timestamp 不正なUnixタイムスタンプ
invalid_trial_end 不正なトライアル終了日
invalid_string_length 不正な文字列長
invalid_country 不正な国名コード
invalid_currency 不正な通貨コード
invalid_address_zip 不正な郵便番号
invalid_amount 不正な支払い金額
invalid_plan_amount 不正なプラン金額
invalid_card 不正なカード
invalid_card_name 不正なカードホルダー名
invalid_card_country 不正なカード請求先国名コード
invalid_card_address_zip 不正なカード請求先住所(郵便番号)
invalid_card_address_state 不正なカード請求先住所(都道府県)
invalid_card_address_city 不正なカード請求先住所(市区町村)
invalid_card_address_line 不正なカード請求先住所(番地など)
invalid_customer 不正な顧客
invalid_boolean 不正な論理値
invalid_email 不正なメールアドレス
no_allowed_param パラメーターが許可されていない場合
no_param パラメーターが何もセットされていない
invalid_querystring 不正なクエリー文字列
missing_param 必要なパラメーターがセットされていない
invalid_param_key 指定できない不正なパラメーターがある
no_payment_method 支払い手段がセットされていない
payment_method_duplicate 支払い手段が重複してセットされている
payment_method_duplicate_including_customer 支払い手段が重複してセットされている(顧客IDを含む)
failed_payment 指定した支払いが失敗している場合
invalid_refund_amount 不正な返金額
already_refunded すでに返金済み
invalid_amount_to_not_captured 確定されていない支払いに対して部分返金ができない
refund_amount_gt_net 返金額が元の支払い額より大きい
capture_amount_gt_net 支払い確定額が元の支払い額より大きい
invalid_refund_reason 不正な返金理由
already_captured すでに支払いが確定済み
cant_capture_refunded_charge 返金済みの支払いに対して支払い確定はできない
cant_reauth_refunded_charge 返金済みの支払いに対して再認証はできない
charge_expired 認証が失効している支払い
already_exist_id すでに存在しているID
token_already_used すでに使用済みのトークン
already_have_card 指定した顧客がすでに保持しているカード
dont_has_this_card 顧客が指定したカードを保持していない
doesnt_have_card 顧客がカードを何も保持していない
already_have_the_same_card すでに同じカード番号、有効期限のカードを保持している
invalid_interval 不正な課金周期
invalid_trial_days 不正なトライアル日数
invalid_billing_day 不正な支払い実行日
billing_day_for_non_monthly_plan 支払い実行日は月次プランにしか指定できない
exist_subscribers 購入者が存在するプランは削除できない
already_subscribed すでに定期課金済みの顧客
already_canceled すでにキャンセル済みの定期課金
already_paused すでに停止済みの定期課金
subscription_worked すでに稼働している定期課金
cannot_change_prorate_status 日割り課金の設定はプラン変更時のみ可能
too_many_metadata_keys metadataキーの登録上限(20)を超過している
invalid_metadata_key 不正なmetadataキー
invalid_metadata_value 不正なmetadataバリュー
apple_pay_disabled_in_livemode 本番モードのApple Pay利用が許可されていない
invalid_apple_pay_token 不正なApple Payトークン
test_card_on_livemode 本番モードのリクエストにテストカードが使用されている
not_activated_account 本番モードが許可されていないアカウント
too_many_test_request テストモードのリクエストリミットを超過している
payjp_wrong PAY.JPのサーバー側でエラーが発生している
pg_wrong 決済代行会社のサーバー側でエラーが発生している
not_found リクエスト先が存在しないことを示す
not_allowed_method 許可されていないHTTPメソッド
over_capacity レートリミットに到達
refund_limit_exceeded 期限を過ぎた後の返金操作
error[status] Meaning
200 リクエスト成功
400 不正なパラメーターなどのリクエストエラー
401 APIキーの認証エラー
402 カード認証・支払いエラー
404 存在しないAPIリソース
429 レートリミットによるアクセス一時拒否
500 PAY.JPや決済ネットワークでの障害

Rate Limit

PAY.JPのAPIには、過負荷による障害の防止を目的としたレートリミットが設定されています。

ゾーン

APIリクエストは下記のルールに従ってゾーンに分類され、ゾーンごとに制限が適用されます。

ゾーン 対象範囲
pk 公開鍵によるトークン作成へのアクセスが該当
payment 秘密鍵による支払い作成へのアクセスが該当
sk 秘密鍵によるAPIアクセスのうち、paymentに該当しないもの

ゾーンごとの制限値は以下のとおりです。livemode/testmodeによっても値は違います。

モード ゾーン 流速[request/sec] バケット
livemode pk 10 10
livemode payment 14 70
livemode sk 60 120
testmode pk 2 10
testmode payment 2 10
testmode sk 2 10

制限値はアカウントごとに独立して管理され、他アカウントのアクセス状況は関係しません。

リミットの挙動

レートリミットは、leaky bucketアルゴリズム に従って実装されています。

各ゾーンに対するリクエストは一旦バケットに入り、入った順に流速の値に従って処理されていきます。

流速を超えてリクエストを行うと、バケットの処理待ちリクエスト数が増加します。バケットの上限値を超えてしまう場合は、そのリクエストはエラーとなります。

エラーとなった場合、ステータスコード429・エラーコードover_capacityのエラーjsonが返却されます。

リミットへの対応

チュートリアル - レートリミットへの対応 をご参照ください

ヘルプ - レートリミットにもよくある質問への回答が記載されています。

List(ページネーション)

curl https://api.pay.jp/v1/customers?limit=3&offset=10 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Customer.all(limit=3, offset=10)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Customer.all(limit: 3, offset: 10)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Customer::all(array("limit" => 3, "offset" => 10));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.list({
  limit: 3,
  offset: 10
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("limit", 3);
customerParams.put("offset", 10);
Customer.all(customerParams);

レスポンス

{
  "count": 0,
  "data": [],
  "has_more": false,
  "object": "list",
  "url": "/v1/customers"
}

各オブジェクトを一覧取得した際、戻り値はlistオブジェクトを介して取得されます。

一覧取得APIは共通して以下のページネーションを指定でき、各種オブジェクトは直近で生成された順番に取得されます。

クエリー 詳細
limit 取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。
offset 基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。

例えば、直近の支払情報を10件まで取得したい場合、 limit=10 というクエリーを追加します。

またCustomer.cards のように、親リソースのレスポンス内に含まれている関連リソースのリストは、 デフォルトのページング(limit=10, offset=0)が行われた状態で取得されます。 11件目以降のデータを取得する際には、該当のlistオブジェクトurl キーで取得できるエンドポイントに対して、 適切な limit, offset を指定してページングを行なってください。

listオブジェクト

listオブジェクト

{
  "count": 0,
  "data": [],
  "has_more": false,
  "object": "list",
  "url": "/v1/customers"
}

プロパティ


object String

“list"の固定文字列


has_more Boolean

取得できていないリソースオブジェクトがあるかどうか


url String

このlistオブジェクトのURLパス


data Array

リソースオブジェクトの配列


count Integer

data の配列長

Metadata

curl https://api.pay.jp/v1/customers \
-u sk_test_c62fade9d045b54cd76d7036: \
-d metadata[user_id]=123
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Customer.create(
    metadata = {'user_id': 123}
)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Customer.create(
  metadata: {user_id: 123}
)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Customer::create(array(
        "metadata" => array("user_id" => "123")
));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.create({
  metadata: {'user_id': '123'}
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> customerParams = new HashMap<String, Object>();
Map<String, String> initialMetadata = new HashMap<String, String>();
initialMetadata.put("user_id", "123");
customerParams.put("metadata", initialMetadata);
Customer.create(customerParams);

メタデータは、更新可能なオブジェクト(Charge, Customer, Card, Plan, Subscription)に任意のキーバリュー型のデータ持たせることのできるオブジェクトです。 例えば、請求書番号や注文番号などを支払いオブジェクトのメタデータに保存すれば、それらをPAY.JPの支払いオブジェクトから直接取得することが可能になります。

メタデータを設定していない場合でも、各種オブジェクトのレスポンスのJSON内にmetadataキーは存在します。

メタデータを利用するには、対象オブジェクトの作成もしくは更新リクエストに例のように設定します。

なお、一つのオブジェクトには最大20キーまで保存でき、キーは40文字まで、バリューは500文字までの文字列をセットすることができます。

詳しい実装についてはブログ記事もご覧ください。

Charge (支払い)

都度の支払いや定期購入の引き落としのときに生成される、支払い情報のオブジェクトです。

chargeオブジェクト

chargeオブジェクト

{
  "amount": 3500,
  "amount_refunded": 0,
  "captured": true,
  "captured_at": 1433127983,
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1583375140,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_6845da1a8651f889bc432362dfcb",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": null,
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_fa990a4c10672a93053a774730b0a",
  "livemode": false,
  "metadata": null,
  "object": "charge",
  "paid": true,
  "platform_fee": null,
  "platform_fee_rate": "10.00",
  "refund_reason": null,
  "refunded": false,
  "subscription": null,
  "tenant": "ten_121673955bd7aa144de5a8f6c262",
  "total_platform_fee": 350
}

プロパティ


id String

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


object String

“charge"の固定文字列


livemode Boolean

本番環境かどうか


created Integer

この支払い作成時のUTCタイムスタンプ


amount Integer

支払い額


currency String

3文字のISOコード(現状 "jpy” のみサポート)


paid Boolean

認証処理が成功しているかどうか。


expired_at Integer

認証状態が自動的に失効される日時のタイムスタンプ


captured Boolean

支払い処理を確定しているかどうか


captured_at Integer

支払い処理確定時のUTCタイムスタンプ


card Object

支払いされたクレジットカードのcardオブジェクト


customer String

顧客ID


description String

概要


failure_code String

失敗した支払いのエラーコード


failure_message String

失敗した支払いの説明


refunded Boolean

返金済みかどうか


amount_refunded Integer

この支払いに対しての返金額


refund_reason String

返金理由


subscription String

sub_から始まる定期課金のID


metadata Object

キーバリューの任意データ


platform_fee Integer

PAY.JP Platform のみ

プラットフォーマーに振り分けられる入金金額。


tenant String

PAY.JP Platformのみ

テナントID


platform_fee_rate String

PAY.JP Platformのみ

テナント作成時に指定したプラットフォーム利用料率(%)


total_platform_fee Integer

PAY.JP Platformのみ

プラットフォーム利用料総額

支払いを作成

POST https://api.pay.jp/v1/charges

curl https://api.pay.jp/v1/charges \
-u sk_test_c62fade9d045b54cd76d7036: \
-d card=tok_76e202b409f3da51a0706605ac81 \
-d amount=3500 \
-d currency=jpy
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = payjp.Charge.create(
    amount=3500,
    card='tok_76e202b409f3da51a0706605ac81',
    currency='jpy',
)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = Payjp::Charge.create(
  :amount => 3500,
  :card => 'tok_76e202b409f3da51a0706605ac81',
  :currency => 'jpy',
)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Charge::create(array(
    "card" => "tok_76e202b409f3da51a0706605ac81",
    "amount" => 3500,
    "currency" => "jpy",
    // "tenant" => "ten_xxx" // PAY.JP Platformでは必須
));
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.create({
  card: 'tok_76e202b409f3da51a0706605ac81',
  amount: 3500,
  currency: 'jpy',
  // tenant: "ten_xxx" // PAY.JP Platformでは必須
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("card", "tok_76e202b409f3da51a0706605ac81");
chargeParams.put("amount", 3500);
chargeParams.put("currency", "jpy");
Charge.create(chargeParams);

レスポンス

{
  "amount": 3500,
  "amount_refunded": 0,
  "captured": true,
  "captured_at": 1433127983,
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1583375140,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_6845da1a8651f889bc432362dfcb",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": null,
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_fa990a4c10672a93053a774730b0a",
  "livemode": false,
  "metadata": null,
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": false,
  "subscription": null
}

エラーレスポンス

{
  "error": {
    "code": "invalid_number",
    "message": "Your card number is invalid.",
    "param": "card[number]",
    "status": 400,
    "type": "card_error"
  }
}

トークンIDまたはカードを保有している顧客IDを指定して支払いを作成します。 なお、以前はカードオブジェクトの指定ができましたが非通過対応により既に当該パラメーターは利用出来ないようになっております。 詳しくは カード情報非通過化対応のお願い をご覧ください。

テスト用のキーでは、本番用の決済ネットワークへは接続されず、実際の請求が行われることもありません。 本番用のキーでは、決済ネットワークで処理が行われ、実際の請求が行われます。

支払いを確定せずに、カードの認証と支払い額のみ確保する場合は、 capturefalse を指定してください。 このとき expiry_days を指定することで、認証の期間を定めることができます。 expiry_days はデフォルトで7日となっており、1日~60日の間で設定が可能です。なお60日に設定した場合、認証期限は59日後の11:59PM(日本時間)までになります。また確保されました与信枠は、expiry_days で設定されました期間を過ぎると解放されるようなっております。

引数


amount Integer

50~9,999,999の整数

amountcurrency、もしくはprodcutのどちらかは必須


currency String

3文字のISOコード(現状 “jpy” のみサポート)

amountcurrency、もしくはprodcutのどちらかは必須


product String

プロダクトID

amountcurrency、もしくはprodcutのどちらかは必須


customer String

顧客ID

合わせて顧客の保有するカードIDcard に指定することで、そのカードを支払いに利用できます。 card を省略した場合はデフォルトカードとして登録されているものが利用されます。

cardcustomerのどちらかは必須


card String

トークンIDを指定することで、一度限りの支払いが可能です。 カード情報を使い回したい場合はCustomer (顧客)を利用ください。

customer を指定している場合、カードIDを指定することで、顧客のデフォルトカード以外のカードを利用できます。

cardcustomerのどちらかは必須


description String

概要


capture Boolean

支払い処理を確定するかどうか

falseの場合、カードの認証と支払い額の確保のみ行う


expiry_days Integer

認証状態が失効するまでの日数


metadata Object

キーバリューの任意データ


platform_fee Integer

PAY.JP Platform のみ設定可能

プラットフォーマーに振り分けられる入金金額。 指定した場合、テナントの platform_fee_rate は無視され、この金額が優先されます。レスポンスの platform_fee_rate はnullとなります。

指定可能な金額はテナントの payjp_fee_included の値に依って以下の通り異なります。

tenant.payjp_fee_included charge.platform_fee に指定可能な範囲
true charge.amountの5% ~ 100%
false charge.amountの0% ~ 95%

tenant String 必須

PAY.JP Platform のみ設定可能

テナントID

レスポンス

作成されたchargeオブジェクト

支払い情報を取得

GET https://api.pay.jp/v1/charges/:id

curl https://api.pay.jp/v1/charges/ch_fa990a4c10672a93053a774730b0a \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Charge::retrieve("ch_fa990a4c10672a93053a774730b0a");
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.retrieve('ch_fa990a4c10672a93053a774730b0a');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Charge.retrieve("ch_fa990a4c10672a93053a774730b0a");

レスポンス

{
  "amount": 3500,
  "amount_refunded": 0,
  "captured": true,
  "captured_at": 1433127983,
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1583375140,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_6845da1a8651f889bc432362dfcb",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": null,
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_fa990a4c10672a93053a774730b0a",
  "livemode": false,
  "metadata": null,
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": false,
  "subscription": null
}

エラーレスポンス

{
  "error": {
    "message": "There is no charge with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

生成された支払い情報を取得します。

引数

なし

レスポンス

指定したidのchargeオブジェクト

支払い情報を更新

POST https://api.pay.jp/v1/charges/:id

curl https://api.pay.jp/v1/charges/ch_fa990a4c10672a93053a774730b0a \
-u sk_test_c62fade9d045b54cd76d7036: \
-d description=Updated
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = payjp.Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
charge.description='Updated'
charge.save()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = Payjp::Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
charge.description='Updated'
charge.save
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$ch = \Payjp\Charge::retrieve("ch_fa990a4c10672a93053a774730b0a");
$ch->description = "Updated";
$ch->save();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.update('ch_fa990a4c10672a93053a774730b0a', {
  description: 'Updated'
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Charge ch = Charge.retrieve("ch_fa990a4c10672a93053a774730b0a");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("description", "Updated");
ch.update(updateParams);

レスポンス

{
  "amount": 3500,
  "amount_refunded": 0,
  "captured": true,
  "captured_at": 1433127983,
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1583375140,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_6845da1a8651f889bc432362dfcb",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": "Updated",
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_fa990a4c10672a93053a774730b0a",
  "livemode": false,
  "metadata": null,
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": false,
  "subscription": null
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to charge.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

支払い情報を更新します。

引数


description String

概要


metadata Object

キーバリューの任意データ

レスポンス

更新されたchargeオブジェクト

返金する

POST https://api.pay.jp/v1/charges/:id/refund

curl https://api.pay.jp/v1/charges/ch_fa990a4c10672a93053a774730b0a/refund \
-u sk_test_c62fade9d045b54cd76d7036: \
-XPOST
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = payjp.Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
charge.refund()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = Payjp::Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
charge.refund
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$ch = \Payjp\Charge::retrieve("ch_fa990a4c10672a93053a774730b0a");
$ch->refund();
\\一部返金する場合
$ch->refund(array("amount" => 300));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.refund('ch_fa990a4c10672a93053a774730b0a', {amount: 1});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Charge ch = Charge.retrieve("ch_fa990a4c10672a93053a774730b0a");
ch.refund();

レスポンス

{
  "amount": 3500,
  "amount_refunded": 3500,
  "captured": true,
  "captured_at": 1433127983,
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1583375140,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_6845da1a8651f889bc432362dfcb",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": "Updated",
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_fa990a4c10672a93053a774730b0a",
  "livemode": false,
  "metadata": null,
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": true,
  "subscription": null
}

エラーレスポンス

{
  "error": {
    "message": "Charge `ch_fa990a4c10672a93053a774730b0a` has already been refunded.",
    "status": 400,
    "type": "client_error"
  }
}

支払い済みとなった処理を返金します。全額返金、及び amount を指定することで金額の部分返金を行うことができます。また確定していない支払いも取り消すことができますが amount を指定して部分返金をすることはできません。

なお返金可能な期限につきましては売上作成より180日以内となります。

引数


amount Integer

1~9,999,999の整数


refund_reason string

返金理由

レスポンス

返金後の状態のchargeオブジェクト

支払いを再認証する

POST https://api.pay.jp/v1/charges/:id/reauth

curl https://api.pay.jp/v1/charges/ch_fa990a4c10672a93053a774730b0a/reauth \
-u sk_test_c62fade9d045b54cd76d7036: \

レスポンス

{
  "amount": 775,
  "amount_refunded": 0,
  "captured": false,
  "captured_at": null,
  "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": 1470087896,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 12,
    "exp_year": 2017,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_d3f7bb8572250f8c5ab1328e4764",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1470088864,
  "currency": "jpy",
  "customer": "cus_137f2aec147eeafe849841d093a3",
  "description": null,
  "expired_at": 1470175385,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_82a41a81849c9e354c774cbd2d9e0",
  "livemode": false,
  "metadata": {},
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": false,
  "subscription": null
}

エラーレスポンス

{
  "error": {
    "message": "There is no charge with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

各種SDKは順次対応予定です

認証状態となった処理待ちの支払いを再認証します。 captured="false" の支払いが対象です。 expiry_days を指定することで、新たな認証の期間を定めることができます。 expiry_days はデフォルトで7日となっており、1日~60日の間で設定が可能です。なお60日に設定した場合、認証期限は59日後の11:59PM(日本時間)までになります。

再認証が必要な場合は認証状態の charge を返金し、新たに支払いを作成 することを推奨いたします。

このAPIは認証済みの与信をキャンセルせず別の与信を作るため、同じ金額で認証済みでも失敗したり、デビットカードなどでは一度目の認証(capture=falseの支払い)と含めて二重に金額が引き落とされることがあります。

引数


expiry_days Integer

認証状態が失効するまでの日数

レスポンス

再認証後の状態のchargeオブジェクト

支払い処理を確定する

POST https://api.pay.jp/v1/charges/:id/capture

curl https://api.pay.jp/v1/charges/ch_cce2fce62e9cb5632b3d38b0b1621/capture \
-u sk_test_c62fade9d045b54cd76d7036: \
-XPOST
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = payjp.Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
charge.capture()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = Payjp::Charge.retrieve('ch_cce2fce62e9cb5632b3d38b0b1621')
charge.capture
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$ch = \Payjp\Charge::retrieve("ch_cce2fce62e9cb5632b3d38b0b1621");
$ch->capture();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.capture('ch_fa990a4c10672a93053a774730b0a', {});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Charge ch = Charge.retrieve("ch_cce2fce62e9cb5632b3d38b0b1621");
ch.capture();

レスポンス

{
  "amount": 3500,
  "amount_refunded": 0,
  "captured": true,
  "captured_at": 1433128911,
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1583375140,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_6845da1a8651f889bc432362dfcb",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": null,
  "expired_at": 1433429999,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_cce2fce62e9cb5632b3d38b0b1621",
  "livemode": false,
  "metadata": null,
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": false,
  "subscription": null
}

エラーレスポンス

{
  "error": {
    "message": "Charge `ch_cce2fce62e9cb5632b3d38b0b1621` has already been captured.",
    "status": 400,
    "type": "client_error"
  }
}

認証状態となった処理待ちの支払い処理を確定させます。具体的には captured="false" となった支払いが該当します。

引数


amount Integer

50~9,999,999の整数

これをセットすることで、支払い生成時の金額と異なる金額の支払い処理を行うことができます。 ただし支払い生成時の金額よりも少額である必要があるためご注意ください。

セットした場合、レスポンスの amount_refunded に認証時の amount との差額が入ります。 例えば、認証時に amount=500 で作成し、 amount=400 で支払い確定を行った場合、 amount_refunded=100 となり、確定金額が400円に変更された状態で支払いが確定されます。

レスポンス

支払いが確定された状態のchargeオブジェクト

支払いリストを取得

GET https://api.pay.jp/v1/charges

curl 'https://api.pay.jp/v1/charges?limit=3&offset=10' \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Charge.all(limit=3, offset=10)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Charge.all(limit: 3, offset: 10)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Charge::all(array("limit" => 3, "offset" => 10));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.list({
  limit: 3,
  offset: 10
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> chargeParams = new HashMap<String, Object>();
chargeParams.put("limit", 3);
chargeParams.put("offset", 10);
Charge.all(chargeParams);

レスポンス

{
  "count": 1,
  "data": [
    {
      "amount": 1000,
      "amount_refunded": 0,
      "captured": true,
      "captured_at": 1432965397,
      "card": {
        "address_city": "\u8d64\u5742",
        "address_line1": "7-4",
        "address_line2": "203",
        "address_state": "\u6e2f\u533a",
        "address_zip": "1070050",
        "address_zip_check": "passed",
        "brand": "Visa",
        "country": "JP",
        "created": 1432965397,
        "cvc_check": "passed",
        "customer": null,
        "exp_month": 12,
        "exp_year": 2016,
        "fingerprint": "e1d8225886e3a7211127df751c86787f",
        "id": "car_7a79b41fed704317ec0deb4ebf93",
        "last4": "4242",
        "name": "Test Hodler",
        "object": "card"
      },
      "created": 1432965397,
      "currency": "jpy",
      "customer": "cus_67fab69c14d8888bba941ae2009b",
      "description": "test charge",
      "expired_at": null,
      "failure_code": null,
      "failure_message": null,
      "id": "ch_6421ddf0e12a5e5641d7426f2a2c9",
      "livemode": false,
      "metadata": null,
      "object": "charge",
      "paid": true,
      "refund_reason": null,
      "refunded": false,
      "subscription": null
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/charges"
}

エラーレスポンス

{
  "error": {
    "message": "Invalid query string.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

生成した支払い情報のリストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得


customer String

絞り込みたい顧客ID


subscription String

絞り込みたい定期課金ID


tenant String

PAY.JP Platformのみ指定可能

絞り込みたいテナントID

レスポンス

chargeオブジェクトlistオブジェクト

Customer (顧客)

顧客を管理するためのオブジェクトです。

顧客における都度の支払いや定期購入、複数カードの管理など、さまざまなことができます。作成した顧客は、あとからカードを追加・更新・削除したり、顧客自体を削除することができます。

customerオブジェクト

customerオブジェクト

{
  "cards": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_121673955bd7aa144de5a8f6c262/cards"
  },
  "created": 1433127983,
  "default_card": null,
  "description": "test",
  "email": null,
  "id": "cus_121673955bd7aa144de5a8f6c262",
  "livemode": false,
  "metadata": null,
  "object": "customer",
  "subscriptions": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_121673955bd7aa144de5a8f6c262/subscriptions"
  }
}

プロパティ


object String

“customer"の固定文字列


id String

一意なオブジェクトを示す文字列


livemode Boolean

本番環境かどうか


created Integer

この顧客作成時のUTCタイムスタンプ


default_card String

支払いにデフォルトで使用されるカードのcar_から始まるID


cards Object

顧客に紐づけられているカードオブジェクトlistオブジェクト


email String

メールアドレス


description String

概要


subscriptions Object

顧客が購読している定期課金オブジェクトlistオブジェクト


metadata Object

キーバリューの任意データ

cardオブジェクト

cardオブジェクト

{
  "address_city": null,
  "address_line1": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": "unchecked",
  "brand": "Visa",
  "country": null,
  "created": 1583375140,
  "customer": null,
  "cvc_check": "passed",
  "exp_month": 2,
  "exp_year": 2024,
  "fingerprint": "e1d8225886e3a7211127df751c86787f",
  "id": "car_6845da1a8651f889bc432362dfcb",
  "last4": "4242",
  "livemode": false,
  "metadata": {},
  "name": null,
  "object": "card"
}

プロパティ


object String

"card"の固定文字列


id String

car_で始まり一意なオブジェクトを示す、最大32桁の文字列


created Integer

カード作成時のタイムスタンプ


name String

カード保有者名(e.g. "YUI ARAGAKI”)


last4 String

カード番号の下四桁


exp_month Integer

有効期限月


exp_year Integer

有効期限年


brand String

カードブランド名


cvc_check String

CVCコードチェックの結果


fingerprint String

このクレジットカード番号に紐づく値。

同一番号のカードからは同一の値が生成されることが保証されており、 トークン化の度にトークンIDは変わりますが、この値は変わりません。


address_state String

都道府県


address_city String

市区町村


address_line1 String

番地など


address_line2 String

建物名など


country String

2桁のISOコード(e.g. JP)


address_zip String

郵便番号


address_zip_check String

郵便番号存在チェックの結果


metadata Object

キーバリューの任意データ

顧客を作成

POST https://api.pay.jp/v1/customers

curl https://api.pay.jp/v1/customers \
-u sk_test_c62fade9d045b54cd76d7036: \
-d description=test
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Customer.create(
    description='test'
)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Customer.create(
  description: 'test'
)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Customer::create(array(
        "description" => "test"
));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.create({
  description: 'test'
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("description", "test");
Customer.create(customerParams);

レスポンス

{
  "cards": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_121673955bd7aa144de5a8f6c262/cards"
  },
  "created": 1433127983,
  "default_card": null,
  "description": "test",
  "email": null,
  "id": "cus_121673955bd7aa144de5a8f6c262",
  "livemode": false,
  "metadata": null,
  "object": "customer",
  "subscriptions": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_121673955bd7aa144de5a8f6c262/subscriptions"
  }
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to customer.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

メールアドレスやIDなどを指定して顧客を作成します。

作成と同時にカード情報を登録する場合、トークンIDを指定します。

以前はカードオブジェクトの指定ができましたが非通過対応により既に当該パラメーターは利用出来ないようになっております。 詳しくは カード情報非通過化対応のお願い をご覧ください。

作成した顧客やカード情報はあとから更新・削除することができます。

引数


email String

メールアドレス

RFC 3696に則ったバリデーションを行なっているため、ピリオドが連続する場合など、RFCに準拠せず発行されたメールアドレスは登録できません。


description String

概要


id String

顧客ID

100桁までの一意な文字列を指定可能。

未指定時はcus_で始まる32桁までの一意な文字列が自動生成されます。


card String

トークンID(トークンIDを指定)


metadata Object

キーバリューの任意データ

レスポンス

作成されたcustomerオブジェクト

顧客情報を取得

GET https://api.pay.jp/v1/customers/:id

curl https://api.pay.jp/v1/customers/cus_121673955bd7aa144de5a8f6c262 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Customer.retrieve('cus_121673955bd7aa144de5a8f6c262')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Customer.retrieve('cus_121673955bd7aa144de5a8f6c262')

\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Customer::retrieve("cus_121673955bd7aa144de5a8f6c262");
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.retrieve('cus_121673955bd7aa144de5a8f6c262');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer.retrieve("cus_121673955bd7aa144de5a8f6c262");

レスポンス

{
  "cards": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_121673955bd7aa144de5a8f6c262/cards"
  },
  "created": 1433127983,
  "default_card": null,
  "description": "test",
  "email": null,
  "id": "cus_121673955bd7aa144de5a8f6c262",
  "livemode": false,
  "metadata": null,
  "object": "customer",
  "subscriptions": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_121673955bd7aa144de5a8f6c262/subscriptions"
  }
}

エラーレスポンス

{
  "error": {
    "message": "There is no customer with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

生成した顧客情報を取得します。

引数

なし

レスポンス

指定したidのcustomerオブジェクト

顧客情報を更新

POST https://api.pay.jp/v1/customers/:id

curl https://api.pay.jp/v1/customers/cus_121673955bd7aa144de5a8f6c262 \
-u sk_test_c62fade9d045b54cd76d7036: \
-d email=added@example.com
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_121673955bd7aa144de5a8f6c262')
customer.email = 'added@example.com'
customer.save()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_121673955bd7aa144de5a8f6c262')
customer.email = 'added@example.com'
customer.save
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$cu = \Payjp\Customer::retrieve("cus_121673955bd7aa144de5a8f6c262");
$cu->email = "added@example.com";
$cu->save();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.update('cus_121673955bd7aa144de5a8f6c262', {
  email: 'example@example.com'
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_121673955bd7aa144de5a8f6c262");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("email", "added@example.com");
cu.update(updateParams);

レスポンス

{
  "cards": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_121673955bd7aa144de5a8f6c262/cards"
  },
  "created": 1433127983,
  "default_card": null,
  "description": "test",
  "email": null,
  "id": "cus_121673955bd7aa144de5a8f6c262",
  "livemode": false,
  "metadata": null,
  "object": "customer",
  "subscriptions": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_121673955bd7aa144de5a8f6c262/subscriptions"
  }
}

エラーレスポンス

{
  "error": {
    "message": "There is no customer with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

生成した顧客情報を更新したり、新たなカードを顧客に追加することができます。また default_card に保持しているカードIDを指定することで、メイン利用のカードを変更することもできます。

以前はカードオブジェクトの指定ができましたが非通過対応により既に当該パラメーターは利用出来ないようになっております。 詳しくは カード情報非通過化対応のお願い をご覧ください。

引数


email String

メールアドレス


description String

概要


default_card String

保持しているカードID


card String

トークンID(トークンIDを指定)


metadata Object

キーバリューの任意データ

レスポンス

更新されたcustomerオブジェクト

顧客を削除

DELETE https://api.pay.jp/v1/customers/:id

curl https://api.pay.jp/v1/customers/cus_121673955bd7aa144de5a8f6c262 \
-u sk_test_c62fade9d045b54cd76d7036: \
-XDELETE
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_121673955bd7aa144de5a8f6c262')
customer.delete()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_121673955bd7aa144de5a8f6c262')
customer.delete
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$cu = \Payjp\Customer::retrieve("cus_121673955bd7aa144de5a8f6c262");
$cu->delete();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.delete('cus_121673955bd7aa144de5a8f6c262');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_121673955bd7aa144de5a8f6c262");
cu.delete();

レスポンス

{
  "deleted": true,
  "id": "cus_121673955bd7aa144de5a8f6c262",
  "livemode": false
}

エラーレスポンス

{
  "error": {
    "message": "There is no customer with ID: cus_121673955bd7aa144de5a8f6c262",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

顧客を削除します。顧客に紐付く定期課金がある場合は、同時にそれらの定期課金も削除されます。

引数

なし

レスポンス


deleted Boolean

trueが入ります


id String

削除した顧客ID


livemode Boolean

本番環境かどうか

顧客リストを取得

GET https://api.pay.jp/v1/customers

curl https://api.pay.jp/v1/customers?limit=3&offset=10 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Customer.all(limit=3, offset=10)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Customer.all(limit: 3, offset: 10)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Customer::all(array("limit" => 3, "offset" => 10));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.list({
  limit: 3,
  offset: 10
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> customerParams = new HashMap<String, Object>();
customerParams.put("limit", 3);
customerParams.put("offset", 10);
Customer.all(customerParams);

レスポンス

{
  "count": 1,
  "data": [
    {
      "cards": {
        "count": 0,
        "data": [],
        "has_more": false,
        "object": "list",
        "url": "/v1/customers/cus_842e21be700d1c8156d9dac025f6/cards"
      },
      "created": 1433059905,
      "default_card": null,
      "description": "test",
      "email": null,
      "id": "cus_842e21be700d1c8156d9dac025f6",
      "livemode": false,
      "metadata": null,
      "object": "customer",
      "subscriptions": {
        "count": 0,
        "data": [],
        "has_more": false,
        "object": "list",
        "url": "/v1/customers/cus_842e21be700d1c8156d9dac025f6/subscriptions"
      }
    }
  ],
  "has_more": true,
  "object": "list",
  "url": "/v1/customers"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to customer.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

生成した顧客情報のリストを取得します。リストは、直近で生成された順番に取得されます。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得

レスポンス

customerオブジェクトのリスト。

リストは、直近で生成された順番に取得されます。

顧客のカードを作成

POST https://api.pay.jp/v1/customers/:id/cards

curl https://api.pay.jp/v1/customers/cus_4df4b5ed720933f4fb9e28857517/cards \
-u sk_test_c62fade9d045b54cd76d7036: \
-d card=tok_76e202b409f3da51a0706605ac81
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_121673955bd7aa144de5a8f6c262')
customer.cards.create(
    card='tok_76e202b409f3da51a0706605ac81'
)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.cards.create(
  card: 'tok_76e202b409f3da51a0706605ac81'
)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$cu = \Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517");
$cu->cards->create(array(
        "card" => "tok_76e202b409f3da51a0706605ac81"
));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.cards.create('cus_121673955bd7aa144de5a8f6c262', {
  card: 'tok_76e202b409f3da51a0706605ac81',
  default: true,
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_4df4b5ed720933f4fb9e28857517");
cu.createCard("card", "tok_76e202b409f3da51a0706605ac81")

レスポンス

{
  "address_city": null,
  "address_line1": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": "unchecked",
  "brand": "Visa",
  "country": null,
  "created": 1583375140,
  "customer": null,
  "cvc_check": "passed",
  "exp_month": 2,
  "exp_year": 2024,
  "fingerprint": "e1d8225886e3a7211127df751c86787f",
  "id": "car_6845da1a8651f889bc432362dfcb",
  "last4": "4242",
  "livemode": false,
  "metadata": {},
  "name": null,
  "object": "card"
}

エラーレスポンス

{
  "error": {
    "message": "Please provide either token or card parameters.",
    "param": "card",
    "status": 400,
    "type": "client_error"
  }
}

トークンIDを指定して、新たにカードを追加します。ただし同じカード番号および同じ有効期限年/月のカードは、重複追加することができません。default を指定することで、作成したカードを顧客のメイン利用のカードに設定することができます。

引数


card String

トークンID


metadata Object

キーバリューの任意データ


default Boolean

メイン利用のカードに設定するかどうか

レスポンス

作成されたcardオブジェクト

顧客のカード情報を取得

GET https://api.pay.jp/v1/customers/:id/cards/:card_id

curl https://api.pay.jp/v1/customers/cus_4df4b5ed720933f4fb9e28857517/cards/car_f7d9fa98594dc7c2e42bfcd641ff \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.cards.retrieve('car_f7d9fa98594dc7c2e42bfcd641ff')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.cards.retrieve('car_f7d9fa98594dc7c2e42bfcd641ff')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$cu = \Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517");
$cu->cards->retrieve("car_f7d9fa98594dc7c2e42bfcd641ff");
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.cards.retrieve(
  'cus_121673955bd7aa144de5a8f6c262',
  'car_f7d9fa98594dc7c2e42bfcd641ff'
);
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_4df4b5ed720933f4fb9e28857517");
cu.getCards().retrieve("car_f7d9fa98594dc7c2e42bfcd641ff");

レスポンス

{
  "address_city": null,
  "address_line1": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": "unchecked",
  "brand": "Visa",
  "country": null,
  "created": 1583375140,
  "customer": null,
  "cvc_check": "passed",
  "exp_month": 2,
  "exp_year": 2024,
  "fingerprint": "e1d8225886e3a7211127df751c86787f",
  "id": "car_6845da1a8651f889bc432362dfcb",
  "last4": "4242",
  "livemode": false,
  "metadata": {},
  "name": null,
  "object": "card"
}

エラーレスポンス

{
  "error": {
    "message": "There is no card with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

顧客の特定のカード情報を取得します。

引数

なし

レスポンス

指定したidのcardオブジェクト

顧客のカードを更新

POST https://api.pay.jp/v1/customers/:id/cards/:card_id

curl https://api.pay.jp/v1/customers/cus_4df4b5ed720933f4fb9e28857517/cards/car_f7d9fa98594dc7c2e42bfcd641ff \
-u sk_test_c62fade9d045b54cd76d7036: \
-d name="PAY TARO"
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
card = customer.cards.retrieve('car_f7d9fa98594dc7c2e42bfcd641ff')
card.name="PAY TARO"
card.save()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
card = customer.cards.retrieve('car_f7d9fa98594dc7c2e42bfcd641ff')
card.name="PAY TARO"
card.save
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$cu = \Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517");
$card = $cu->cards->retrieve("car_f7d9fa98594dc7c2e42bfcd641ff");
$card->name="PAY TARO";
$card->save();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.cards.update(
  'cus_121673955bd7aa144de5a8f6c262',
  'car_f7d9fa98594dc7c2e42bfcd641ff', {
  name: "PAY TARO"
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_4df4b5ed720933f4fb9e28857517");
Card ca = cu.getCards().retrieve("car_f7d9fa98594dc7c2e42bfcd641ff");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", "PAY TARO");
ca.update(updateParams);

レスポンス

{
  "address_city": null,
  "address_line1": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,
  "address_zip_check": "unchecked",
  "brand": "Visa",
  "country": null,
  "created": 1433127983,
  "customer": null,
  "cvc_check": "unchecked",
  "exp_month": 12,
  "exp_year": 2026,
  "fingerprint": "e1d8225886e3a7211127df751c86787f",
  "id": "car_f7d9fa98594dc7c2e42bfcd641ff",
  "last4": "4242",
  "livemode": false,
  "metadata": null,
  "name": null,
  "object": "card"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to card.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

顧客の特定のカード情報を更新します。

以前はexp_month , exp_year , cvc の指定ができましたが非通過対応により既に当該パラメーターは利用出来ないようになっております。 詳しくは カード情報非通過化対応のお願い をご覧ください。

引数


address_state String

都道府県


address_city String

市区町村


address_line1 String

番地など


address_line2 String

建物名など


address_zip String

郵便番号


country String

2桁のISOコード(e.g. JP)


name String

カード保有者名(e.g. “YUI ARAGAKI”)


metadata Object

キーバリューの任意データ

レスポンス

更新されたcardオブジェクト

顧客のカードを削除

DELETE https://api.pay.jp/v1/customers/:id/cards/:card_id

curl https://api.pay.jp/v1/customers/cus_4df4b5ed720933f4fb9e28857517/cards/car_f7d9fa98594dc7c2e42bfcd641ff \
-u sk_test_c62fade9d045b54cd76d7036: \
-XDELETE
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
card = customer.cards.retrieve('car_f7d9fa98594dc7c2e42bfcd641ff')
card.delete()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
card = customer.cards.retrieve('car_f7d9fa98594dc7c2e42bfcd641ff')
card.delete
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$cu = \Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517");
$card = $cu->cards->retrieve("car_f7d9fa98594dc7c2e42bfcd641ff");
$card->delete();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.cards.delete(
  'cus_121673955bd7aa144de5a8f6c262',
  'car_f7d9fa98594dc7c2e42bfcd641ff'
);
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_4df4b5ed720933f4fb9e28857517");
Card ca = cu.getCards().retrieve("car_f7d9fa98594dc7c2e42bfcd641ff");
ca.delete();

レスポンス

{
  "deleted": true,
  "id": "car_f7d9fa98594dc7c2e42bfcd641ff",
  "livemode": false
}

エラーレスポンス

{
  "error": {
    "message": "There is no card with ID: car_f7d9fa98594dc7c2e42bfcd641ff",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

顧客の特定のカードを削除します。

引数

なし

レスポンス


deleted Boolean

trueが入ります


id String

削除したカードID


livemode Boolean

本番環境かどうか

顧客のカードリストを取得

GET https://api.pay.jp/v1/customers/:id/cards

curl "https://api.pay.jp/v1/customers/cus_4df4b5ed720933f4fb9e28857517/cards?limit=3&offset=1" \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
card = customer.cards.all(limit=3, offset=10)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
card = customer.cards.all(limit: 3, offset: 10)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517")->cards->all(array("limit"=>3, "offset"=>1));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.cards.list('cus_121673955bd7aa144de5a8f6c262', {
  limit: 3,
  offset: 10
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> listParams = new HashMap<String, Object>();
listParams.put("limit", 3);
listParams.put("offset", 1);
Customer.retrieve("cus_4df4b5ed720933f4fb9e28857517").getCards().all(listParams);

レスポンス

{
  "count": 1,
  "data": [
    {
      "address_city": null,
      "address_line1": null,
      "address_line2": null,
      "address_state": null,
      "address_zip": null,
      "address_zip_check": "unchecked",
      "brand": "Visa",
      "country": null,
      "created": 1583375140,
      "customer": null,
      "cvc_check": "passed",
      "exp_month": 2,
      "exp_year": 2024,
      "fingerprint": "e1d8225886e3a7211127df751c86787f",
      "id": "car_6845da1a8651f889bc432362dfcb",
      "last4": "4242",
      "livemode": false,
      "metadata": {},
      "name": null,
      "object": "card"
    }
  ],
  "object": "list",
  "has_more": false,
  "url": "/v1/customers/cus_4df4b5ed720933f4fb9e28857517/cards"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to card.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

顧客の保持しているカードリストを取得します。リストは、直近で生成された順番に取得されます。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ(sec)

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ(sec)

指定したタイムスタンプ以前に作成されたデータのみ取得

レスポンス

cardオブジェクトのリスト。

リストは、直近で生成された順番に取得されます。

顧客の定期課金情報を取得

GET https://api.pay.jp/v1/customers/:id/subscriptions/:subscription_id

curl https://api.pay.jp/v1/customers/cus_4df4b5ed720933f4fb9e28857517/subscriptions/sub_567a1e44562932ec1a7682d746e0 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.subscriptions.retrieve('sub_567a1e44562932ec1a7682d746e0')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.subscriptions.retrieve('sub_567a1e44562932ec1a7682d746e0')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$cu = \Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517");
$cu->subscriptions->retrieve("sub_567a1e44562932ec1a7682d746e0");
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.subscriptions.retrieve(
  'cus_121673955bd7aa144de5a8f6c262',
  'sub_567a1e44562932ec1a7682d746e0'
);
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_4df4b5ed720933f4fb9e28857517");
Map<String, Object> listParams = new HashMap<String, Object>();
listParams.put("limit", 3);
cu.getSubscriptions().all(listParams);

レスポンス

{
  "canceled_at": null,
  "created": 1433127983,
  "current_period_end": 1435732422,
  "current_period_start": 1433140422,
  "customer": "cus_4df4b5ed720933f4fb9e28857517",
  "id": "sub_567a1e44562932ec1a7682d746e0",
  "livemode": false,
  "metadata": null,
  "object": "subscription",
  "paused_at": null,
  "plan": {
    "amount": 1000,
    "billing_day": null,
    "created": 1432965397,
    "currency": "jpy",
    "id": "pln_9589006d14aad86aafeceac06b60",
    "livemode": false,
    "metadata": {},
    "interval": "month",
    "name": "test plan",
    "object": "plan",
    "trial_days": 0
  },
  "prorate": false,
  "resumed_at": null,
  "start": 1433140422,
  "status": "active",
  "trial_end": null,
  "trial_start": null
}

エラーレスポンス

{
  "error": {
    "message": "There is no subscription with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

顧客の特定の定期課金情報を取得します。

引数

なし

レスポンス

指定したidのsubscriptionオブジェクト

顧客の定期課金リストを取得

GET https://api.pay.jp/v1/customers/:id/subscriptions

curl 'https://api.pay.jp/v1/customers/cus_4df4b5ed720933f4fb9e28857517/subscriptions?limit=3' \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.subscriptions.all(limit=3)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.subscriptions.all(limit: 3)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517")->subscriptions->all(array("limit"=>3));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.subscriptions.list('cus_121673955bd7aa144de5a8f6c262', {
  limit: 3,
  offset: 10
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_4df4b5ed720933f4fb9e28857517");
Map<String, Object> listParams = new HashMap<String, Object>();
listParams.put("limit", 3);
cu.getSubscriptions().all(listParams);

レスポンス

{
  "count": 1,
  "data": [
    {
      "canceled_at": null,
      "created": 1433127983,
      "current_period_end": 1435732422,
      "current_period_start": 1433140422,
      "customer": "cus_4df4b5ed720933f4fb9e28857517",
      "id": "sub_567a1e44562932ec1a7682d746e0",
      "livemode": false,
      "metadata": null,
      "object": "subscription",
      "paused_at": null,
      "plan": {
        "amount": 1000,
        "billing_day": null,
        "created": 1432965397,
        "currency": "jpy",
        "id": "pln_9589006d14aad86aafeceac06b60",
        "livemode": false,
        "metadata": {},
        "interval": "month",
        "name": "test plan",
        "object": "plan",
        "trial_days": 0
      },
      "prorate": false,
      "resumed_at": null,
      "start": 1433140422,
      "status": "active",
      "trial_end": null,
      "trial_start": null
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/customers/cus_4df4b5ed720933f4fb9e28857517/subscriptions"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to subscription.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

顧客の定期課金リストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得


plan String

プランID


status String

定期課金ステータス。

active, trial, canceled または paused のみ指定可能。

レスポンス

subscriptionオブジェクトのリスト。

リストは、直近で生成された順番に取得されます。

Plan (プラン)

定期購入に使用するプラン情報です。

金額、期間(月次、年次)、支払い実行日(1-31)、トライアル日数などを指定して、 あなたのビジネスに必要なさまざまなプランを生成することができます。

planオブジェクト

planオブジェクト

{
  "amount": 500,
  "billing_day": null,
  "created": 1433127983,
  "currency": "jpy",
  "id": "pln_45dd3268a18b2837d52861716260",
  "interval": "month",
  "livemode": false,
  "metadata": null,
  "name": null,
  "object": "plan",
  "trial_days": 30
}

プロパティ


id String

プランID。一意なplanオブジェクトを識別する文字列。


object String

“plan"の固定文字列


livemode Boolean

本番環境かどうか


created Integer

プラン作成時のUTCタイムスタンプ


amount Integer

プランの金額


currency String

3文字のISOコード(現状 "jpy” のみサポート)


interval String

課金周期(“month"もしくは"year”)


name String

プラン名


trial_days Integer

トライアル日数(0-365)


billing_day Integer

月次プランの課金日(1-31, 年次の場合は"null")

指定した日が存在しない月の場合、定期課金におけるサイクルは自動的に月末に調整されるため、例えば31を指定した場合は常に月末が課金日となります。

また定期課金における課金時刻は、この指定日の日本時間午前9:00に固定されます。

billing_dayを指定しない場合は最初に課金された時刻(UTC)からのサイクルになります。課金時刻は固定されません。それ以降、サイクル開始時刻と同じ日がない場合、月末の日付に自動で調整され、以降はその日に課金されます。


metadata Object

キーバリューの任意データ

プランを作成

POST https://api.pay.jp/v1/plans

curl https://api.pay.jp/v1/plans \
-u sk_test_c62fade9d045b54cd76d7036: \
-d amount=500 \
-d currency=jpy \
-d interval=month \
-d trial_days=30
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Plan.create(
    amount=500,
    currency='jpy',
    interval='month',
    trial_days=30
)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Plan.create(
  amount: 500,
  currency: 'jpy',
  interval: 'month',
  trial_days: 30
)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Plan::create(array(
        "amount" => 500,
        "currency" => "jpy",
        "interval" => "month",
        "trial_days" => 30,
));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.plans.create({
  amount: 500,
  currency: 'jpy',
  interval: 'month',
  trial_days: 30
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> planParams = new HashMap<String, Object>();
planParams.put("amount", 500);
planParams.put("currency", "jpy");
planParams.put("interval", "month");
planParams.put("trial_days", 30);
Plan.create(planParams);

レスポンス

{
  "amount": 500,
  "billing_day": null,
  "created": 1433127983,
  "currency": "jpy",
  "id": "pln_45dd3268a18b2837d52861716260",
  "interval": "month",
  "livemode": false,
  "metadata": null,
  "name": null,
  "object": "plan",
  "trial_days": 30
}

エラーレスポンス

{
  "error": {
    "code": "invalid_interval",
    "message": "Invalid interval",
    "param": "interval",
    "status": 400,
    "type": "client_error"
  }
}

金額や通貨などを指定して定期購入に利用するプランを生成します。

引数


amount Integer 必須

50~9,999,999の整数


currency String 必須

3文字のISOコード(現状 “jpy” のみサポート)


interval String 必須

月次課金であればmonthを、年次課金であればyearを指定下さい。

年次課金の場合、billing_dayは指定できません(現在作成はできますが、定期課金利用時にエラーとなります)。


id String

任意のプランID。一意に識別できる必要があり、重複する値を設定するとエラーとなります。


name String

プランの名前


trial_days Integer

トライアル日数

定期課金を作成時に、定期課金がトライアル状態(status: trial)となります。

なお、定期課金を作成時にもトライアルを追加したり、ここで指定したトライアル日数を無効にして作成することが可能です。


billing_day Integer

月次プラン(interval=month)のみに指定可能な課金日(1〜31)

指定した日が存在しない月の場合、定期課金におけるサイクルは自動的に月末に調整されるため、例えば31を指定した場合は常に月末が課金日となります。

また定期課金における課金時刻は、この指定日の日本時間午前9:00に固定されます。

billing_dayを指定しない場合は最初に課金された時刻(UTC)からのサイクルになります。課金時刻は固定されません。それ以降、サイクル開始時刻と同じ日がない場合、月末の日付に自動で調整され、以降はその日に課金されます。


metadata Object

キーバリューの任意データ


プラン情報を取得

GET https://api.pay.jp/v1/plans/:id

curl https://api.pay.jp/v1/plans/pln_45dd3268a18b2837d52861716260 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Plan.retrieve('pln_45dd3268a18b2837d52861716260')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Plan.retrieve('pln_45dd3268a18b2837d52861716260')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Plan::retrieve("pln_45dd3268a18b2837d52861716260");
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.plans.retrieve('pln_45dd3268a18b2837d52861716260');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Plan.retrieve("pln_45dd3268a18b2837d52861716260");

レスポンス

{
  "amount": 500,
  "billing_day": null,
  "created": 1433127983,
  "currency": "jpy",
  "id": "pln_45dd3268a18b2837d52861716260",
  "interval": "month",
  "livemode": false,
  "metadata": null,
  "name": null,
  "object": "plan",
  "trial_days": 30
}

エラーレスポンス

{
  "error": {
    "message": "There is no plan with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

特定のプラン情報を取得します。

引数

なし

レスポンス

指定したidのplanオブジェクト

プランを更新

POST https://api.pay.jp/v1/plans/:id

curl https://api.pay.jp/v1/plans/pln_45dd3268a18b2837d52861716260 \
-u sk_test_c62fade9d045b54cd76d7036: \
-d name=NewPlan
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
plan = payjp.Plan.retrieve('pln_45dd3268a18b2837d52861716260')
plan.name = 'NewPlan'
plan.save()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
plan = Payjp::Plan.retrieve('pln_45dd3268a18b2837d52861716260')
plan.name = 'NewPlan'
plan.save
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$p = \Payjp\Plan::retrieve("pln_45dd3268a18b2837d52861716260");
$p->name = "NewPlan";
$p->save();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.plans.update('pln_45dd3268a18b2837d52861716260', {
  name: 'NewPlan'
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Plan p = Plan.retrieve("pln_45dd3268a18b2837d52861716260");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("name", "NewPlan");
p.update(updateParams);

レスポンス

{
  "amount": 500,
  "billing_day": null,
  "created": 1433127983,
  "currency": "jpy",
  "id": "pln_45dd3268a18b2837d52861716260",
  "interval": "month",
  "livemode": false,
  "metadata": null,
  "name": "NewPlan",
  "object": "plan",
  "trial_days": 30
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to plan.",
    "param": "amount",
    "status": 400,
    "type": "client_error"
  }
}

プラン情報を更新します。

引数


name String

プランの名前


metadata Object

キーバリューの任意データ

レスポンス

更新されたplanオブジェクト

プランを削除

DELETE https://api.pay.jp/v1/plans/:id

curl https://api.pay.jp/v1/plans/pln_45dd3268a18b2837d52861716260 \
-u sk_test_c62fade9d045b54cd76d7036: \
-XDELETE
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
plan = payjp.Plan.retrieve('pln_45dd3268a18b2837d52861716260')
plan.delete()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
plan = Payjp::Plan.retrieve('pln_45dd3268a18b2837d52861716260')
plan.delete
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$p = \Payjp\Plan::retrieve("pln_45dd3268a18b2837d52861716260");
$p->delete();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.plans.delete('pln_45dd3268a18b2837d52861716260');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Plan p = Plan.retrieve("pln_45dd3268a18b2837d52861716260");
p.delete();

レスポンス

{
  "deleted": true,
  "id": "pln_45dd3268a18b2837d52861716260",
  "livemode": false
}

エラーレスポンス

{
  "error": {
    "message": "There is no plan with ID: pln_45dd3268a18b2837d52861716260",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

プランを削除します。

引数

なし

レスポンス


deleted Boolean

trueが入ります


id String

削除したプランID


livemode Boolean

本番環境かどうか

プランリストを取得

GET https://api.pay.jp/v1/plans

curl https://api.pay.jp/v1/plans?limit=3 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Plan.all(limit=3)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Plan.all(limit: 3)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Plan::all(array("limit" => 3));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.plans.list({
  limit: 3
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> listParams = new HashMap<String, Object>();
listParams.put("limit", 3);
Plan.all(listParams);

レスポンス

{
  "count": 3,
  "data": [
    {
      "amount": 1000,
      "billing_day": null,
      "created": 1432965397,
      "currency": "jpy",
      "id": "pln_acfbc08ae710da03ac2a3fcb2334",
      "interval": "month",
      "livemode": false,
      "metadata": null,
      "name": "test plan",
      "object": "plan",
      "trial_days": 0
    },
    {...},
    {...}
  ],
  "has_more": true,
  "object": "list",
  "url": "/v1/plans"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to plan.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

生成したプランのリストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)


offset Integer

基準点からのデータ取得を行う開始位置


since Integer

ここに指定したタイムスタンプ以降に作成されたデータを取得


until Integer

ここに指定したタイムスタンプ以前に作成されたデータを取得

レスポンス

planオブジェクトのリスト。

リストは、直近で生成された順番に取得されます。

Subscription (定期課金)

月もしくは年単位の定期的な支払い処理を行います。顧客IDとプランIDを指定して生成します。 顧客に複数紐付けるができ、停止・再開・キャンセル・削除もできます。

実装方法については チュートリアル - 定期課金 も参考ください。

原則として、定期課金は前払い式であり、課金が行われた時点から周期が開始します。

subscriptionオブジェクト

subscriptionオブジェクト

{
  "canceled_at": null,
  "created": 1433127983,
  "current_period_end": 1435732422,
  "current_period_start": 1433140422,
  "customer": "cus_4df4b5ed720933f4fb9e28857517",
  "id": "sub_567a1e44562932ec1a7682d746e0",
  "livemode": false,
  "metadata": null,
  "next_cycle_plan": null,
  "object": "subscription",
  "paused_at": null,
  "plan": {
    "amount": 1000,
    "billing_day": null,
    "created": 1432965397,
    "currency": "jpy",
    "id": "pln_9589006d14aad86aafeceac06b60",
    "livemode": false,
    "metadata": {},
    "interval": "month",
    "name": "test plan",
    "object": "plan",
    "trial_days": 0
  },
  "resumed_at": null,
  "start": 1433140422,
  "status": "active",
  "trial_end": null,
  "trial_start": null,
  "prorate": false
}

プロパティ


id String

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


object String

“subscription"の固定文字列


livemode Boolean

本番環境かどうか


created Integer

定期課金作成時のタイムスタンプ


start Integer

定期課金開始時のタイムスタンプ


customer String

定期課金を購読している顧客ID


plan Object

定期課金に紐付くplanオブジェクト


next_cycle_plan Object

planオブジェクト or null。

planオブジェクトが設定されている場合、次回サイクル更新時に指定のプランへと自動的に切り替えし、課金を試みます。 プランの切り替えは必ず行われますが、課金の有無は切り替わるプランの設定に依ります。 詳細は定期課金を更新の引数 next_cycle_plan の説明を参照ください。

切り替えが実施されたタイミングでこの値はnullとなります。


status String

trial, active, canceled または paused のいずれかの値。

定期課金の現在の状態を表し、active の場合のみ支払い処理が行われます。


prorate Boolean

日割り課金が有効かどうか


current_period_start Integer

現在の購読期間開始時のタイムスタンプ

原則として、定期課金は前払い式であり、課金が行われた時点から周期が開始します。


current_period_end Integer

現在の購読期間終了時のタイムスタンプ


trial_start Integer

トライアル期間開始時のタイムスタンプ


trial_end Integer

トライアル期間終了時のタイムスタンプ


paused_at Integer

定期課金が停止状態になった時のタイムスタンプ


canceled_at Integer

定期課金がキャンセル状態になった時のタイムスタンプ


resumed_at Integer

停止またはキャンセル状態の定期課金が有効状態になった時のタイムスタンプ


metadata Object

キーバリューの任意データ

定期課金を作成

POST https://api.pay.jp/v1/subscriptions

curl https://api.pay.jp/v1/subscriptions \
-u sk_test_c62fade9d045b54cd76d7036: \
-d customer=cus_4df4b5ed720933f4fb9e28857517 \
-d plan=pln_9589006d14aad86aafeceac06b60
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Subscription.create(
    plan='pln_9589006d14aad86aafeceac06b60',
    customer='cus_4df4b5ed720933f4fb9e28857517'
)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Subscription.create(
  plan: 'pln_9589006d14aad86aafeceac06b60',
  customer: 'cus_4df4b5ed720933f4fb9e28857517'
)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Subscription::create(
        array(
                "customer" => "cus_4df4b5ed720933f4fb9e28857517",
                "plan" => "pln_9589006d14aad86aafeceac06b60"
        )
);
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.create({
  plan: 'pln_9589006d14aad86aafeceac06b60',
  customer: 'cus_4df4b5ed720933f4fb9e28857517'
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> subscriptionParams = new HashMap<String, Object>();
subscriptionParams.put("plan", "pln_9589006d14aad86aafeceac06b60");
subscriptionParams.put("customer", "cus_4df4b5ed720933f4fb9e28857517");
Subscription.create(subscriptionParams);

レスポンス

{
  "canceled_at": null,
  "created": 1433127983,
  "current_period_end": 1435732422,
  "current_period_start": 1433140422,
  "customer": "cus_4df4b5ed720933f4fb9e28857517",
  "id": "sub_567a1e44562932ec1a7682d746e0",
  "livemode": false,
  "metadata": null,
  "next_cycle_plan": null,
  "object": "subscription",
  "paused_at": null,
  "plan": {
    "amount": 1000,
    "billing_day": null,
    "created": 1432965397,
    "currency": "jpy",
    "id": "pln_9589006d14aad86aafeceac06b60",
    "livemode": false,
    "metadata": {},
    "interval": "month",
    "name": "test plan",
    "object": "plan",
    "trial_days": 0
  },
  "resumed_at": null,
  "start": 1433140422,
  "status": "active",
  "trial_end": null,
  "trial_start": null,
  "prorate": false
}

エラーレスポンス

{
  "error": {
    "code": "missing_param",
    "message": "Missing required param to subscription.",
    "param": "plan",
    "status": 400,
    "type": "client_error"
  }
}

顧客IDとプランIDを指定して、定期課金を開始します。

前払い式のため、定期課金作成時に最初の課金が実行されます。但し以下の場合には作成時の課金はされません。

引数


customer String 必須

顧客ID

定期課金はデフォルトカードに請求が行われますので、デフォルトカードが存在しない顧客を指定した場合はエラーとなります。


plan String 必須

プランID


trial_end Integer or String

リクエスト時より未来のタイムスタンプ or 文字列 now が指定可能です。 これにより、プラン情報を上書きするトライアル設定が可能です。

未来のタイムスタンプを指定した場合、トライアル状態(status=trial)で定期課金が作成されます。トライアル期間終了時に支払い処理が行われ、 そこを基準としてプランに沿ったサイクルで定期課金が更新されます。

トライアル状態を利用することで、以下のことが可能です。

課金日(billing_day)が指定されているプランでも、トライアル終了時に支払い処理が行われますのでご注意ください。

また now を指定した場合、トライアル期間を終了し課金を即時実行できます。


prorate Boolean

デフォルトはfalse

trueの場合、日割り課金を設定します

定期課金を削除した際に、プランの金額を日割り計算して顧客へ返金処理を行います。

またプランに課金日(billing_day)が指定されている場合、trueであれば作成日から課金日までの日割り分が課金されますが、falseであれば最初の支払いは作成時ではなく課金日に行われます。


metadata Object

キーバリューの任意データ

レスポンス

作成されたsubscriptionオブジェクト

定期課金情報を取得

GET https://api.pay.jp/v1/subscriptions/:id

curl https://api.pay.jp/v1/subscriptions/sub_567a1e44562932ec1a7682d746e0 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Subscription::retrieve("sub_567a1e44562932ec1a7682d746e0");
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.retrieve('sub_567a1e44562932ec1a7682d746e0');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");

レスポンス

{
  "canceled_at": null,
  "created": 1433127983,
  "current_period_end": 1435732422,
  "current_period_start": 1433140422,
  "customer": "cus_4df4b5ed720933f4fb9e28857517",
  "id": "sub_567a1e44562932ec1a7682d746e0",
  "livemode": false,
  "metadata": null,
  "next_cycle_plan": null,
  "object": "subscription",
  "paused_at": null,
  "plan": {
    "amount": 1000,
    "billing_day": null,
    "created": 1432965397,
    "currency": "jpy",
    "id": "pln_9589006d14aad86aafeceac06b60",
    "livemode": false,
    "metadata": {},
    "interval": "month",
    "name": "test plan",
    "object": "plan",
    "trial_days": 0
  },
  "resumed_at": null,
  "start": 1433140422,
  "status": "active",
  "trial_end": null,
  "trial_start": null,
  "prorate": false
}

エラーレスポンス

{
  "error": {
    "message": "There is no subscription with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

指定されたIDの定期課金情報を取得します。

引数

なし

レスポンス

指定されたidのsubscriptionオブジェクト

定期課金を更新

POST https://api.pay.jp/v1/subscriptions/:id

curl https://api.pay.jp/v1/subscriptions/sub_567a1e44562932ec1a7682d746e0 \
-u sk_test_c62fade9d045b54cd76d7036: \
-d trial_end=1473911903
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = payjp.Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.trial_end = 1473911903
subscription.save()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = Payjp::Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.trial_end = 1473911903
subscription.save
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$su = \Payjp\Subscription::retrieve("sub_567a1e44562932ec1a7682d746e0");
$su->trial_end = 1473911903;
$su->save();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.update('sub_567a1e44562932ec1a7682d746e0', {
  trial_end: 1473911903
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription su = Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");
Map<String, Object> updateParams = new HashMap<String, Object>();
updateParams.put("trial_end", 1473911903);
su.update(updateParams);

レスポンス

{
  "canceled_at": null,
  "created": 1433127983,
  "current_period_end": 1435732422,
  "current_period_start": 1433140422,
  "customer": "cus_4df4b5ed720933f4fb9e28857517",
  "id": "sub_567a1e44562932ec1a7682d746e0",
  "livemode": false,
  "metadata": null,
  "next_cycle_plan": null,
  "object": "subscription",
  "paused_at": null,
  "plan": {
    "amount": 500,
    "billing_day": null,
    "created": 1433127983,
    "currency": "jpy",
    "id": "pln_68e6a67f582462c223ca693bc549",
    "livemode": false,
    "metadata": {},
    "interval": "week",
    "name": "weekly_plan",
    "object": "plan",
    "trial_days": 0
  },
  "resumed_at": null,
  "start": 1433140422,
  "status": "trial",
  "trial_end": 1473911903,
  "trial_start": 1433140922,
  "prorate": false
}

エラーレスポンス

{
  "error": {
    "message": "There is no plan with ID: dummy",
    "param": "plan",
    "status": 400,
    "type": "client_error"
  }
}

トライアル期間を新たに設定したり、プランの変更を行うことができます。

引数


trial_end Integer/String

リクエスト時より未来のタイムスタンプ or 文字列 now が指定可能です。

これにより、プラン情報を上書きするトライアル設定が可能です。

未来のタイムスタンプを指定した場合、トライアル期間終了時に支払い処理が行われ、 そこを基準としてプランに沿った周期で定期課金が作成されます。 トライアル期間を利用することで、定期課金の開始日を任意の日にずらせます。

課金日(billing_day)が指定されているプランでも、トライアル終了時に支払い処理が行われますのでご注意ください。

課金日(billing_day)が指定されていて、かつ日割り課金(prorate)が無効の場合、トライアル期間は次の課金日の日本時間午前9:00に自動調整されます。

また now を指定した場合、トライアル期間を終了し課金を即時実行できます。


plan String

新しいプランのID

プランを変更するとその時点で新しいプランでの課金が実行されます。 プランに設定されているトライアル期間は無視されるのでご注意ください。 即時課金を実行したくない場合はtrial_endに未来のタイムスタンプを設定ください。


prorate Boolean

trueの場合、日割り課金を設定します

この引数は plan と合わせて更新する場合のみ設定可能です。

例えばプランに課金日(billing_day)が指定されている場合、更新日から課金日までの日割り分を課金処理します。


next_cycle_plan String

プランIDを指定することで、次回サイクル更新時に指定のプランへと自動的に切り替えを行い課金を試みます。

値を指定せず(空文字列)更新した場合、設定は解除されます。

課金に失敗した場合、定期課金はプランの切り替えは行われた状態で停止します。

指定したプランの課金日(billing_day)と定期課金の日割り設定(prorate)の値によっては、課金が試行されない場合もあります。

next_cycle_plan.billing_day subscription.prorate 課金
なし true/false 全額
subscription.current_period_endの日と同じ false 全額
subscription.plan.billing_dayと同じ false 全額
上記以外の値 true 日割り
上記以外の値 false 無し

指定するプランについては、以下に注意ください。

なお current_period_end を過ぎてから実際にサイクル更新が行われる前に本パラメータを設定されますと、その更新時に反映される恐れがございます(更新タイミングとサービス運用中の状態の扱いについて)。 current_period_end 以前に設定することをお勧めします。


metadata Object

キーバリューの任意データ

レスポンス

更新されたsubscriptionオブジェクト

定期課金を停止

POST https://api.pay.jp/v1/subscriptions/:id/pause

curl https://api.pay.jp/v1/subscriptions/sub_f9fb5ef2507b46c00a1a84c47bed/pause \
-u sk_test_c62fade9d045b54cd76d7036: \
-XPOST
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = payjp.Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.pause()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = Payjp::Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.pause
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$su = \Payjp\Subscription::retrieve("sub_567a1e44562932ec1a7682d746e0");
$su->pause();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.pause('sub_567a1e44562932ec1a7682d746e0');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription su = Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");
su.pause();

レスポンス

{
  "canceled_at": null,
  "created": 1432965397,
  "current_period_end": 1435643801,
  "current_period_start": 1432965401,
  "customer": "cus_2498ea9cb54644f4516a9bf6dc78",
  "id": "sub_f9fb5ef2507b46c00a1a84c47bed",
  "livemode": false,
  "metadata": null,
  "next_cycle_plan": null,
  "object": "subscription",
  "paused_at": 1433141463,
  "plan": {
    "amount": 1000,
    "billing_day": null,
    "created": 1432965397,
    "currency": "jpy",
    "id": "pln_acfbc08ae710da03ac2a3fcb2334",
    "livemode": false,
    "metadata": {},
    "interval": "month",
    "name": "test plan",
    "object": "plan",
    "trial_days": 0
  },
  "resumed_at": null,
  "start": 1432965401,
  "status": "paused",
  "trial_end": null,
  "trial_start": null,
  "prorate": false
}

エラーレスポンス

{
  "error": {
    "message": "Subscription `sub_f9fb5ef2507b46c00a1a84c47bed` already has been paused",
    "status": 400,
    "type": "client_error"
  }
}

引き落としの失敗やカードが不正である、また定期課金を停止したい場合はこのリクエストで定期購入を停止させます。

定期課金を停止させると、再開されるまで引き落とし処理は一切行われません。

引数

なし

レスポンス

停止(status=paused)されたsubscriptionオブジェクト

定期課金を再開

POST https://api.pay.jp/v1/subscriptions/:id/resume

curl https://api.pay.jp/v1/subscriptions/sub_f9fb5ef2507b46c00a1a84c47bed/resume \
-u sk_test_c62fade9d045b54cd76d7036: \
-XPOST
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = payjp.Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.resume()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = Payjp::Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.resume
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$su = \Payjp\Subscription::retrieve("sub_567a1e44562932ec1a7682d746e0");
$su->resume();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.resume('sub_567a1e44562932ec1a7682d746e0', {prorate = true});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription su = Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");
su.resume();

レスポンス

{
  "canceled_at": null,
  "created": 1432965397,
  "current_period_end": 1435733621,
  "current_period_start": 1433141621,
  "customer": "cus_2498ea9cb54644f4516a9bf6dc78",
  "id": "sub_f9fb5ef2507b46c00a1a84c47bed",
  "livemode": false,
  "metadata": null,
  "next_cycle_plan": null,
  "object": "subscription",
  "paused_at": null,
  "plan": {
    "amount": 1000,
    "billing_day": null,
    "created": 1432965397,
    "currency": "jpy",
    "id": "pln_acfbc08ae710da03ac2a3fcb2334",
    "livemode": false,
    "metadata": {},
    "interval": "month",
    "name": "test plan",
    "object": "plan",
    "trial_days": 0
  },
  "resumed_at": 1433141621,
  "start": 1433141621,
  "status": "active",
  "trial_end": null,
  "trial_start": null,
  "prorate": false
}

エラーレスポンス

{
  "error": {
    "message": "Subscription `sub_f9fb5ef2507b46c00a1a84c47bed` already has been worked.",
    "status": 400,
    "type": "client_error"
  }
}

停止もしくはキャンセル状態(status=canceled or paused)の定期課金を再開させます。

トライアル期間中であればトライアル状態(status=trial)で再開します。

再開時の current_period_end が過去の日時の場合、トライアル期間内でなければ支払いが行われ、その時点が周期の開始として設定されます。 支払いの失敗により停止していた場合などは、 current_period_end は支払い失敗時の値になるため、必ず過去の日時がセットされます。

再開時の支払いに失敗すると、定期課金は再開されません。 この場合は、有効なカードを顧客のデフォルトカードにセットしてから、再度定期課金の再開を行ってください。

引数


trial_end Integer/String

リクエスト時より未来のタイムスタンプ or 文字列 now が指定可能です。

未来のタイムスタンプを指定した場合、トライアル状態(status=trial)で定期課金が再開されます。

課金日(billing_day)が指定されているプランでも、トライアル終了時に支払い処理が行われますのでご注意ください。

また課金日(billing_day)が指定されていて、かつ日割り課金(prorate)が無効の場合、トライアル期間は次の課金日の日本時間午前9:00に自動調整されます。

now を指定した場合、定期課金がトライアル期間中であれば、トライアル期間を終了して課金を即時実行できます。 定期課金がトライアル期間中でない場合は、この指定は無視されます。

この引数を指定した場合、プランのトライアル日数(trial_days)は無視されます。


prorate Boolean

trueの場合、日割り課金を設定します

レスポンス

再開されたsubscriptionオブジェクト

定期課金をキャンセル

POST https://api.pay.jp/v1/subscriptions/:id/cancel

curl https://api.pay.jp/v1/subscriptions/sub_19f6a2123363b514a743d1334109/cancel \
-u sk_test_c62fade9d045b54cd76d7036: \
-XPOST
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = payjp.Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.cancel()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = Payjp::Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.cancel
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$su = \Payjp\Subscription::retrieve("sub_567a1e44562932ec1a7682d746e0");
$su->cancel();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.cancel('sub_567a1e44562932ec1a7682d746e0');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription su = Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");
su.cancel();

レスポンス

{
  "canceled_at": 1433141780,
  "created": 1432965397,
  "current_period_end": 1435643801,
  "current_period_start": 1432965401,
  "customer": "cus_d43eb7c419c0da28ca0fd414108e",
  "id": "sub_19f6a2123363b514a743d1334109",
  "livemode": false,
  "metadata": null,
  "next_cycle_plan": null,
  "object": "subscription",
  "paused_at": null,
  "plan": {
    "amount": 1000,
    "billing_day": null,
    "created": 1432965397,
    "currency": "jpy",
    "id": "pln_01b0370fb0918777b952257302d5",
    "livemode": false,
    "metadata": {},
    "interval": "month",
    "name": "test plan",
    "object": "plan",
    "trial_days": 0
  },
  "resumed_at": null,
  "start": 1432965401,
  "status": "canceled",
  "trial_end": null,
  "trial_start": null,
  "prorate": false
}

エラーレスポンス

{
  "error": {
    "message": "Subscription `sub_19f6a2123363b514a743d1334109` already has been canceled",
    "status": 400,
    "type": "client_error"
  }
}

定期課金をキャンセルし、現在の周期の終了日をもって定期課金を終了させます。

終了日以前であれば、定期課金の再開リクエスト(/resume)を行うことで、キャンセルを取り消すことができます。 終了日をむかえた定期課金は自動的に削除されますのでご注意ください。

引数

なし

レスポンス

キャンセル(status=canceled)されたsubscriptionオブジェクト

定期課金を削除

DELETE https://api.pay.jp/v1/subscriptions/:id

curl https://api.pay.jp/v1/subscriptions/sub_19f6a2123363b514a743d1334109 \
-u sk_test_c62fade9d045b54cd76d7036: \
-XDELETE
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = payjp.Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.delete()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
subscription = Payjp::Subscription.retrieve('sub_567a1e44562932ec1a7682d746e0')
subscription.delete
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$su = \Payjp\Subscription::retrieve("sub_567a1e44562932ec1a7682d746e0");
$su->delete();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.delete('sub_567a1e44562932ec1a7682d746e0', {prorate: true});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription su = Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");
su.delete();

レスポンス

{
  "deleted": true,
  "id": "sub_19f6a2123363b514a743d1334109",
  "livemode": false
}

エラーレスポンス

{
  "error": {
    "message": "There is no subscription with ID: sub_19f6a2123363b514a743d1334109",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

定期課金をすぐに削除します。 次回以降の課金は行われず、一度削除した定期課金は再び戻すことができません。

引数


prorate Boolean

日割り設定

trueの場合、削除時から現在の周期の終了日までの日割り分を算出し、返金処理を行います。

レスポンス


deleted Boolean

trueが入ります


id String

削除した定期課金ID


livemode Boolean

本番環境かどうか

定期課金のリストを取得

GET https://api.pay.jp/v1/subscriptions

curl https://api.pay.jp/v1/subscriptions?limit=1 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Subscription.all(limit=1)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Subscription.all(limit: 1)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Subscription::all(array("limit" => 1));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.list('sub_567a1e44562932ec1a7682d746e0', {
  limit: 1
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> listParams = new HashMap<String, Object>();
listParams.put("limit", 1);
Subscription.all(listParams);

レスポンス

{
  "count": 1,
  "data": [
    {
      "canceled_at": null,
      "created": 1432965397,
      "current_period_end": 1435643801,
      "current_period_start": 1432965401,
      "customer": "cus_ca2676897435d6476c4f6205a6f5",
      "id": "sub_80ac5ef1c0073a3e443a7d7deb93",
      "livemode": false,
      "metadata": null,
      "next_cycle_plan": null,
      "object": "subscription",
      "paused_at": null,
      "plan": {
        "amount": 1000,
        "billing_day": null,
        "created": 1432965397,
        "currency": "jpy",
        "id": "pln_9589006d14aad86aafeceac06b60",
        "livemode": false,
        "metadata": {},
        "interval": "month",
        "name": "test plan",
        "object": "plan",
        "trial_days": 0
      },
      "resumed_at": null,
      "start": 1432965401,
      "status": "active",
      "trial_end": null,
      "trial_start": null,
      "prorate": false
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/subscriptions"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to subscription.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

生成した定期課金のリストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得


plan String

絞り込みたいプランID


customer String

絞り込みたい顧客ID


status String

定期課金ステータス。

active, trial, canceled または paused のみ指定可能。

レスポンス

subscriptionオブジェクトlistオブジェクト

リストは、直近で生成された順番に取得されます。

Token (トークン)

カード情報を代替するトークンオブジェクトです。

トークンは、カード番号やCVCなどのセキュアなデータを隠しつつも、カードと同じように扱うことができます。

顧客にカードを登録するときや、支払い処理を行うときにカード代わりとして使用します。

一度使用したトークンは再び使用することはできませんが、 顧客にカードを登録すれば、顧客IDを支払い手段として用いることで、何度でも同じカードで支払い処理ができるようになります。

tokenオブジェクト

tokenオブジェクト

{
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1442290383,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_e3ccd4e0959f45e7c75bacc4be90",
    "livemode": false,
    "metadata": {},
    "last4": "4242",
    "name": null,
    "object": "card"
  },
  "created": 1442290383,
  "id": "tok_5ca06b51685e001723a2c3b4aeb4",
  "livemode": false,
  "object": "token",
  "used": false
}

プロパティ


object String

“token"の固定文字列


id String

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


livemode Boolean

本番環境かどうか


created Integer

このトークン作成時のUTCタイムスタンプ


used Boolean

このトークンが使用済みかどうか


card Object

クレジットカードの情報を表すcardオブジェクト

トークンを作成

POST https://api.pay.jp/v1/tokens

curl https://api.pay.jp/v1/tokens \
-u sk_test_c62fade9d045b54cd76d7036: \
-H "X-Payjp-Direct-Token-Generate: true" \
-d "card[number]=4242424242424242" \
-d "card[cvc]=123" \
-d "card[exp_month]=02" \
-d "card[exp_year]=2024"
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Token.create(
    card={
        'number' : '4242424242424242',
        'cvc' : '123',
        'exp_month' : '2',
        'exp_year' : '2024'
    },
    headers={'X-Payjp-Direct-Token-Generate': 'true'}
)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Token.create({
  :card => {
    :number => '4242424242424242',
    :cvc => '123',
    :exp_month => '2',
    :exp_year => '2024'
  }},
  {
    'X-Payjp-Direct-Token-Generate': 'true'
  } 
)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$params = [
    'card' => [
        "number" => "4242424242424242",
        "exp_month" => "12",
        "exp_year" => "2024",
    ]
];
\Payjp\Token::create($params, $options = ['payjp_direct_token_generate' => 'true']);
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.tokens.create({
  card: {
    number: 4242424242424242,
    cvc: 123,
    exp_month: 2,
    exp_year: 2024
  },
}, {
  'X-Payjp-Direct-Token-Generate': 'true'
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> tokenParams = new HashMap<String, Object>();
Map<String, Object> cardParams = new HashMap<String, Object>();
Map<String, String> additionalHeaders = new LinkedHashMap<String, String>();
cardParams.put("number", "4242424242424242");
cardParams.put("cvc", "123");
cardParams.put("exp_month", "2");
cardParams.put("exp_year", "2024");
additionalHeaders.put("X-Payjp-Direct-Token-Generate", "true");
RequestOptions options = RequestOptions.getDefault()
        .toBuilder()
        .setAdditionalHeaders(additionalHeaders)
        .build();
tokenParams.put("card", cardParams);
Token.create(tokenParams, options);

レスポンス

{
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1442290383,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_e3ccd4e0959f45e7c75bacc4be90",
    "livemode": false,
    "metadata": {},
    "last4": "4242",
    "name": null,
    "object": "card"
  },
  "created": 1442290383,
  "id": "tok_5ca06b51685e001723a2c3b4aeb4",
  "livemode": false,
  "object": "token",
  "used": false
}

エラーレスポンス

{
  "error": {
    "code": "missing_param",
    "message": "Missing required param to token.",
    "param": "card[exp_year]",
    "status": 400,
    "type": "client_error"
  }
}

カード情報を指定して、トークンを生成します。生成したトークンは二度以上使用することができません。

本APIはシークレットキーを使ってサーバーサイドからカード情報をリクエストすることでトークンを取得するものです。通常はカード情報非通過対応が必要なためチェックアウトやpayjp.js を利用して、ブラウザ経由でパブリックキーを使ってカード情報を指定して生成する必要があります。

2018年6月1日以降に作成したアカウントでは後述するテスト目的のトークン以外は取得できません。 2018年7月中に全てのアカウントに対して同様の制限が適用される予定です。 詳しくは カード情報非通過化対応のお願い をご覧ください。

チェックアウトやpayjp.jsを使ったトークン化の実装方法については チュートリアル - カード情報のトークン化 をご覧ください。

テスト目的のトークン作成

テスト等の目的でトークンの作成処理をサーバーサイドで完結させたい場合、HTTPヘッダーに X-Payjp-Direct-Token-Generate: true を指定して本APIをリクエストすることで、カード情報を直接指定してトークンを作成することができます。この機能はテストモードでのみ利用可能です。

引数


card[number] String 必須

カード番号


card[exp_month] String 必須

有効期限月


card[exp_year] String 必須

有効期限年


card[cvc] String

3~4桁のCVCコード


card[address_state] String

都道府県


card[address_city] String

市区町村


card[address_line1] String

番地など


card[address_line2] String

建物名など


card[address_zip] String

郵便番号


card[country] String

2桁のISOコード(e.g. JP)


card[name] String

カード保有者名(e.g. "YUI ARAGAKI”)

トークン情報を取得

GET https://api.pay.jp/v1/tokens/:id

curl https://api.pay.jp/v1/tokens/tok_5ca06b51685e001723a2c3b4aeb4 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Token.retrieve('tok_5ca06b51685e001723a2c3b4aeb4')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Token.retrieve('tok_5ca06b51685e001723a2c3b4aeb4')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Token::retrieve("tok_5ca06b51685e001723a2c3b4aeb4");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.tokens.retrieve('tok_5ca06b51685e001723a2c3b4aeb4');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Token.retrieve("tok_5ca06b51685e001723a2c3b4aeb4");

レスポンス

{
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": null,
    "created": 1442290383,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 2,
    "exp_year": 2024,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_e3ccd4e0959f45e7c75bacc4be90",
    "livemode": false,
    "metadata": {},
    "last4": "4242",
    "name": null,
    "object": "card"
  },
  "created": 1442290383,
  "id": "tok_5ca06b51685e001723a2c3b4aeb4",
  "livemode": false,
  "object": "token",
  "used": true
}

エラーレスポンス

{
  "error": {
    "message": "There is no token with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

特定のトークン情報を取得します。

引数

なし

レスポンス

指定したidのtokenオブジェクト

Transfer (入金)

入金は、各締め日ごとに売上と返金を元にデータが生成されます。

transferオブジェクト

transferオブジェクト

{
  "amount": 1000,
  "carried_balance": null,
  "charges": {
    "count": 1,
    "data": [
      {
        "amount": 1000,
        "amount_refunded": 0,
        "captured": true,
        "captured_at": 1441706750,
        "card": {
          "address_city": null,
          "address_line1": null,
          "address_line2": null,
          "address_state": null,
          "address_zip": null,
          "address_zip_check": "unchecked",
          "brand": "Visa",
          "country": null,
          "created": 1441706750,
          "customer": null,
          "cvc_check": "unchecked",
          "exp_month": 5,
          "exp_year": 2018,
          "fingerprint": "e1d8225886e3a7211127df751c86787f",
          "id": "car_93e59e9a9714134ef639865e2b9e",
          "last4": "4242",
          "name": null,
          "object": "card"
        },
        "created": 1441706750,
        "currency": "jpy",
        "customer": "cus_b92b879e60f62b532d6756ae12af",
        "description": null,
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "id": "ch_60baaf2dc8f3e35684ebe2031a6e0",
        "object": "charge",
        "paid": true,
        "refund_reason": null,
        "refunded": false,
        "subscription": null
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/charges"
  },
  "created": 1438354800,
  "currency": "jpy",
  "description": null,
  "id": "tr_8f0c0fe2c9f8a47f9d18f03959ba1",
  "livemode": false,
  "object": "transfer",
  "scheduled_date": "2015-09-16",
  "status": "pending",
  "summary": {
    "charge_count": 1,
    "charge_fee": 0,
    "charge_gross": 1000,
    "net": 1000,
    "refund_amount": 0,
    "refund_count": 0
  },
  "term_end": 1439650800,
  "term_start": 1438354800,
  "transfer_amount": null,
  "transfer_date": null
}

プロパティ


object String

“transfer"の固定文字列


id String

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


livemode Boolean

本番環境かどうか


created Integer

この入金作成時のUTCタイムスタンプ


amount Integer

入金予定額


currency String

3文字のISOコード(現状 "jpy” のみサポート)


status String

この入金の処理状態を表す下記のいずれかの値

pending 振込金額(¥10,000)以上で入金日前の状態
paid 入金完了後の状態
failed 口座間違い等で入金に失敗した状態
stop PAYJPの判断で加盟店様側の入金を控えさせていただいている状態
carried_over 合計金額が¥10,000に満たない場合は、次回入金に繰り越しが行われる
recombination 入金に失敗し、次回入金時に組み戻し手数料が発生する状態

recombination は2020年2月29日入金予定分より適用される値です。詳しくはお知らせをご参照ください。


charges Object

この入金に含まれる支払いのlistオブジェクト


scheduled_date Date

入金予定日


summary Object

この入金に関する集計情報

キー 値の型 値の説明
charge_count Integer 支払い総回数
charge_fee Integer 支払い手数料
charge_gross Integer 総売上
net Integer 差引額
refund_amount Integer 返金総額
refund_count Integer 返金総数

description String

概要


term_start Integer

集計期間開始時のUTCタイムスタンプ


term_end Integer

集計期間終了時のUTCタイムスタンプ


transfer_amount Integer

入金額


transfer_date Date

入金日


carried_balance Integer

繰越金

入金情報を取得

GET https://api.pay.jp/v1/transfers/:id

curl https://api.pay.jp/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Transfer.retrieve('tr_8f0c0fe2c9f8a47f9d18f03959ba1')

require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Transfer.retrieve('tr_8f0c0fe2c9f8a47f9d18f03959ba1')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Transfer::retrieve("tr_8f0c0fe2c9f8a47f9d18f03959ba1");
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.transfers.retrieve('tr_8f0c0fe2c9f8a47f9d18f03959ba1');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Transfer.retrieve("tr_8f0c0fe2c9f8a47f9d18f03959ba1");

レスポンス

{
  "amount": 1000,
  "carried_balance": null,
  "charges": {
    "count": 1,
    "data": [
      {
        "amount": 1000,
        "amount_refunded": 0,
        "captured": true,
        "captured_at": 1441706750,
        "card": {
          "address_city": null,
          "address_line1": null,
          "address_line2": null,
          "address_state": null,
          "address_zip": null,
          "address_zip_check": "unchecked",
          "brand": "Visa",
          "country": null,
          "created": 1441706750,
          "customer": null,
          "cvc_check": "unchecked",
          "exp_month": 5,
          "exp_year": 2018,
          "fingerprint": "e1d8225886e3a7211127df751c86787f",
          "id": "car_93e59e9a9714134ef639865e2b9e",
          "last4": "4242",
          "name": null,
          "object": "card"
        },
        "created": 1441706750,
        "currency": "jpy",
        "customer": "cus_b92b879e60f62b532d6756ae12af",
        "description": null,
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "id": "ch_60baaf2dc8f3e35684ebe2031a6e0",
        "object": "charge",
        "paid": true,
        "refund_reason": null,
        "refunded": false,
        "subscription": null
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/charges"
  },
  "created": 1438354800,
  "currency": "jpy",
  "description": null,
  "id": "tr_8f0c0fe2c9f8a47f9d18f03959ba1",
  "livemode": false,
  "object": "transfer",
  "scheduled_date": "2015-09-16",
  "status": "pending",
  "summary": {
    "charge_count": 1,
    "charge_fee": 0,
    "charge_gross": 1000,
    "net": 1000,
    "refund_amount": 0,
    "refund_count": 0
  },
  "term_end": 1439650800,
  "term_start": 1438354800,
  "transfer_amount": null,
  "transfer_date": null
}

エラーレスポンス

{
  "error": {
    "message": "There is no transfer with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

特定の入金情報を取得します。

引数

なし

レスポンス

指定したidのtransferオブジェクト

入金リストを取得

GET https://api.pay.jp/v1/transfers

curl https://api.pay.jp/v1/transfers?limit=3 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Transfer.all()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Transfer.all
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Transfer::all();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.transfers.list({limit: 1});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Transfer.all();

レスポンス

{
  "count": 1,
  "data": [
    {
      "amount": 1000,
      "carried_balance": null,
      "charges": {
        "count": 1,
        "data": [
          {
            "amount": 1000,
            "amount_refunded": 0,
            "captured": true,
            "captured_at": 1441706750,
            "card": {
              "address_city": null,
              "address_line1": null,
              "address_line2": null,
              "address_state": null,
              "address_zip": null,
              "address_zip_check": "unchecked",
              "brand": "Visa",
              "country": null,
              "created": 1441706750,
              "customer": null,
              "cvc_check": "unchecked",
              "exp_month": 5,
              "exp_year": 2018,
              "fingerprint": "e1d8225886e3a7211127df751c86787f",
              "id": "car_93e59e9a9714134ef639865e2b9e",
              "last4": "4242",
              "name": null,
              "object": "card"
            },
            "created": 1441706750,
            "currency": "jpy",
            "customer": "cus_b92b879e60f62b532d6756ae12af",
            "description": null,
            "expired_at": null,
            "failure_code": null,
            "failure_message": null,
            "id": "ch_60baaf2dc8f3e35684ebe2031a6e0",
            "object": "charge",
            "paid": true,
            "refund_reason": null,
            "refunded": false,
            "subscription": null
          }
        ],
        "has_more": false,
        "object": "list",
        "url": "/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/charges"
      },
      "created": 1438354800,
      "currency": "jpy",
      "description": null,
      "id": "tr_8f0c0fe2c9f8a47f9d18f03959ba1",
      "livemode": false,
      "object": "transfer",
      "scheduled_date": "2015-09-16",
      "status": "pending",
      "summary": {
        "charge_count": 1,
        "charge_fee": 0,
        "charge_gross": 1000,
        "net": 1000,
        "refund_amount": 0,
        "refund_count": 0
      },
      "term_end": 1439650800,
      "term_start": 1438354800,
      "transfer_amount": null,
      "transfer_date": null
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/transfers"
}

エラーレスポンス

{
  "error": {
    "message": "Invalid query string.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

入金リストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得


status String

transferオブジェクトのステータス

pending, paid, carried_over, failed, stop, recombination

レスポンス

transferオブジェクトlistオブジェクト

入金の内訳を取得

GET https://api.pay.jp/v1/transfers/:id/charges

curl https://api.pay.jp/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/charges \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
transfer = payjp.Transfer.retrieve('tr_8f0c0fe2c9f8a47f9d18f03959ba1')
transfer.charges.all(limit=3)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
transfer = Payjp::Transfer.retrieve('tr_8f0c0fe2c9f8a47f9d18f03959ba1')
transfer.charges.all(limit: 3)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Transfer::retrieve("tr_8f0c0fe2c9f8a47f9d18f03959ba1")->charges->all(array("limit"=>3));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.transfers.charges('tr_8f0c0fe2c9f8a47f9d18f03959ba1', {
  limit: 3
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Transfer tr = Transfer.retrieve("tr_8f0c0fe2c9f8a47f9d18f03959ba1");
Map<String, Object> listParams = new HashMap<String, Object>();
listParams.put("limit", 3);
tr.getCharges.all(listParams);

レスポンス

{
  "count": 1,
  "data": [
    {
      "amount": 1000,
      "amount_refunded": 0,
      "captured": true,
      "captured_at": 1441706750,
      "card": {
        "address_city": null,
        "address_line1": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": "unchecked",
        "brand": "Visa",
        "country": null,
        "created": 1441706750,
        "customer": "cus_b92b879e60f62b532d6756ae12af",
        "cvc_check": "unchecked",
        "exp_month": 5,
        "exp_year": 2018,
        "fingerprint": "e1d8225886e3a7211127df751c86787f",
        "id": "car_93e59e9a9714134ef639865e2b9e",
        "last4": "4242",
        "name": null,
        "object": "card"
      },
      "created": 1441706750,
      "currency": "jpy",
      "customer": "cus_b92b879e60f62b532d6756ae12af",
      "description": null,
      "expired_at": null,
      "failure_code": null,
      "failure_message": null,
      "id": "ch_60baaf2dc8f3e35684ebe2031a6e0",
      "livemode": false,
      "object": "charge",
      "paid": true,
      "refund_reason": null,
      "refunded": false,
      "subscription": null
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/charges"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to transfer.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

入金内訳の支払いリストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得


customer String

絞り込みたい顧客ID

レスポンス

chargeオブジェクトlistオブジェクト

Event (イベント)

作成、更新、削除などのイベントを表示するオブジェクトです。イベント情報は、Webhookで任意のURLへ通知設定をすることができます。

eventオブジェクト

eventオブジェクト

{
  "created": 1442288882,
  "data": {
    "cards": {
      "count": 0,
      "data": [],
      "has_more": false,
      "object": "list",
      "url": "/v1/customers/cus_a16c7b4df01168eb82557fe93de4/cards"
    },
    "created": 1441936720,
    "default_card": null,
    "description": "updated\n",
    "email": null,
    "id": "cus_a16c7b4df01168eb82557fe93de4",
    "livemode": false,
    "object": "customer",
    "subscriptions": {
      "count": 0,
      "data": [],
      "has_more": false,
      "object": "list",
      "url": "/v1/customers/cus_a16c7b4df01168eb82557fe93de4/subscriptions"
    }
  },
  "id": "evnt_54db4d63c7886256acdbc784ccf",
  "livemode": false,
  "object": "event",
  "pending_webhooks": 1,
  "type": "customer.updated"
}

プロパティ


object String

“event"の固定文字列


id String

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


livemode Boolean

本番環境かどうか


created Integer

このイベント作成時のUTCタイムスタンプ


type String

このイベントのタイプ。値の種類についてはこちら


pending_webhooks Integer

設定されたURLへの通知が完了していない(2xxのレスポンスが得られていない)webhookの数


data Object

このイベントに関連したリソースオブジェクト

イベント情報を取得

GET https://api.pay.jp/v1/events/:id

curl https://api.pay.jp/v1/events/evnt_54db4d63c7886256acdbc784ccf \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Event.retrieve('evnt_54db4d63c7886256acdbc784ccf')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Event.retrieve('evnt_54db4d63c7886256acdbc784ccf')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Event::retrieve("evnt_54db4d63c7886256acdbc784ccf");
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Event.retrieve("evnt_54db4d63c7886256acdbc784ccf");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.events.retrieve("evnt_54db4d63c7886256acdbc784ccf");

レスポンス

{
  "created": 1442288882,
  "data": {
    "cards": {
      "count": 0,
      "data": [],
      "has_more": false,
      "object": "list",
      "url": "/v1/customers/cus_a16c7b4df01168eb82557fe93de4/cards"
    },
    "created": 1441936720,
    "default_card": null,
    "description": "updated\n",
    "email": null,
    "id": "cus_a16c7b4df01168eb82557fe93de4",
    "livemode": false,
    "object": "customer",
    "subscriptions": {
      "count": 0,
      "data": [],
      "has_more": false,
      "object": "list",
      "url": "/v1/customers/cus_a16c7b4df01168eb82557fe93de4/subscriptions"
    }
  },
  "id": "evnt_54db4d63c7886256acdbc784ccf",
  "livemode": false,
  "object": "event",
  "pending_webhooks": 1,
  "type": "customer.updated"
}

エラーレスポンス

{
  "error": {
    "message": "There is no event with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

特定のイベント情報を取得します。

引数

なし

レスポンス

指定したidのeventオブジェクト

イベントリストを取得

GET https://api.pay.jp/v1/events

curl 'https://api.pay.jp/v1/events?limit=3&offset=10' \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Event.all(limit=3, offset=10)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Event.all(limit: 3, offset: 10)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Event::all(array("limit"=>3, "offset"=>10));
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> listParams = new HashMap<String, Object>();
listParams.put("limit", 3);
listParams.put("offset", 10);
Event.all(listParams);
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.events.list({limit: 1}})

レスポンス

{
  "count": 3,
  "data": [
    {
      "created": 1442298026,
      "data": {
        "amount": 5000,
        "amount_refunded": 5000,
        "captured": true,
        "captured_at": 1442212986,
        "card": {
          "address_city": null,
          "address_line1": null,
          "address_line2": null,
          "address_state": null,
          "address_zip": null,
          "address_zip_check": "unchecked",
          "brand": "Visa",
          "country": null,
          "created": 1442212986,
          "customer": null,
          "cvc_check": "passed",
          "exp_month": 1,
          "exp_year": 2016,
          "fingerprint": "e1d8225886e3a7211127df751c86787f",
          "id": "car_f0984a6f68a730b7e1814ceabfe1",
          "last4": "4242",
          "name": null,
          "object": "card"
        },
        "created": 1442212986,
        "currency": "jpy",
        "customer": null,
        "description": "hogehoe",
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "id": "ch_bcb7776459913c743c20e9f9351d4",
        "livemode": false,
        "object": "charge",
        "paid": true,
        "refund_reason": null,
        "refunded": true,
        "subscription": null
      },
      "id": "evnt_8064917698aa417a3c86d292266",
      "livemode": false,
      "object": "event",
      "pending_webhooks": 1,
      "type": "charge.updated"
    }
    {...},
    {...}
  ],
  "has_more": true,
  "object": "list",
  "url": "/v1/events"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to event.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

イベントリストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


resource_id String

取得するeventに紐づくAPIリソースのID (e.g. customer.id)


object String

取得するeventに紐づくAPIリソースのobject
値はリソース名(e.g. customer, charge)


type String

取得するeventのtype


since Integer

ここに指定したタイムスタンプ以降に作成されたデータを取得


until Integer

ここに指定したタイムスタンプ以前に作成されたデータを取得

レスポンス

eventオブジェクトlistオブジェクト

リストは、直近で生成された順番に取得されます。

Product (プロダクト)

各種SDKは順次対応予定です

支払いの雛形となるオブジェクトです。

支払いを作成する時に、金額と通貨の代わりにプロダクトを指定することができます。作成された支払いの金額、通貨、メタデータは元となったプロダクトのものが入ります。 個々のプロダクトには、それぞれユニークなPAYCode(QRコード)が発行されます。そのPAYCodeはお支払いアプリ「PAY ID」での支払いに使用することができます。PAY IDユーザーがPAY IDアプリでPAYCodeをスキャンすることにより、支払いAPIを使用せずに支払いオブジェクトが作成されます。

productオブジェクト

productオブジェクト

{
  "amount": 350,
  "capture": true,
  "created": 1498268809,
  "currency": "jpy",
  "id": "prd_24790edf42fb15c3eb72af2c7e6a",
  "invalid_after": null,
  "livemode": false,
  "metadata": {},
  "object": "product",
  "paycode_url": "https://qr.pay.jp/pc_d910596ff3baf3da8bbe430e47805.png"
}

プロパティ


object String

“product"の固定文字列


id String

一意なオブジェクトを示す文字列


livemode Boolean

本番環境かどうか


created Integer

このプロダクト作成時のUTCタイムスタンプ


amount Integer

プロダクト金額


currency String

3文字のISOコード(現状 "jpy” のみサポート)


capture Boolean

このプロダクトを購入時に通常、支払い処理を確定するかどうか (falseの場合、カードの認証と支払い額の確保のみ行う)


invalid_after Integer

このプロダクトの有効日時を示す、リクエスト時より未来のUTCタイムスタンプ


metadata[display_name] Object

PAY IDでの購入者に表示されるプロダクト名


metadata Object

キーバリューの任意データ


paycode_url String

このプロダクトのPAYCode(QRコード)画像が配置されてるURL

プロダクトを作成

POST https://api.pay.jp/v1/products

curl https://api.pay.jp/v1/products \
-u sk_test_c62fade9d045b54cd76d7036: \
-d amount=350 \
-d currency=jpy \
-d "metadata[display_name]=espresso"

レスポンス

{
  "amount": 350,
  "capture": true,
  "created": 1498268809,
  "currency": "jpy",
  "id": "prd_24790edf42fb15c3eb72af2c7e6a",
  "invalid_after": null,
  "livemode": false,
  "metadata": {
    "display_name": "espresso"
  },
  "object": "product",
  "paycode_url": "https://qr.pay.jp/pc_d910596ff3baf3da8bbe430e47805.png"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_currency",
    "message": "We currently support only jpy.",
    "param": "currency",
    "status": 400,
    "type": "client_error"
  }
}

金額や通貨などを指定してプロダクトを生成します。

有効期限(invalid_after)を指定することで、プロダクトの購入可能期限となる日時を付与することができます。 また、captureを指定することにより、支払い作成時に処理を確定するかどうかを設定できます。

metadatadisplay_nameというキーで値を指定することにより、PAY IDでの支払い時やPAY ID アプリの購入履歴などで購入者に表示されるプロダクト名を設定できます。

引数


amount Integer 必須

50~9,999,999の整数


currency String 必須

3文字のISOコード(現状 “jpy” のみサポート)


invalid_after Integer

このプロダクトの有効日時を示す、リクエスト時より未来のUTCタイムスタンプ


capture Boolean

このプロダクトと紐づいた支払いを作成した時に、支払い処理を確定するかどうか (falseの場合、カードの認証と支払い額の確保のみ行う)


metadata[display_name] Object

PAY IDでの購入者に表示されるプロダクト名


metadata Object

キーバリューの任意データ

レスポンス

生成されたproductオブジェクト

プロダクト情報を取得

GET https://api.pay.jp/v1/products/:id

curl https://api.pay.jp/v1/products/prd_24790edf42fb15c3eb72af2c7e6a \
-u sk_test_c62fade9d045b54cd76d7036:

レスポンス

{
  "amount": 350,
  "capture": true,
  "created": 1498268809,
  "currency": "jpy",
  "id": "prd_24790edf42fb15c3eb72af2c7e6a",
  "invalid_after": null,
  "livemode": false,
  "metadata": {
    "display_name": "espresso"
  },
  "object": "product",
  "paycode_url": "https://qr.pay.jp/pc_d910596ff3baf3da8bbe430e47805.png"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_id",
    "message": "No such product: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

特定のプロダクト情報を取得します。

引数

なし

レスポンス

指定したidのproductオブジェクト

プロダクトを更新

POST https://api.pay.jp/v1/products/:id

curl https://api.pay.jp/v1/products/prd_24790edf42fb15c3eb72af2c7e6a \
-u sk_test_c62fade9d045b54cd76d7036: \
-d invalid_after=1510876800

レスポンス

{
  "amount": 350,
  "capture": true,
  "created": 1498287168,
  "currency": "jpy",
  "id": "prd_24790edf42fb15c3eb72af2c7e6a",
  "invalid_after": 1510876800,
  "livemode": false,
  "metadata": {
    "display_name": "espresso"
  },
  "object": "product",
  "paycode_url": "https://qr.pay.jp/pc_43317c7108a4d0593f3347cef9dec.png"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to product",
    "param": "nanako",
    "status": 400,
    "type": "client_error"
  }
}

プロダクト情報を更新します。

引数


invalid_after Integer

このプロダクトの有効日時を示す、リクエスト時より未来のUTCタイムスタンプ


metadata[display_name] Object

PAY IDでの購入者に表示されるプロダクト名


metadata Object

キーバリューの任意データ

レスポンス

更新されたproductオブジェクト

プロダクトを削除

DELETE https://api.pay.jp/v1/products/:id

curl https://api.pay.jp/v1/products/prd_24790edf42fb15c3eb72af2c7e6a \
-u sk_test_c62fade9d045b54cd76d7036: \
-XDELETE

レスポンス

{
  "deleted": true,
  "id": "prd_24790edf42fb15c3eb72af2c7e6a",
  "livemode": false
}

エラーレスポンス

{
  "error": {
    "code": "invalid_id",
    "message": "No such product: prd_24790edf42fb15c3eb72af2c7e6a",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

プロダクトを削除します。

引数

なし

レスポンス


deleted Boolean

trueが入ります


id String

削除したプロダクトID


livemode Boolean

本番環境かどうか

プロダクトリストを取得

GET https://api.pay.jp/v1/products

curl https://api.pay.jp/v1/products?limit=3 \
-u sk_test_c62fade9d045b54cd76d7036:

レスポンス

{
  "count": 3,
  "data": [
    {
      "amount": 350,
      "capture": true,
      "created": 1498268809,
      "currency": "jpy",
      "id": "prd_24790edf42fb15c3eb72af2c7e6a",
      "invalid_after": null,
      "livemode": false,
      "metadata": {
        "display_name": "espresso"
      },
      "object": "product",
      "paycode_url": "https://qr.pay.jp/pc_d910596ff3baf3da8bbe430e47805.png"
    },
    {...},
    {...}
  ],
  "has_more": true,
  "object": "list",
  "url": "/v1/products"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to product",
    "param": "nanako",
    "status": 400,
    "type": "client_error"
  }
}

生成したプロダクトのリストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)


offset Integer

基準点からのデータ取得を行う開始位置


since Integer

ここに指定したタイムスタンプ以降に作成されたデータを取得


until Integer

ここに指定したタイムスタンプ以前に作成されたデータを取得

レスポンス

productオブジェクトlistオブジェクト

リストは、直近で生成された順番に取得されます。

Account (アカウント)

あなたのアカウント情報です。

accountオブジェクト

accountオブジェクト

{
  "created": 1439706600,
  "email": "liveaccount@example.com",
  "id": "acct_8a27db83a7bf11a0c12b0c2833f",
  "merchant": {
    "bank_enabled": false,
    "brands_accepted": [
      "Visa",
      "MasterCard",
      "JCB",
      "American Express",
      "Diners Club",
      "Discover"
    ],
    "business_type": null,
    "charge_type": null,
    "country": "JP",
    "created": 1439706600,
    "currencies_supported": [
      "jpy"
    ],
    "default_currency": "jpy",
    "details_submitted": false,
    "id": "acct_mch_21a96cb898ceb6db0932983",
    "livemode_activated_at": null,
    "livemode_enabled": false,
    "object": "merchant",
    "product_name": null,
    "product_type": null,
    "site_published": null
  },
  "object": "account"
}

プロパティ


object String

“account"の固定文字列


id String

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


email String

メールアドレス


created Integer

このアカウント作成時のUTCタイムスタンプ


merchant Object

このアカウントに紐付くmerchantオブジェクト

merchantオブジェクト

merchantオブジェクト

{
  "bank_enabled": false,
  "brands_accepted": [
    "Visa",
    "MasterCard",
    "JCB",
    "American Express",
    "Diners Club",
    "Discover"
  ],
  "business_type": null,
  "charge_type": null,
  "country": "JP",
  "created": 1439706600,
  "currencies_supported": [
    "jpy"
  ],
  "default_currency": "jpy",
  "details_submitted": false,
  "id": "acct_mch_21a96cb898ceb6db0932983",
  "livemode_activated_at": null,
  "livemode_enabled": false,
  "object": "merchant",
  "product_name": null,
  "product_type": null,
  "site_published": null
}

プロパティ


object String

"merchant"の固定文字列


id String

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


bank_enabled Boolean

入金先銀行口座情報が設定済みかどうか


brands_accepted Array

本番環境で利用可能なカードブランドのリスト


currencies_supported Array

対応通貨のリスト


default_currency String

3文字のISOコード(現状 "jpy” のみサポート)


details_submitted Boolean

本番環境申請情報が提出済みかどうか


business_type String

業務形態


country String

所在国


charge_type Array

支払い方法種別のリスト


product_name String

販売商品名


product_type Array

販売商品の種類リスト


livemode_enabled Boolean

本番環境が有効かどうか


livemode_activated_at Integer

本番環境が許可された日時のUTCタイムスタンプ


site_published Boolean

申請対象のサイトがオープン済みかどうか


created Integer

登録日時

アカウント情報を取得

GET https://api.pay.jp/v1/accounts

curl https://api.pay.jp/v1/accounts \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Account.retrieve()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Account.retrieve

\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Account::retrieve();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.accounts.retrieve();
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Account.retrieve();

レスポンス

{
  "created": 1439706600,
  "email": "liveaccount@example.com",
  "id": "acct_8a27db83a7bf11a0c12b0c2833f",
  "merchant": {
    "bank_enabled": false,
    "brands_accepted": [
      "Visa",
      "MasterCard",
      "JCB",
      "American Express",
      "Diners Club",
      "Discover"
    ],
    "business_type": null,
    "charge_type": null,
    "country": "JP",
    "created": 1439706600,
    "currencies_supported": [
      "jpy"
    ],
    "default_currency": "jpy",
    "details_submitted": false,
    "id": "acct_mch_21a96cb898ceb6db0932983",
    "livemode_activated_at": null,
    "livemode_enabled": false,
    "object": "merchant",
    "product_name": null,
    "product_type": null,
    "site_published": null
  },
  "object": "account"
}

エラーレスポンス

{
  "error": {
    "message": "Invalid query string.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

あなたのアカウント情報を取得します。

引数

なし

レスポンス

accountオブジェクト

Platform API (β版)

このAPIは、 MarketPlace型アカウント または Payouts型アカウント で利用可能です。

プラットフォームサービスを提供したいプラットフォーマー向けのAPIで、売上をテナントに分配・入金する機能、テナントからプラットフォーム手数料を徴収する機能などが存在します。

APIの具体的な使い方についてはPAY.JP Platform チュートリアルを参考ください。

本APIは現在β提供中の機能となります
※ ご利用希望の方は利用の準備をごらんください

(旧プラットフォームのAPIはこちらです。旧プラットフォームは新規受付停止中ですので、本プラットフォーム機能をご利用下さい。)

Platform API共通項目

認証も含め、PAY.JP APIの共通項目に従います。

利用できないPAY.JP API

下記API は現在準備中です。

Platform Error

エラーハンドリング例

# レスポンス例を記載
{
  "error": {
    "code": "platform_fee_limit",
    "message": "...",
    "status": 400,
    "type": "client_error"
  }
}
// PAY.JP API のエラーハンドリング例と同じです
// PAY.JP API のエラーハンドリング例と同じです

基本的にPAY.JP API Errorに従いますが、Platform API でのみ下記が追加されます。

error[code] 詳細
invalid_character 不正な文字
invalid_url 不正なURL
invalid_format_string 不正な文字列形式
invalid_file 不正なファイル
invalid_file_id 不正なファイルIDがセットされている
invalid_business_type 不正な事業形態
invalid_numerical_value 不正な数値
invalid_gender 不正な性別
invalid_address_state 不正な都道府県
invalid_address_city 不正な市区町村
invalid_address_line 不正な番地等
invalid_phone 不正な電話番号
invalid_bank_code 不正な銀行コード
invalid_bank_branch_code 不正な銀行支店コード
invalid_bank_account_type 不正な口座種別
invalid_bank_account_holder_name 不正な口座名義
invalid_bank_account_number 不正な口座番号
invalid_param_length パラメーターの長さが不正
invalid_product_type 不正な商材種類
invalid_charge_type 不正な課金種類
invalid_key_type 不正なキータイプ
invalid_access_mode 不正なアクセスモード
invalid_timing 不正な更新タイミング
platform_fee_limit プラットフォーム利用料は支払い金額の95%以下の金額をセットしてください

Charge for Platform (支払い)

PAY.JP API の Charge でテナントの支払いを操作します。 Platform では、下記の点が通常の PAY.JP API と異なります。

  1. charge 作成時に tenant の指定が必要
  2. charge 作成時にプラットフォーマーの入金金額として platform_fee を指定可能
  3. chargeリスト取得時に tenant を指定可能(未指定の場合は全テナントを対象)
  4. chargeオブジェクトに専用プロパティが追加

charge 作成時の platform_fee について、通常、テナントの platform_fee_rate に基いてプラットフォーマーの入金金額が算出されますが、 platform_fee を指定した場合はそちらが優先されます。

例えば platform_fee_rate が 8(%) のテナントで platform_fee を 50 として charge を作成した場合、total_platform_fee は必ず 50 となります。

なお payjp_fee_included の値によって指定可能な範囲が異なります。 詳しくはcharge 作成の引数欄を確認ください。

Transfer for Platform (入金)

プラットフォーマーの入金情報については PAY.JP API の Transfer (入金) をご利用ください。

テナントの入金情報については TenantTransfer (テナント入金) をご利用ください。

Tenant (テナント)

テナントを管理するためのオブジェクトです。

テナントに紐つけた売上は料率を差し引いてそのテナントに登録してある銀行口座に入金されます。

tenantオブジェクト

tenantオブジェクト

{
  "created": 1433127983,
  "name": "test",
  "id": "test",
  "livemode": false,
  "metadata": null,
  "object": "tenant",
  "platform_fee_rate": "10.15",
  "payjp_fee_included": false,
  "minimum_transfer_amount": 1000,
  "bank_account_number": "0001000",
  "bank_branch_code": "000",
  "bank_code": "0000",
  "bank_account_holder_name": "ヤマダ タロウ",
  "bank_account_type": "普通",
  "bank_account_status": "pending"
}

プロパティ


id String

ten_で始まる自動生成された一意な文字列、または作成時に指定した任意の文字列


object String

“tenant"の固定文字列


livemode Boolean

本番環境かどうか


created Integer

定期課金作成時のUTCタイムスタンプ


platform_fee_rate String

テナントのプラットフォーム利用料率(%)。 小数点以下2桁までの数値の文字列型。


payjp_fee_included Boolean

テナントのプラットフォーム利用料にPAY.JP決済手数料を含めるかどうか。


minimum_transfer_amount Integer

最低入金額。デフォルトは1万円で下限は1000円。締め日にこの金額以上の売上が貯まっていると入金手数料250円を引いた金額が振り込まれる。


bank_code String

4桁の銀行コード


bank_branch_code String

3桁の支店コード


bank_account_type String

預金種別


bank_account_number String

口座番号


bank_account_holder_name String

口座名義


bank_account_status String

口座状態。pending:未確認, success:入金確認済み, failed:入金不可能


currencies_supported Array

対応通貨のリスト(文字列)


default_currency String

3文字のISOコード(現状 “jpy” のみサポート)


reviewed_brands Array

申請情報を提出済のブランドの各種情報

配列内は以下のキーバリューをもつオブジェクト

キー 値の型 値の説明
brand String ブランド名
status String 審査ステータス(passed: 通過, in_review: 審査中, declined: 否決)
available_date Integer 利用可能開始時刻のタイムスタンプ(status: 'passed'以外ではnull)

metadata Object

キーバリューの任意データ

テナントを作成

POST https://api.pay.jp/v1/tenants

curl https://api.pay.jp/v1/tenants \
-u sk_test_...: \
-d id=test \
-d name=test \
-d platform_fee_rate=10.15 \
-d minimum_transfer_amount=1000 \
-d bank_account_holder_name='ヤマダ タロウ' \
-d bank_code=0001 \
-d bank_branch_code=001 \
-d bank_account_type=普通 \
-d bank_account_number=0001000
# SDKは準備中です
# SDKは準備中です
\Payjp\Payjp::setApiKey("sk_test_...");
\Payjp\Tenant::create(
    array(
        "id" => "test",
        "name" => "test",
        "platform_fee_rate" => "10.15",
        "minimum_transfer_amount" => 1000,
        "bank_account_holder_name" => "ヤマダ タロウ",
        "bank_code" => "0001",
        "bank_branch_code" => "001",
        "bank_account_type" => "普通",
        "bank_account_number" => "0001000",
    )
);
const payjp = require('payjp')('sk_test_...');
payjp.tenants.create({id: 'test', platform_fee_rate: '10.15'});
// SDKは準備中です

レスポンス

{
  "created": 1433127983,
  "name": "test",
  "id": "test",
  "livemode": false,
  "metadata": null,
  "object": "tenant",
  "platform_fee_rate": "10.15",
  "payjp_fee_included": false,
  "minimum_transfer_amount": 1000,
  "bank_account_number": "0001000",
  "bank_branch_code": "000",
  "bank_code": "0000",
  "bank_account_holder_name": "ヤマダ タロウ",
  "bank_account_type": "普通",
  "bank_account_status": "pending",
  "currencies_supported": [
    "jpy"
  ],
  "default_currency": "jpy",
  "reviewed_brands": [
  ]
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to tenant.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

名前やIDなどを指定してテナントを作成します。

作成したテナントはあとから更新・削除することができます。

引数

name String 必須

テナント名


id String

テナントIDとなる任意の文字列。

一意にならないとエラーになります。また、未指定時は自動生成されます。


platform_fee_rate Float 必須

テナントのプラットフォーム利用料率(%)。 小数点以下2桁まで入力可能。

決済毎に、この料率の小数以下を切り捨てた金額がプラットフォーム利用料として適用されます。

後述の payjp_fee_included の値によって上限と下限が異なります。詳細は payjp_fee_included を確認ください。


payjp_fee_included Boolean

テナントのプラットフォーム利用料にPAY.JP決済手数料を含めるかどうか。 デフォルトはfalse。 この値によって指定可能な platform_fee_rate の範囲が変わります。

payjp_fee_included platform_fee_rate下限 platform_fee_rate上限
true 5.00 100.00
false 0.00 95.00

minimum_transfer_amount Integer

最低入金額。デフォルトは1万円で下限は1000円。締め日にこの金額以上の売上が貯まっていると入金手数料250円を引いた金額が振り込まれる。


bank_code String (Payouts型アカウントの場合は必須

4桁の銀行コード


bank_branch_code String (Payouts型アカウントの場合は必須

3桁の支店コード


bank_account_type String (Payouts型アカウントの場合は必須

預金種別


bank_account_number String (Payouts型アカウントの場合は必須

口座番号


bank_account_holder_name String (Payouts型アカウントの場合は必須

口座名義


metadata Object

キーバリューの任意データ

レスポンス

作成されたtenantオブジェクト

テナント情報を取得

GET https://api.pay.jp/v1/tenants/:id

curl https://api.pay.jp/v1/tenants/ten_121673955bd7aa144de5a8f6c262 \
-u sk_test_...:
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey("sk_test_...");
\Payjp\Tenant::retrieve("ten_121673955bd7aa144de5a8f6c262");
const payjp = require('payjp')('sk_test_...');
payjp.tenants.retrieve('ten_121673955bd7aa144de5a8f6c262');
SDKは準備中です

レスポンス

{
  "created": 1433127983,
  "name": "test",
  "id": "test",
  "livemode": false,
  "metadata": null,
  "object": "tenant",
  "platform_fee_rate": "10.15",
  "payjp_fee_included": false,
  "minimum_transfer_amount": 1000,
  "bank_account_number": "0001000",
  "bank_branch_code": "000",
  "bank_code": "0000",
  "bank_account_holder_name": "ヤマダ タロウ",
  "bank_account_type": "普通",
  "bank_account_status": "pending",
  "currencies_supported": [
    "jpy"
  ],
  "default_currency": "jpy",
  "reviewed_brands": [
    {
      "brand": "Visa",
      "status": "passed",
      "available_date": 143312900
    },
    {
      "brand": "MasterCard",
      "status": "passed",
      "available_date": 143312900
    },
    {
      "brand": "JCB",
      "status": "in_review",
      "available_date": null
    }
  ]
}

エラーレスポンス

{
  "error": {
    "message": "There is no tenant with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

テナント情報を取得します。

引数

なし

レスポンス

指定したIDのtenantオブジェクト

テナント情報を更新

POST https://api.pay.jp/v1/tenants/:id

curl https://api.pay.jp/v1/tenants/ten_121673955bd7aa144de5a8f6c262 \
-u sk_test_...: \
-d platform_fee_rate=30
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey("sk_test_...");
$te = \Payjp\Tenant::retrieve("ten_121673955bd7aa144de5a8f6c262");
$te->platform_fee_rate = "30";
$te->save();
const payjp = require('payjp')('sk_test_...');
payjp.tenants.update('ten_121673955bd7aa144de5a8f6c262', {platform_fee_rate: '30'});
SDKは準備中です

レスポンス

{
  "created": 1433127983,
  "name": "test",
  "id": "test",
  "livemode": false,
  "metadata": null,
  "object": "tenant",
  "platform_fee_rate": "30.00",
  "payjp_fee_included": false,
  "minimum_transfer_amount": 1000,
  "bank_account_number": "0001000",
  "bank_branch_code": "000",
  "bank_code": "0000",
  "bank_account_holder_name": "ヤマダ タロウ",
  "bank_account_type": "普通",
  "bank_account_status": "pending",
  "currencies_supported": [
    "jpy"
  ],
  "default_currency": "jpy",
  "reviewed_brands": [
  ]
}

エラーレスポンス

{
  "error": {
    "message": "There is no tenant with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

生成したテナント情報を更新することができます。

引数

name String

テナント名


platform_fee_rate Float

テナントのプラットフォーム利用料率(%)。小数点以下2桁まで入力可能。最大95%


minimum_transfer_amount Integer

最低入金額。デフォルトは1万円で下限は1000円。締め日にこの金額以上の売上が貯まっていると入金手数料250円を引いた金額が振り込まれる。


bank_code String

4桁の銀行コード


bank_branch_code String

3桁の支店コード


bank_account_type String

預金種別


bank_account_number String

口座番号


bank_account_holder_name String

口座名義


metadata Object

キーバリューの任意データ

レスポンス

更新されたtenantオブジェクト

テナントを削除

DELETE https://api.pay.jp/v1/tenants/:id

curl https://api.pay.jp/v1/tenants/ten_121673955bd7aa144de5a8f6c262 \
-u sk_test_...: \
-XDELETE
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey("sk_test_...");
$te = \Payjp\Tenant::retrieve("ten_121673955bd7aa144de5a8f6c262");
$te->delete();
const payjp = require('payjp')('sk_test_...');
payjp.tenants.delete('ten_121673955bd7aa144de5a8f6c262');
SDKは準備中です

レスポンス

{
  "deleted": true,
  "id": "ten_121673955bd7aa144de5a8f6c262",
  "livemode": false
}

エラーレスポンス

{
  "error": {
    "message": "There is no tenant with ID: ten_121673955bd7aa144de5a8f6c262",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

生成したテナント情報を削除します。

削除したテナントと同じIDのテナントをもう一度生成することができますが、削除したテナントとは別のテナントとして扱われます。

引数

なし

レスポンス


deleted Boolean

trueが入ります


id String

削除した定期課金ID


livemode Boolean

本番環境かどうか

テナントリストを取得

GET https://api.pay.jp/v1/tenants

curl https://api.pay.jp/v1/tenants?limit=3&offset=10 \
-u sk_test_...:
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey("sk_test_...");
\Payjp\Tenant::all(array("limit" => 3, "offset" => 10));
const payjp = require('payjp')('sk_test_...');
payjp.tenants.list();
SDKは準備中です

レスポンス

{
  "count": 2,
  "data": [
    {
      "bank_account_holder_name": "ヤマダ タロウ",
      "bank_account_number": "0001000",
      "bank_account_status": "pending",
      "bank_account_type": "普通",
      "bank_branch_code": "000",
      "bank_code": "0000",
      "created": 1547812255,
      "id": "test",
      "livemode": true,
      "metadata": {},
      "minimum_transfer_amount": 1000,
      "name": "test",
      "object": "tenant",
      "platform_fee_rate": "30.00",
      "payjp_fee_included": false,
      "currencies_supported": [
        "jpy"
      ],
      "default_currency": "jpy",
      "reviewed_brands": [
      ]
    },
    {
      "bank_account_holder_name": null,
      "bank_account_number": null,
      "bank_account_status": null,
      "bank_account_type": null,
      "bank_branch_code": null,
      "bank_code": null,
      "created": 1547812256,
      "id": "ten_a7b6241d6050dacd26995cce69e0",
      "livemode": false,
      "metadata": null,
      "minimum_transfer_amount": 1000,
      "name": "test2",
      "object": "tenant",
      "platform_fee_rate": "10.15",
      "payjp_fee_included": false,
      "currencies_supported": [
        "jpy"
      ],
      "default_currency": "jpy",
      "reviewed_brands": [
      ]
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/tenants"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to tenant.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

テナントのリストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得

レスポンス

e.g. https://pay.jp/_/applications/step1/fsnFCqqeevWf?return_to=https://example.com/

指定せずにurlアクセスした場合、もしくは指定したurlのフォーマットが不正な場合(e.g. http始まりでない場合など)は、PAY.JPの400 Bad Requestページに遷移します。 このケースのアクセスではURLは失効しません。

tenantオブジェクトlistオブジェクト

テナントの審査申請ページのURLを作成

POST https://api.pay.jp/v1/tenants/:id/application_urls

curl https://api.pay.jp/v1/tenants/ten_121673955bd7aa144de5a8f6c262/application_urls \
-XPOST \
-u sk_live_xxx:
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey("sk_live_xxx");
\Payjp\Tenant::retrieve("ten_121673955bd7aa144de5a8f6c262")->application_urls->create();
const payjp = require('payjp')('sk_live_xxx');
payjp.tenants.applicationUrls('ten_121673955bd7aa144de5a8f6c262');
SDKは準備中です

レスポンス

{
  "object": "application_url",
  "url": "https://pay.jp/_/applications/start/c24368137e384aa9xxxxxxxxxxxxxxxx",
  "expires": 1476676539
}

エラーレスポンス

{
  "error": {
    "message": "There is no tenant with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

(Marketplace型アカウントのみ利用可能)テナントの審査申請ページのURLを作成します。

このAPIは現在、本番秘密鍵でしか利用できません。

引数

なし

レスポンス


object String

オブジェクト名 値は"application_url”


url String

テナントの審査申請URL

urlには推測できないUUIDが含まれます。

urlは以下の条件で失効します。

失効したurlにアクセスした場合は、PAY.JPの404 Page NotFoundページに遷移します。

urlにアクセスする際は return_to パラメータの付与をお願いします。値には申請完了後に遷移するリダイレクト先URLをURLエンコードした状態で指定ください。

ex, https://pay.jp/_/applications/step1/fsnFCqqeevWf?return_to=https%3A%2F%2Fexample.com%2F%3Ffoo%3D1%26bar%3D2

指定せずにurlアクセスした場合、もしくは指定したurlのフォーマットが不正な場合(ex, http始まりでない場合など)は、PAY.JPの400 Bad Requestページに遷移します。 このケースのアクセスではURLは失効しません。


expires Integer

application_urlの使用期限のタイムスタンプ。発行から5分

Tenant Transfer (入金)

テナントの入金情報を取得できます。

プラットフォーマーの入金情報については PAY.JP API の Transfer (入金) をご利用ください。

tenant_transferオブジェクト

tenant_transferオブジェクト

{
  "amount": 1000,
  "carried_balance": null,
  "charges": {
    "count": 1,
    "data": [
      {
        "amount": 1000,
        "amount_refunded": 0,
        "captured": true,
        "captured_at": 1441706750,
        "card": {
          "address_city": null,
          "address_line1": null,
          "address_line2": null,
          "address_state": null,
          "address_zip": null,
          "address_zip_check": "unchecked",
          "brand": "Visa",
          "country": null,
          "created": 1441706750,
          "customer": null,
          "cvc_check": "unchecked",
          "exp_month": 5,
          "exp_year": 2018,
          "fingerprint": "e1d8225886e3a7211127df751c86787f",
          "id": "car_93e59e9a9714134ef639865e2b9e",
          "last4": "4242",
          "name": null,
          "object": "card"
        },
        "created": 1441706750,
        "currency": "jpy",
        "customer": "cus_b92b879e60f62b532d6756ae12af",
        "description": null,
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "id": "ch_60baaf2dc8f3e35684ebe2031a6e0",
        "object": "charge",
        "paid": true,
        "platform_fee": null,
        "platform_fee_rate": "30.00",
        "refund_reason": null,
        "refunded": false,
        "subscription": null,
        "tenant": "test",
        "total_platform_fee": 300
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "https://api.pay.jp/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/tenant_transfers/ten_tr_23748b8c95c79edff22a8b7b795xx/charges"
  },
  "created": 1438354800,
  "currency": "jpy",
  "id": "ten_tr_23748b8c95c79edff22a8b7b795xx",
  "livemode": false,
  "object": "tenant_transfer",
  "scheduled_date": "2015-09-16",
  "status": "pending",
  "summary": {
    "charge_count": 1,
    "charge_fee": 10,
    "total_platform_fee": 300,
    "charge_gross": 1000,
    "net": 690,
    "refund_amount": 0,
    "refund_count": 0
  },
  "tenant_id": "test",
  "term_end": 1439650800,
  "term_start": 1438354800
}

基本的にtransferオブジェクトと同じになります。

追加・値の上書きがあるプロパティのみ以下に記載します。

プロパティ


object String

tenant_transferオブジェクトでは"tenant_transfer"の固定文字列となります


id String

tenant_transferオブジェクトではten_tr_で始まる一意なオブジェクトを示す文字列となります


description String

tenant_transferオブジェクトにはこのプロパティはありません


summary[total_platform_fee] Integer

tenant_transferオブジェクトのみ追加されます。

summary プロパティのオブジェクト内に total_platform_fee プロパティが追加されます。

プラットフォーム手数料総額を表します。


tenant_id String

tenant_transferオブジェクトのみ追加されます。

テナントID

テナントの入金情報を取得

GET https://api.pay.jp/v1/tenant_transfers/:tenant_transfer_id

curl https://api.pay.jp/v1/tenant_transfers/ten_tr_23748b8c95c79edff22a8b7b795xx \
-u sk_test_...:
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey("sk_test_...");
\Payjp\TenantTransfer::retrieve("ten_tr_23748b8c95c79edff22a8b7b795xx");
const payjp = require('payjp')('sk_test_...');
payjp.tenant_transfers.retrieve('ten_tr_23748b8c95c79edff22a8b7b795xx');
SDKは準備中です

レスポンス

{
  "amount": 1000,
  "carried_balance": null,
  "charges": {
    "count": 1,
    "data": [
      {
        "amount": 1000,
        "amount_refunded": 0,
        "captured": true,
        "captured_at": 1441706750,
        "card": {
          "address_city": null,
          "address_line1": null,
          "address_line2": null,
          "address_state": null,
          "address_zip": null,
          "address_zip_check": "unchecked",
          "brand": "Visa",
          "country": null,
          "created": 1441706750,
          "customer": null,
          "cvc_check": "unchecked",
          "exp_month": 5,
          "exp_year": 2018,
          "fingerprint": "e1d8225886e3a7211127df751c86787f",
          "id": "car_93e59e9a9714134ef639865e2b9e",
          "last4": "4242",
          "name": null,
          "object": "card"
        },
        "created": 1441706750,
        "currency": "jpy",
        "customer": "cus_b92b879e60f62b532d6756ae12af",
        "description": null,
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "id": "ch_60baaf2dc8f3e35684ebe2031a6e0",
        "object": "charge",
        "paid": true,
        "platform_fee": null,
        "platform_fee_rate": "30.00",
        "refund_reason": null,
        "refunded": false,
        "subscription": null,
        "tenant": "test",
        "total_platform_fee": 300
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "https://api.pay.jp/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/tenant_transfers/ten_tr_23748b8c95c79edff22a8b7b795xx/charges"
  },
  "created": 1438354800,
  "currency": "jpy",
  "id": "ten_tr_23748b8c95c79edff22a8b7b795xx",
  "livemode": false,
  "object": "tenant_transfer",
  "scheduled_date": "2015-09-16",
  "status": "pending",
  "summary": {
    "charge_count": 1,
    "charge_fee": 10,
    "total_platform_fee": 300,
    "charge_gross": 1000,
    "net": 690,
    "refund_amount": 0,
    "refund_count": 0
  },
  "tenant_id": "test",
  "term_end": 1439650800,
  "term_start": 1438354800
}

エラーレスポンス

{
  "error": {
    "message": "There is no tenant transfer with ID: dummy",
    "param": "id",
    "status": 404,
    "type": "client_error"
  }
}

テナントの入金情報を取得します。

引数

なし

レスポンス

指定したidのtenant_transferオブジェクト

テナントの入金リストを取得

GET https://api.pay.jp/v1/tenant_transfers

curl https://api.pay.jp/v1/tenant_transfers?limit=1 \
-u sk_test_...:
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey("sk_test_...");
\Payjp\TenantTransfer::all(array("tenant"=>"test"));
const payjp = require('payjp')('sk_test_...');
payjp.tenant_transfers.list({transfer: 'tr_8f0c0fe2c9f8a47f9d18f03959ba1'})
SDKは準備中です

レスポンス

{
  "count": 1,
  "data": [
    {
      "amount": 1000,
      "carried_balance": null,
      "charges": {
        "count": 1,
        "data": [
          {
            "amount": 1000,
            "amount_refunded": 0,
            "captured": true,
            "captured_at": 1441706750,
            "card": {
              "address_city": null,
              "address_line1": null,
              "address_line2": null,
              "address_state": null,
              "address_zip": null,
              "address_zip_check": "unchecked",
              "brand": "Visa",
              "country": null,
              "created": 1441706750,
              "customer": null,
              "cvc_check": "unchecked",
              "exp_month": 5,
              "exp_year": 2018,
              "fingerprint": "e1d8225886e3a7211127df751c86787f",
              "id": "car_93e59e9a9714134ef639865e2b9e",
              "last4": "4242",
              "name": null,
              "object": "card"
            },
            "created": 1441706750,
            "currency": "jpy",
            "customer": "cus_b92b879e60f62b532d6756ae12af",
            "description": null,
            "expired_at": null,
            "failure_code": null,
            "failure_message": null,
            "id": "ch_60baaf2dc8f3e35684ebe2031a6e0",
            "object": "charge",
            "paid": true,
            "platform_fee": 50,
            "platform_fee_rate": "30.00",
            "refund_reason": null,
            "refunded": false,
            "subscription": null,
            "tenant": "test",
            "total_platform_fee": 50
          }
        ],
        "has_more": false,
        "object": "list",
        "url": "/v1/tenant_transfers/ten_tr_23748b8c95c79edff22a8b7b795xx/charges"
      },
      "created": 1438354800,
      "currency": "jpy",
      "id": "ten_tr_23748b8c95c79edff22a8b7b795xx",
      "livemode": false,
      "object": "tenant_transfer",
      "scheduled_date": "2015-09-16",
      "status": "pending",
      "summary": {
        "charge_count": 1,
        "charge_fee": 10,
        "total_platform_fee": 50,
        "charge_gross": 1000,
        "net": 940,
        "refund_amount": 0,
        "refund_count": 0
      },
      "tenant_id": "test",
      "term_end": 1439650800,
      "term_start": 1438354800
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/tenant_transfers"
}

エラーレスポンス

{
  "error": {
    "message": "Invalid query string.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

テナントの入金リストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得


status String

tenant_transferオブジェクトのステータス


transfer String

入金IDで絞り込みたい場合に指定


tenant String

テナントIDで絞り込みたい場合に指定

レスポンス

tenant_transferオブジェクトlistオブジェクト

テナントの入金の内訳を取得

GET https://api.pay.jp/v1/tenant_transfers/:tenant_transfer_id/charges

curl https://api.pay.jp/v1/tenant_transfers/ten_tr_23748b8c95c79edff22a8b7b795xx/charges \
-u sk_test_...:
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey("sk_test_...");
\Payjp\TenantTransfer::retrieve("ten_tr_23748b8c95c79edff22a8b7b795xx")->charges->all();
const payjp = require('payjp')('sk_test_...');
payjp.tenant_transfers.charges('ten_tr_23748b8c95c79edff22a8b7b795xx', {customer: 'test'});
SDKは準備中です

レスポンス

{
  "count": 1,
  "data": [
    {
      "amount": 1000,
      "amount_refunded": 0,
      "captured": true,
      "captured_at": 1441706750,
      "card": {
        "address_city": null,
        "address_line1": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": "unchecked",
        "brand": "Visa",
        "country": null,
        "created": 1441706750,
        "customer": null,
        "cvc_check": "unchecked",
        "exp_month": 5,
        "exp_year": 2018,
        "fingerprint": "e1d8225886e3a7211127df751c86787f",
        "id": "car_93e59e9a9714134ef639865e2b9e",
        "last4": "4242",
        "name": null,
        "object": "card"
      },
      "created": 1441706750,
      "currency": "jpy",
      "customer": "cus_b92b879e60f62b532d6756ae12af",
      "description": null,
      "expired_at": null,
      "failure_code": null,
      "failure_message": null,
      "id": "ch_60baaf2dc8f3e35684ebe2031a6e0",
      "object": "charge",
      "paid": true,
      "platform_fee": null,
      "platform_fee_rate": "30.00",
      "refund_reason": null,
      "refunded": false,
      "subscription": null,
      "tenant": "test",
      "total_platform_fee": 300
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/transfers/tr_8f0c0fe2c9f8a47f9d18f03959ba1/tenant_transfers/ten_tr_23748b8c95c79edff22a8b7b795xx/charges"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_param_key",
    "message": "Invalid param key to tenant_transfer.",
    "param": "dummy",
    "status": 400,
    "type": "client_error"
  }
}

特定のテナント入金の内訳の支払いリストを取得します。

引数


limit Integer

取得するデータ数の最大値(1~100まで)。指定がない場合は 10 となる。


offset Integer

基準点からのデータ取得を行う開始位置。指定がない場合は 0 となる。


since Integer

タイムスタンプ

指定したタイムスタンプ以降に作成されたデータのみ取得


until Integer

タイムスタンプ

指定したタイムスタンプ以前に作成されたデータのみ取得


customer String

顧客IDで絞り込みたい場合に指定

レスポンス

chargeオブジェクトlistオブジェクト