NAV
curl Python Ruby PHP Node.js Java Go

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")
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
// ここでは最新版(`beta`ブランチ)のAPI仕様を記載しています

// go.modにbetaブランチのコードを記載ください。
require (
    github.com/payjp/payjp-go beta
)

// $go mod tidy
// ※betaというバージョン名は自動的に修正される可能性があります。

// または明示的にパッケージをプロジェクトに`go get`ください。
// $go get -u github.com/payjp/payjp-go@beta

// payjpの初期化は以下の通りです
package main
import (
    payjp "github.com/payjp/payjp-go/v1"
)

func main() {
    pay := payjp.New("sk_test_c62fade9d045b54cd76d7036", nil)
    // 具体的な実装例は以下で公開しています
    // https://github.com/payjp/payjp-go/tree/beta/v1/examples
}

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)で返されます。

タイムスタンプ

日次に関するデータはUNIXタイムスタンプで表示されます。 ただし一部のパラメータはDate型(e.g. 入金予定日 transfer.scheduled_date が 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 {
  // request, such as `Charge.retrieve("ch_xxx");`
} catch (CardException e) {
  // 402 カード認証・支払いエラー
  System.out.println(e.getStatus()); // HTTP Status (int)
  System.out.println(e.getCode()); // error[code] (String/null)
  System.out.println(e.getParam()); // error[param] (String/null)
  System.out.println(e.getMessage()); // error[message] (String)
} catch (InvalidRequestException e) {
  // 400 不正なパラメーターなどのリクエストエラー
  // or
  // 404 存在しないAPIリソース
  System.out.println(e.getStatus()); // HTTP Status (int)
  System.out.println(e.getCode()); // error[code] (String/null)
  System.out.println(e.getParam()); // error[param] (String/null)
  System.out.println(e.getType()); // error[type] (String)
  System.out.println(e.getMessage()); // error[message] (String) or SDK内でのエラーメッセージ
} catch (AuthenticationException e) {
  // 401 APIキーの認証エラー
  // or
  // リクエスト前のAPIキーのバリデーションでAPIキーが空文字など明らかに不正の場合
  System.out.println(e.getStatus()); // HTTP Status (int)
  System.out.println(e.getMessage()); // error[message] (String) or SDK内でのエラーメッセージ
} catch (APIException e) {
  // その他の400, 500系エラー (非JSONレスポンス、タイムアウト、など)
  // or
  // 様々な要因によるAPIエラー
  System.out.println(e.getStatus()); // HTTP Status (int)
  System.out.println(e.getMessage()); // error[message] (String) or SDK内でのエラーメッセージ
} catch (APIConnectionException e) {
  // リクエスト中のIOException (ご自身のネットワーク環境をご確認ください)
  // or
  // 不正なHTTP methodでのリクエスト (SDKのバグの可能性があるのでご連絡ください)
  System.out.println(e.getMessage()); // SDK内での認証エラーメッセージ
} catch (Exception e) {
  // Payjp SDKとは直接関係のない例外発生時
}
charge, err := pay.Charge.Retrieve("ch_xxx")
if err != nil {
    fmt.Println(err) // 404: Type: client_error Code: invalid_id Message: No such charge: ch_hoge, Param: id
    // or err.Error() も同じ文字列を返します

    // APIにおけるエラーの個別の情報は以下のように取得できます
    if e, ok := err.(*payjp.Error); ok {
        fmt.Println(e.Status) // 404
        fmt.Println(e.Type) // client_error
        fmt.Println(e.Code) // invalid_id
        fmt.Println(e.Message) // No such charge: ch_xxx
        fmt.Println(e.Param) // id
    }
}

エラーとなるリクエストには error というキーが含まれたレスポンスが返されます。

error 内には status type message code というキー・バリューが入ります。 エラーによっては param charge などのキー・バリューが追加で存在したり、 code キーがない場合などもあります。

なお、各SDKにおけるエラーハンドリング例は画面右側の言語タブを切り替えてご確認ください。

error[type] 詳細
client_error リクエストエラー
card_error カードに関するエラー
server_error PAY.JPや決済ネットワーク側のエラー
not_allowed_method_error 許可されていないメソッドエラー
auth_error 認証エラー
invalid_request_error 無効なリクエスト
error[code] 詳細
invalid_number 不正なカード番号 [deprecated]
invalid_cvc 不正なCVC [deprecated]
invalid_expiration_date 不正な有効期限年、または月 [deprecated]
incorrect_card_data いずれかのカード情報が誤っている [2020/12/10以降新設]
invalid_expiry_month 不正な有効期限月
invalid_expiry_year 不正な有効期限年
expired_card 支払いを作成APIで引数customer(とcard)を指定したが紐づくカードが有効期限切れ
card_declined カード会社によって拒否されたカード
card_flagged カードを原因としたエラーが続いたことによる一時的なロックアウト
対応方法についてはこちらを参照ください
processing_error 決済ネットワーク上で生じたエラー
missing_card 支払いを作成APIで指定した引数customerがデフォルトカードを持っていない
unacceptable_brand 対象のカードブランドが許可されていない
invalid_id 不正なID
no_api_key APIキーがセットされていない
invalid_api_key 不正なAPIキー
invalid_plan 不正なプラン
invalid_expiry_days 不正な失効日数
unnecessary_expiry_days 失効日数が不要なパラメーターである
invalid_flexible_id Planなど任意に指定できる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 返金理由 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 定期課金の作成APIで指定した引数customerがデフォルトカードを持っていない
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 本番モードが許可されていないアカウント
payjp_wrong PAY.JPのサーバー側でエラーが発生している
pg_wrong 決済代行会社のサーバー側でエラーが発生している
not_found リクエスト先が存在しないことを示す
not_allowed_method 許可されていないHTTPメソッド
over_capacity レートリミットに到達
refund_limit_exceeded 期限を過ぎた後の返金操作
cannot_prorated_refund_of_subscription 返金期限を過ぎた為、定期課金の日割り返金が行えない
three_d_secure_incompleted 3Dセキュアフローが完了していない状態で別の操作を行った
three_d_secure_failed 3Dセキュア認証に失敗した
not_in_three_d_secure_flow 3Dセキュア対象外の支払いか、3Dセキュアフローが時間切れになった
unverified_token 3Dセキュアが完了していないトークンで支払いが行われた
invalid_owner_type ownerパラメータに指定できない値
invalid_three_d_secure_state 3Dセキュア中に二重に処理されるなど不正な遷移をした
not_customer_card 顧客のカードとして登録されていないか、削除済み
error[status] Meaning
200 リクエスト成功
400 不正なパラメーターなどのリクエストエラー
401 APIキーの認証エラー
402 カード認証・支払いエラー
404 存在しないAPIリソース
429 レートリミットによるアクセス一時拒否
500 PAY.JPや決済ネットワークでの障害

Rate Limit

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

ゾーン

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

ゾーン 対象範囲
pk 公開鍵によるトークン作成へのアクセスが該当
payment 以下のAPIが該当
支払い作成
支払い処理を確定する
返金する
支払いを再認証する
3Dセキュアフローを完了する
sk 秘密鍵によるAPIアクセスのうち、paymentに該当しないもの

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

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

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

リミットの挙動

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

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

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

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

リミットへの対応

import payjp

payjp.max_retry = 3  # 最大リトライ回数
payjp.retry_initial_delay = 2  # 初期ディレイ (秒)
payjp.retry_max_delay = 32  # 最大ディレイ (秒)
\Payjp\Payjp::setMaxRetry(3); // 最大リトライ回数
\Payjp\Payjp::setRetryInitialDelay(2); // 初期ディレイ (秒)
\Payjp\Payjp::setRetryMaxDelay(32); // 最大ディレイ (秒)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp.max_retry = 3 # 最大リトライ回数
Payjp.retry_initial_delay = 2 # 初期ディレイ (秒)
Payjp.retry_max_delay = 32 # 最大ディレイ (秒)
// 例) リトライ回数5回、初期ディレイ1秒、最大ディレイ20秒
const payjp = new Payjp('sk_live_xxx', {maxRetry: 5, retryInitialDelay: 1000, retryMaxDelay: 20 * 1000})
Payjp.maxRetry = 3; // 最大リトライ回数
Payjp.retryInitialDelay = 2; // 初期ディレイ (秒)
Payjp.retryMaxDelay = 32; // 最大ディレイ (秒)
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
// 初期化時にオプションを指定できます。以下はリトライ回数5回、初期ディレイ1秒、最大ディレイ10秒、リトライログを出力する設定例です。
pay := payjp.New("sk_test_c62fade9d045b54cd76d7036", nil,
    payjp.WithMaxCount(5), // 最大リトライ回数。デフォルトは0
    payjp.WithInitialDelay(1), // 初期ディレイ (秒)。デフォルトは2
    payjp.WithMaxDelay(10), // 最大ディレイ (秒)。デフォルトは32
    payjp.WithLogger(payjp.NewPayjpLogger(payjp.LogLevelInfo)) // ログ出力。デフォルトではログは出力されません。
)

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

また、リトライに対応しているライブラリでは、オプションを設定することによりライブラリ側でレートリミットに対する自動リトライを有効化することができます。オプションの指定方法は右ペインのサンプルコードをご参照ください。
(対応済み言語のみサンプルを記載しています。対応言語は随時拡大して参ります。)

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

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));
const 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);
// .All(params) (or .AllCard(params))を利用します。
// 注. .List().Limit(10).Do() のような以前の記法はDeprecatedとなっております。

// paramsはポインタ型です。全てのフィールドはポインタ型である必要があります。
params := &payjp.EventListParams{
    ListParams: payjp.ListParams{ // 全リソースの検索で共通なフィールド
        Limit:  payjp.Int(10),
        Offset: payjp.Int(0),
    },
    ResourceID: payjp.String("b"), // EventListParams固有のフィールド
}
// 各リソース毎の XXXListParams (上ではEventListParams)は、全リソースの検索で共通な
// ListParams構造体{Limit/Offset/Since/Until} をEmbeddingしています。
// 初期化は、上の場合はネストが必要ですが、下の場合は不要です。
params.Since = payjp.Int(1455328095) // ListParams構造体のフィールド
params.Object = payjp.String("c") // EventListParams固有のフィールド

data, hasMore, err := pay.Event.All(params)
// レスポンスは以下の通りです。
// data: []*EventResponse
// hasMore: bool
// ※ countの取得は、dataの長さを取得することで行ってください。

レスポンス

{
  "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")
));
const 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);
params := payjp.Plan{
  Metadata: map[string]string{
    "user_id": "123",
  },
}

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

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

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

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

イベントとWebhook

APIリソースの作成や操作が行われると eventオブジェクト が作成され、送信先の登録があればWebhookの送信が行われます。

イベント一覧

type 内容
charge.succeeded 支払いの成功
charge.failed 支払いの失敗
charge.updated 支払いの更新
charge.refunded 支払いの返金
charge.captured 支払いの確定
dispute.created チャージバック発生
token.created トークンの作成
customer.created 顧客の作成
customer.updated 顧客の更新
customer.deleted 顧客の削除
customer.card.created 顧客のカード作成
customer.card.updated 顧客のカード更新
customer.card.deleted 顧客のカード削除
plan.created プランの作成
plan.updated プランの更新
plan.deleted プランの削除
subscription.created 定期課金の作成
subscription.updated 定期課金の更新
subscription.deleted 定期課金の削除
subscription.paused 定期課金の停止
subscription.resumed 定期課金の再開
subscription.canceled 定期課金のキャンセル
subscription.renewed 定期課金の期間更新
transfer.succeeded 入金内容の確定 (通常加盟店、プラットフォーマー)
tenant.created テナント作成(PAY.JP Platformのみ)
tenant.deleted テナント削除(PAY.JP Platformのみ)
tenant.updated テナント情報の更新、本番申請(初回・更新含む)、弊社による審査結果反映(PAY.JP Platformのみ)
tenant_transfer.succeeded テナントの入金内容の確定(PAY.JP Platformのみ)
term.created 区間の作成
term.closed 区間の売上締め処理が終了
statement.created 取引明細の作成
balance.created 残高の作成
balance.fixed 残高が振込もしくは請求に確定した
balance.closed 残高の精算が完了
balance.merged 残高がマージされた

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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": null
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": null,
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "fee_rate": "3.00",
  "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,
  "three_d_secure_status": null
}

プロパティ


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

失敗した支払いの説明


fee_rate 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のみ

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


three_d_secure_status String

3Dセキュアの実施状況

status 意味
(null) 3Dセキュアなし
unverified 3Dセキュア未実施
verified 認証成功
attempted アテンプト
failed 認証失敗
error 認証処理エラー

term_id String

入金管理オブジェクトの刷新に伴い、2024/06/01以降に提供されます。

この支払いが関連付けられたTermオブジェクトのID

chargeイベント

charge.succeeded

支払いの成功

charge.failed

支払いの失敗

charge.updated

支払いの更新

charge.refunded

支払いの返金

charge.captured

支払いの確定

支払いを作成

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);
charge, err := pay.Charge.Create(3500, payjp.Charge{
    CustomerID:     "cus_req1",
    CustomerCardID: "car_req1",
    Description:    "desc",
    Capture:        true,
    Metadata: map[string]string{
        "hoge": "fuga",
    },
    ThreeDSecure: payjp.Bool(false),
})

レスポンス

{
  "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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": null,
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": null,
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "fee_rate": "3.00",
  "id": "ch_fa990a4c10672a93053a774730b0a",
  "livemode": false,
  "metadata": null,
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": false,
  "subscription": null,
  "three_d_secure_status": 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 で設定されました期間を過ぎると解放されるようなっております。

three_d_secure にtrueを指定することで、3Dセキュアを開始できます。 指定した場合、支払いオブジェクトは作成されますが実際の決済処理は保留された状態になります。 保留中の支払いは、引数指定の内容に関わらずcapturedfalsecaptured_atnullexpired_atnullと表示されます。 なお、支払い作成から一定時間を経過すると、3Dセキュアフローはタイムアウトし、処理が進められなくなります。 3Dセキュアの進め方は、 支払いで3Dセキュアを実施する を参照してください。

引数


amount Integer

50~9,999,999の整数

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


currency String

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

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


product String

プロダクトID

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


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


three_d_secure Boolean

3Dセキュアを行うならtrue

レスポンス

作成された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");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.retrieve('ch_fa990a4c10672a93053a774730b0a');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Charge.retrieve("ch_fa990a4c10672a93053a774730b0a");
charge, err := pay.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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": null,
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": null,
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "fee_rate": "3.00",
  "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オブジェクト

3Dセキュアフローを完了する

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

curl https://api.pay.jp/v1/charges/ch_fa990a4c10672a93053a774730b0a/tds_finish \
-u sk_test_c62fade9d045b54cd76d7036: \
-XPOST
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = payjp.Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
charge.tds_finish()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
charge = Payjp::Charge.retrieve('ch_fa990a4c10672a93053a774730b0a')
charge.tds_finish
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$ch = \Payjp\Charge::retrieve("ch_fa990a4c10672a93053a774730b0a");
$ch->tdsFinish();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.tds_finish('ch_fa990a4c10672a93053a774730b0a');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Charge ch = Charge.retrieve("ch_fa990a4c10672a93053a774730b0a");
ch.tds_finish();
charge, err := pay.Charge.TdsFinish("ch_fa990a4c10672a93053a774730b0a")

レスポンス

{
  "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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": null,
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "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,
  "three_d_secure_status": "verified"
}

エラーレスポンス

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

3Dセキュア認証が終了した支払いに対し、決済を行います。 支払いを作成 と同様の決済処理が実行され、実際の請求が行われる状態になります。カードの状態によっては支払いに失敗し、402エラーとなる点も同様です。 保留中の支払いで固定値となっていたcapturecaptured_atexpired_atは、支払い作成時に指定した通りに反映されます。captured_atexpired_atの時刻は本APIにリクエストした時刻を基準として設定されます。

three_d_secure_statusverifiedattemptedでない支払いに対して本APIをリクエストした場合、エラーとなります。

引数

なし

レスポンス

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();
const 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);
charge, err := pay.Charge.Update("ch_fa990a4c10672a93053a774730b0a", "new description", map[string]string{
    "hoge": "fuga",
})

レスポンス

{
  "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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": null,
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": "Updated",
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "fee_rate": "3.00",
  "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));
const 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();
charge, err := pay.Charge.Refund("ch_fa990a4c10672a93053a774730b0a", "reason")

レスポンス

{
  "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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": null,
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": "Updated",
  "expired_at": null,
  "failure_code": null,
  "failure_message": null,
  "fee_rate": "3.00",
  "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

返金理由 (255文字以内)

レスポンス

返金後の状態の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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": null,
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "created": 1470088864,
  "currency": "jpy",
  "customer": "cus_137f2aec147eeafe849841d093a3",
  "description": null,
  "expired_at": 1470175385,
  "failure_code": null,
  "failure_message": null,
  "fee_rate": "3.00",
  "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();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.capture('ch_fa990a4c10672a93053a774730b0a', {});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Charge ch = Charge.retrieve("ch_cce2fce62e9cb5632b3d38b0b1621");
ch.capture();
charge, err := pay.Charge.Capture("ch_cce2fce62e9cb5632b3d38b0b1621", 100)
// or
err = charge.Capture(100)

レスポンス

{
  "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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": null,
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "created": 1433127983,
  "currency": "jpy",
  "customer": null,
  "description": null,
  "expired_at": 1433429999,
  "failure_code": null,
  "failure_message": null,
  "fee_rate": "3.00",
  "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));
const 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);
params := &payjp.ChargeListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(10),
        Offset: payjp.Int(0),
    },
    Customer:   payjp.String("a"),
    Subscription: payjp.String("b"),
    Tenant:     payjp.String("c"),
}
charges, hasMore, err = pay.Charge.All(params)

レスポンス

{
  "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": "PAY TARO",
        "object": "card",
        "three_d_secure_status": null,
        "email": "liveaccount@example.com",
        "phone": "+81301234567"
      },
      "created": 1432965397,
      "currency": "jpy",
      "customer": "cus_67fab69c14d8888bba941ae2009b",
      "description": "test charge",
      "expired_at": null,
      "failure_code": null,
      "failure_message": null,
      "fee_rate": "3.00",
      "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


term String

入金管理オブジェクトの刷新に伴い、2024/06/01以降に提供されます。

絞り込みたいTermの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": "PAY TARO",
  "object": "card",
  "three_d_secure_status": "verified",
  "email": "liveaccount@example.com",
  "phone": "+81301234567"
}

プロパティ


object String

"card"の固定文字列


id String

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


created Integer

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


name String

カード保有者名(e.g. "PAY TARO")

45文字以下の半角英数字、スペース ピリオド ハイフンのみに形式の変更を予定しております。
詳細はこちら

2024年8月以降、3Dセキュア認証の際にデータ入力が求められます。
詳細はこちら


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

address_zipの値のチェック結果。
この結果は決済に影響しません。

passed 日本国内の有効な郵便番号
failed 郵便番号形式の値だが、日本国内の有効な郵便番号ではない
unchecked 値がない、または国内の郵便番号の形式ではない

metadata Object

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


three_d_secure_status String

トークン3Dセキュアの結果

値についてはcharge.three_d_secure_statusに同じ


email String

メールアドレス

2024年8月以降、3Dセキュア認証の際にphoneまたはemailのデータ入力が求められます。
詳細はこちら


phone String

E.164形式の電話番号 (e.g. 090-0123-4567(日本) => "+819001234567")

2024年8月以降、3Dセキュア認証の際にphoneまたはemailのデータ入力が求められます。
詳細はこちら

customerイベント

customer.created

顧客の作成

customer.updated

顧客の更新

customer.deleted

顧客の削除

customer.card.created

顧客のカード作成

customer.card.updated

顧客のカード更新

customer.card.deleted

顧客のカード削除

顧客を作成

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"
));
const 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);
customer, err := pay.Customer.Create(payjp.Customer{
    Email:       payjp.String("example@example.com"),
    Description: payjp.String("test"),
    ID:          payjp.String("test"),
    CardToken:   payjp.String("tok_xxx"),
})

レスポンス

{
  "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

メールアドレス


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");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.retrieve('cus_121673955bd7aa144de5a8f6c262');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer.retrieve("cus_121673955bd7aa144de5a8f6c262");
customer, err := pay.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();
const 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);
customer, err := pay.Customer.Update("cus_121673955bd7aa144de5a8f6c262", payjp.Customer{
    Email: payjp.String("test@mail.com"),
})
// or
customer, err = pay.Customer.Retrieve("cus_121673955bd7aa144de5a8f6c262")
err = customer.Update(payjp.Customer{
    Email: payjp.String("test@mail.com"),
})

レスポンス

{
  "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();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.delete('cus_121673955bd7aa144de5a8f6c262');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_121673955bd7aa144de5a8f6c262");
cu.delete();
err := pay.Customer.Delete("cus_121673955bd7aa144de5a8f6c262")
// or
customer, err := pay.Customer.Retrieve("cus_121673955bd7aa144de5a8f6c262")
err = customer.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));
const 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);
customers, hasMore, err := pay.Customer.All(&payjp.CustomerListParams{
    ListParams: payjp.ListParams{
        Limit: payjp.Int(10),
        Since: payjp.Int(1455328095),
    },
})
// 以下の書き方は廃止予定です
customers, hasMore, err = pay.Customer.List().
    Limit(10).
    Since(time.Unix(1455328095, 0)).Do()

レスポンス

{
  "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"
));
const 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")
card, err := pay.Customer.AddCardToken("cus_121673955bd7aa144de5a8f6c262", "tok_xxx", payjp.Customer{
    DefaultCard: true,
}))

レスポンス

{
  "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": "PAY TARO",
  "object": "card",
  "three_d_secure_status": "verified",
  "email": "liveaccount@example.com",
  "phone": "+81301234567"
}

エラーレスポンス

{
  "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");
const 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");
card, err := pay.Customer.GetCard("cus_121673955bd7aa144de5a8f6c262", "car_f7d9fa98594dc7c2e42bfcd641ff")
// or
customer, err := pay.Customer.Retrieve("cus_121673955bd7aa144de5a8f6c262")
card, err = customer.GetCard("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": "PAY TARO",
  "object": "card",
  "three_d_secure_status": "verified",
  "email": "liveaccount@example.com",
  "phone": "+81301234567"
}

エラーレスポンス

{
  "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();
const 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);
card, err := pay.Customer.UpdateCard("cus_121673955bd7aa144de5a8f6c262", "car_f7d9fa98594dc7c2e42bfcd641ff", payjp.Card{
    Name: "pay",
})
// or
customer, err := pay.Customer.Retrieve("cus_121673955bd7aa144de5a8f6c262")
err = customer.Cards[0].Update(payjp.Card{
    Name: "pay",
})

レスポンス

{
  "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": "PAY TARO",
  "object": "card",
  "three_d_secure_status": "verified",
  "email": "liveaccount@example.com",
  "phone": "+81301234567"
}

エラーレスポンス

{
  "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. "PAY TARO")

45文字以下の半角英数字、スペース ピリオド ハイフンのみに形式の変更を予定しております。詳細はこちら


email String

メールアドレス


phone String

E.164形式の電話番号 (e.g. 090-0123-4567(日本) => "+819001234567")


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();
const 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();
err := pay.Customer.DeleteCard("cus_121673955bd7aa144de5a8f6c262", "car_f7d9fa98594dc7c2e42bfcd641ff")
// or
customer, err := pay.Customer.Retrieve("cus_121673955bd7aa144de5a8f6c262")
card := customer.Cards[0]
err = card.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));
const 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);
customer, err := pay.Customer.Retrieve("cus_121673955bd7aa144de5a8f6c262")
cards, hasMore, err = customer.AllCard(&payjp.CardListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(10),
        Offset: payjp.Int(15),
    },
})

レスポンス

{
  "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": "PAY TARO",
      "object": "card",
      "three_d_secure_status": "verified",
      "email": "liveaccount@example.com",
      "phone": "+81301234567"
    }
  ],
  "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");
const 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);
subscription, err := pay.Customer.GetSubscription("cus_121673955bd7aa144de5a8f6c262", "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,
  "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));
const 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);
subscriptions, hasMore, err := pay.Subscription.All(payjp.SubscriptionListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(10),
        Offset: payjp.Int(15),
    },
    Customer: payjp.String("cus_121673955bd7aa144de5a8f6c262"),
})

レスポンス

{
  "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

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

planイベント

plan.created

プランの作成

plan.updated

プランの更新

plan.deleted

プランの削除

プランを作成

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,
));
const 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);
plan, err := pay.Plan.Create(payjp.Plan{
    Amount:    500,
    Currency:  "jpy",
    Interval:  "month",
})

レスポンス

{
  "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");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.plans.retrieve('pln_45dd3268a18b2837d52861716260');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Plan.retrieve("pln_45dd3268a18b2837d52861716260");
plan, err := pay.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();
const 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);
plan, err := pay.Plan.Update("pln_req", payjp.Plan{
    Name: "name",
})
// or
err = plan.Update(payjp.Plan{
    Name: "new_name",
    Metadata: map[string]string{
        "hoge": "fuga",
    },
})

レスポンス

{
  "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();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.plans.delete('pln_45dd3268a18b2837d52861716260');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Plan p = Plan.retrieve("pln_45dd3268a18b2837d52861716260");
p.delete();
err := pay.Plan.Delete("pln_45dd3268a18b2837d52861716260")
// or
plan, err := pay.Plan.Retrieve("pln_45dd3268a18b2837d52861716260")
err = plan.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));
const 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);
params := &payjp.PlanListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(10),
        Offset: payjp.Int(0),
        Since:  payjp.Int(1455328095),
    },
}
plans, hasMore, err := pay.Plan.All(params)

レスポンス

{
  "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オブジェクトのリスト。

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

Statement (取引明細)

売上や請求を集計項目ごとに集計したオブジェクトです。

statementオブジェクト

statementオブジェクト

{
  "created": 1695892351,
  "id": "st_178fd25dc7ab7b75906f5d4c4b0e6",
  "items": [
    {
      "amount": 3125,
      "name": "売上",
      "subject": "gross_sales",
      "tax_rate": "0.00"
    },
    {
      "amount": -75,
      "name": "決済手数料",
      "subject": "fee",
      "tax_rate": "0.00"
    },
    {
      "amount": -1800,
      "name": "返金",
      "subject": "gross_refund",
      "tax_rate": "0.00"
    },
    {
      "amount": 36,
      "name": "返金による手数料返還",
      "subject": "refund_fee_offset",
      "tax_rate": "0.00"
    },
    {
      "amount": -775,
      "name": "チャージバック",
      "subject": "chargeback",
      "tax_rate": "0.00"
    },
    {
      "amount": 25,
      "name": "チャージバックによる手数料返還",
      "subject": "chargeback_fee_offset",
      "tax_rate": "0.00"
    }
  ],
  "livemode": true,
  "object": "statement",
  "title": null,
  "tenant_id": null,
  "updated": 1695892351,
  "type":"sales",
  "net": 536
}

プロパティ


object String

"statement"の固定文字列


id String

オブジェクトのユニークID


livemode Boolean

livemodeオブジェクトならtrue


created Integer

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


title String

取引明細のタイトル


tenant_id String

オブジェクトを所有するTenantのID


type String

取引明細の区分

区分 詳細
sales 売上 決済による売上、決済手数料等
service_fee サービス利用料 有料プランの月額費用など、salesに含まれないサービス利用料
forfeit 残高失効 -
transfer_fee 振込手数料 -
misc その他 調整金など

net Integer

含まれるstatement_itemの金額合計


updated Integer

更新時刻のUTCタイムスタンプ


term Object

入金管理オブジェクトの刷新に伴い、2024/06/01以降に提供されます。

このStatementの生成元となったTermオブジェクト プロプラン料金や各種手数料など、Termから作られていないものではnullになります。


balance_id String

入金管理オブジェクトの刷新に伴い、2024/06/01以降に提供されます。

このStatementが関連付けられているBalanceのID


items list[statement_item]

statement_itemオブジェクト のリスト

statement_itemオブジェクト

{
  "amount": 3125,
  "name": "売上",
  "subject": "gross_sales",
  "tax_rate": "0.00"
}

プロパティ

subject String

集計項目

項目名 集計対象
gross_sales 支払確定された金額
fee gross_salesに対する決済手数料
platform_fee gross_salesに対するプラットフォーム利用料
gross_refund 返金
refund_fee_offset 返金による手数料返還
refund_platform_fee_offset 返金によるプラットフォーム利用料返還
chargeback チャージバック確定額
chargeback_fee_offset チャージバックによる手数料返還
chargeback_platform_fee_offset チャージバックによるプラットフォーム利用料返還
proplan 旧料金体系におけるプロプラン利用料
plan_fee 有料プラン利用料
forfeit 残高失効
reallocation テナントの残高失効による加算
transfer_fee 振込手数料
other その他

name String

Subjectに対応する表示名

amount Integer

集計された金額

正の値は加盟店への支払額、負の値は請求額を表します。

tax_rate String

税率(パーセント表記)。小数点以下2桁までの数値の文字列型。

statementイベント

statement.created

取引明細の作成

取引明細を取得

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

curl https:/api.pay.jp/v1/statements/st_178fd25dc7ab7b75906f5d4c4b0e6 \
-u sk_test_c62fade9d045b54cd76d7036
payjp.Statement.retrieve('st_178fd25dc7ab7b75906f5d4c4b0e6')
Payjp::Statement.retrieve('st_178fd25dc7ab7b75906f5d4c4b0e6')
\Payjp\Statement::retrieve("st_178fd25dc7ab7b75906f5d4c4b0e6");
payjp.statements.retrieve('st_178fd25dc7ab7b75906f5d4c4b0e6');
Statement.retrieve("st_178fd25dc7ab7b75906f5d4c4b0e6");
statement, err := pay.Statement.Retrieve("st_178fd25dc7ab7b75906f5d4c4b0e6")

レスポンス

{
  "created": 1695892351,
  "id": "st_178fd25dc7ab7b75906f5d4c4b0e6",
  "items": [
    {
      "amount": 3125,
      "name": "売上",
      "subject": "gross_sales",
      "tax_rate": "0.00"
    },
    {
      "amount": -75,
      "name": "決済手数料",
      "subject": "fee",
      "tax_rate": "0.00"
    },
    {
      "amount": -1800,
      "name": "返金",
      "subject": "gross_refund",
      "tax_rate": "0.00"
    },
    {
      "amount": 36,
      "name": "返金による手数料返還",
      "subject": "refund_fee_offset",
      "tax_rate": "0.00"
    },
    {
      "amount": -775,
      "name": "チャージバック",
      "subject": "chargeback",
      "tax_rate": "0.00"
    },
    {
      "amount": 25,
      "name": "チャージバックによる手数料返還",
      "subject": "chargeback_fee_offset",
      "tax_rate": "0.00"
    }
  ],
  "object": "statement",
  "livemode": true,
  "tenant_id": null,
  "title": null,
  "type": "sales",
  "updated": 1695892351,
  "net": 536
}

エラーレスポンス

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

取引明細を取得します。

引数

なし

レスポンス

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

取引明細ダウンロードURLを発行

POST https://api.pay.jp/v1/statements/:id/statement_urls

curl -X POST https:/api.pay.jp/v1/statements/st_178fd25dc7ab7b75906f5d4c4b0e6/statement_urls \
-u sk_test_c62fade9d045b54cd76d7036:
statement = payjp.Statement.retrieve('st_178fd25dc7ab7b75906f5d4c4b0e6')
url = statement.statement_urls(platformer=True)
Payjp::Statement.statement_urls('st_178fd25dc7ab7b75906f5d4c4b0e6')
url = \Payjp\Statement::retrieve("st_178fd25dc7ab7b75906f5d4c4b0e6")->statementUrls->create();
payjp.statements.statementUrls('st_178fd25dc7ab7b75906f5d4c4b0e6', {})
Statement st = Statement.retrieve("st_178fd25dc7ab7b75906f5d4c4b0e6");
Map<String, Object> params = new HashMap<String, Object>();
params.put("platformer", true);
StatementUrl url = st.statementUrls(params);
url.getUrl();
statement, err = pay.Statement.Retrieve("st_178fd25dc7ab7b75906f5d4c4b0e6")
url, err := statement.StatementUrls(payjp.StatementUrls{
    Platformer: payjp.Bool(true),
})

レスポンス

{
  "expires": 1695903280,
  "object": "statement_url",
  "url": "https://pay.jp/_/statements/bd84d2d680b84a10b0fb11eb79789205"
}

エラーレスポンス

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

取引明細およびインボイスをダウンロードできる一時URLを発行します。

発行されたURLにアクセスすると、取引明細・インボイスが表示されます。

主にPAY.JPプラットフォームにおけるTenantに対して取引明細・インボイスを提示するために利用できます。

URLは以下のいずれかの条件で失効します。

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

対応する取引明細が存在しない場合は404エラーが返却されます。

引数

platformer Boolean

trueを指定するとプラットフォーム手数料に関する明細がダウンロードできるURLを発行します。

この場合はPAY.JPが発行者である取引報告書・インボイスは表示されません。

デフォルトはfalseです。

レスポンス


object String

固定値 "statement_url"


url String

取引明細書ダウンロードURL


expires Integer

有効期限のタイムスタンプ。

有効期限は発行から1時間です。

取引明細リストを取得

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

curl https:/api.pay.jp/v1/statements \
-u sk_test_c62fade9d045b54cd76d7036:
payjp.Statement.all(tanant='test')
Payjp::Statement.all(owner: 'merchant')
\Payjp\Statement::all(array("limit" => 3));
payjp.statements.list()
Map<String, Object> params = new HashMap<String, Object>();
listParams.put("limit", 3);
Statement.all(listParams);
params := &payjp.StatementListParams{
    ListParams: payjp.ListParams{
        Limit: payjp.Int(1),
    },
    Owner:          payjp.String("tenant"),
    SourceTransfer: payjp.String("ten_tr_xxx"),
    Tenant:         payjp.String("test"),
}
statements, hasMore, err := pay.Statement.All(params)

レスポンス

{
  "count": 2,
  "data": [
    {
      "created": 1695892351,
      "id": "st_178fd25dc7ab7b75906f5d4c4b0e6",
      "items": [
        {
          "amount": 25,
          "name": "チャージバックによる手数料返還",
          "subject": "chargeback_fee_offset",
          "tax_rate": "0.00"
        },
        {
          "amount": -775,
          "name": "チャージバック",
          "subject": "chargeback",
          "tax_rate": "0.00"
        },
        {
          "amount": 36,
          "name": "返金による手数料返還",
          "subject": "refund_fee_offset",
          "tax_rate": "0.00"
        },
        {
          "amount": -1800,
          "name": "返金",
          "subject": "gross_refund",
          "tax_rate": "0.00"
        },
        {
          "amount": -75,
          "name": "決済手数料",
          "subject": "fee",
          "tax_rate": "0.00"
        },
        {
          "amount": 3125,
          "name": "売上",
          "subject": "gross_sales",
          "tax_rate": "0.00"
        }
      ],
      "object": "statement",
      "livemode": true,
      "tenant_id": null,
      "title": null,
      "type": "sales",
      "updated": 1695892351,
      "net": 536
    },
    {
      "created": 1695892350,
      "id": "st_b4a569b0122a7d08b298f198cf263",
      "items": [
        {
          "amount": -10000,
          "name": "プロプラン利用料",
          "subject": "proplan",
          "tax_rate": "10.00"
        }
      ],
      "object": "statement",
      "livemode": true,
      "title": "プロプラン月額料金",
      "updated": 1695892350,
      "type": "sales",
      "tenant_id": null,
      "net": -10000
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/statements"
}

エラーレスポンス

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

取引明細リストを取得します。

引数


limit Integer

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


offset Integer

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


since Integer

タイムスタンプ

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


until Integer

タイムスタンプ

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


owner String

取引明細の発行対象で絞り込みます。以下の値が指定できます。

owner 絞り込み対象
merchant 加盟店に向けて発行されたもの
tenant テナントに向けて発行されたもの

source_transfer String

取引明細の生成元オブジェクトで絞り込みます。

transferオブジェクト もしくは tenant_transferオブジェクトのIDを指定します。

tenant String

テナントのIDで絞り込みます。

term String

集計区間のIDで絞り込みます。

type String

typeの値で絞り込みます。

レスポンス

statementオブジェクトlistオブジェクト

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

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

subscriptionイベント

subscription.created

定期課金の作成

subscription.updated

定期課金の更新

subscription.deleted

定期課金の削除

subscription.paused

定期課金の停止

subscription.resumed

定期課金の再開

subscription.canceled

定期課金のキャンセル

subscription.renewed

定期課金の期間更新

定期課金を作成

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"
        )
);
const 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);
subscription, err := pay.Subscription.Subscribe("cus_xxx", payjp.Subscription{
    PlanID:  "pln_yyy",
    Prorate: true,
})

レスポンス

{
  "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

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

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

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

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

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

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


prorate Boolean

デフォルトはfalse

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

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

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

明示的にfalseと指定し、かつ引数trial_endも指定した場合、課金日(billing_day)が指定されているならば、 トライアル期間の終了日は次の課金日の日本時間午前9:00に自動調整されます。


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");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.retrieve('sub_567a1e44562932ec1a7682d746e0');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");
subscription, err := pay.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();
const 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);
subscription, err := pay.Subscription.Update("sub_567a1e44562932ec1a7682d746e0", payjp.Subscription{
    PlanID:          "pln_xxx",
    NextCyclePlanID: "next_plan",
})
// or
err = subscription.Update(payjp.Subscription{
    NextCyclePlanID: "",
    Prorate:         "true",
})

レスポンス

{
  "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 or String

リクエスト時より未来のタイムスタンプ(5年後まで) 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を指定することで、次回サイクル更新時に指定のプランへと自動的に切り替えを行い課金を試みます。

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

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

指定したプランの課金日(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();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.pause('sub_567a1e44562932ec1a7682d746e0');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription su = Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");
su.pause();
subscription, err := pay.Subscription.Pause("sub_567a1e44562932ec1a7682d746e0")
// or
err = subscription.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();
const 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();
subscription, err := pay.Subscription.Resume("sub_567a1e44562932ec1a7682d746e0", payjp.Subscription{
    TrialEndAt: time.Now().AddDate(1, 0, 0),
})
// or
err = subscription.Resume(payjp.Subscription{})

レスポンス

{
  "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 or String

リクエスト時より未来のタイムスタンプ(5年後まで) or 文字列 now が指定可能です。 この引数を指定した場合、プランのトライアル日数(trial_days)は無視されます。

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

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

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

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


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();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.subscriptions.cancel('sub_567a1e44562932ec1a7682d746e0');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Subscription su = Subscription.retrieve("sub_567a1e44562932ec1a7682d746e0");
su.cancel();
subscription, err := pay.Subscription.Cancel("sub_567a1e44562932ec1a7682d746e0")
// or
err = subscription.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();
const 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();
err := pay.Subscription.Delete("sub_567a1e44562932ec1a7682d746e0", payjp.SubscriptionDelete{
    Prorate: payjp.Bool(false),
})
// or
err = subscription.Delete(payjp.SubscriptionDelete{
    Prorate: payjp.Bool(true),
})

レスポンス

{
  "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));
const 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);
status := payjp.SubscriptionActive
params := &payjp.SubscriptionListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(1),
        Offset: payjp.Int(0),
    },
    Plan:     payjp.String("pln_xxx"),
    Status:   &status,
    Customer: payjp.String("cus_xxx"),
}
subscriptions, hasMore, err = pay.Subscription.All(params)

レスポンス

{
  "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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": "verified",
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "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オブジェクト

tokenイベント

token.created

トークンの作成

トークンを作成

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"
-d "card[email]=liveaccount@example.com"
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);
p := Token{
    Number:   "4242424242424242",
    ExpMonth: "2",
    ExpYear:  "2020",
    CVC: "123",
}
p.Name = "pay taro"
token, err = pay.Token.Create(p)

レスポンス

{
  "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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": "verified",
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "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[name] String

カード保有者名(e.g. "PAY TARO")

45文字以下の半角英数字、スペース ピリオド ハイフンのみに形式の変更を予定しております。
詳細はこちら

2024年8月以降、3Dセキュア認証の際にデータ入力が求められます。
詳細はこちら


card[email] String

メールアドレス

2024年8月以降、3Dセキュア認証の際にphoneまたはemailのデータ入力が求められます。
詳細はこちら


card[phone] String

E.164形式の電話番号 (e.g. 090-0123-4567(日本) => "+819001234567")

2024年8月以降、3Dセキュア認証の際にphoneまたはemailのデータ入力が求められます。
詳細はこちら


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)


tenant String

テナントID

Marketplace 型 Platform をご利用の方のみ指定可能です。
任意ですが指定を強く推奨します。指定が必要な理由についてはトークン作成時のテナント ID についてをご参照ください。


three_d_secure Boolean

3Dセキュアを開始するかどうか

管理画面でトークン3Dセキュアを実施するモードが有効になっている時は無視されます。

トークン情報を取得

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");
token, err := pay.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": "PAY TARO",
    "object": "card",
    "three_d_secure_status": "verified",
    "email": "liveaccount@example.com",
    "phone": "+81301234567"
  },
  "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",
          "three_d_secure_status": null
        },
        "created": 1441706750,
        "currency": "jpy",
        "customer": "cus_b92b879e60f62b532d6756ae12af",
        "description": null,
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "fee_rate": "3.00",
        "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,
    "dispute_amount": 0,
    "dispute_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 合計金額が最低入金額に満たず、次回入金に繰り越している状態
recombination 入金に失敗し、次回入金時に組み戻し手数料が発生する状態

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


charges Object

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


scheduled_date Date

入金予定日。日本時間(JST)で表記


summary Object

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

キー 値の型 値の説明
charge_count Integer 支払い総回数
charge_fee Integer 支払い手数料
charge_gross Integer 総売上
net Integer 差引額
refund_amount Integer 返金総額
refund_count Integer 返金総数
dispute_amount Integer チャージバックにより相殺された金額の合計
dispute_count Integer チャージバック対象となったchargeの個数
total_platform_fee Integer PAY.JP Platform のTenant Transferオブジェクトのみ。 プラットフォーム支払い手数料

description String

概要


term_start Integer

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


term_end Integer

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


transfer_amount Integer

入金額


transfer_date Date

入金日。日本時間(JST)で表記


carried_balance Integer

繰越金

transferイベント

transfer.succeeded

入金内容の確定

入金情報を取得

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");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.transfers.retrieve('tr_8f0c0fe2c9f8a47f9d18f03959ba1');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Transfer.retrieve("tr_8f0c0fe2c9f8a47f9d18f03959ba1");
transfer, err := pay.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",
          "three_d_secure_status": null
        },
        "created": 1441706750,
        "currency": "jpy",
        "customer": "cus_b92b879e60f62b532d6756ae12af",
        "description": null,
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "fee_rate": "3.00",
        "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,
    "dispute_amount": 0,
    "dispute_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();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.transfers.list({limit: 1});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Transfer.all();
status := payjp.TransferPending
params := &payjp.TransferListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(10),
        Offset: payjp.Int(15),
    },
    SinceSheduledDate: payjp.Int(1455500895),
    Status: &status,
}
data, hasMore, err = transfer.All(params)

レスポンス

{
  "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",
              "three_d_secure_status": null
            },
            "created": 1441706750,
            "currency": "jpy",
            "customer": "cus_b92b879e60f62b532d6756ae12af",
            "description": null,
            "expired_at": null,
            "failure_code": null,
            "failure_message": null,
            "fee_rate": "3.00",
            "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,
        "dispute_amount": 0,
        "dispute_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

タイムスタンプ

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


since_scheduled_date Integer

タイムスタンプ

入金予定日が指定したタイムスタンプ以降のデータのみ取得


until_scheduled_date 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));
const 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);
transfer, err := pay.Transfer.Retrieve("tr_8f0c0fe2c9f8a47f9d18f03959ba1")
params := &payjp.TransferChargeListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(10),
    },
    Customer: payjp.String("cus_xxx"),
}
data, hasMore, err = transfer.All(params)

レスポンス

{
  "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",
        "three_d_secure_status": null
      },
      "created": 1441706750,
      "currency": "jpy",
      "customer": "cus_b92b879e60f62b532d6756ae12af",
      "description": null,
      "expired_at": null,
      "failure_code": null,
      "failure_message": null,
      "fee_rate": "3.00",
      "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オブジェクト

Term(集計区間)

入金管理オブジェクトの刷新に伴い、2024/06/01以降に提供されます。

取引の集計区間を示すオブジェクトです。 支払い、返金、確定したチャージバックは、それぞれの確定日に対応するTermオブジェクトに関連付けられます。

termオブジェクト

termオブジェクト

{
  "charge_count": 5,
  "dispute_count": 0,
  "end_at": 1698764400,
  "id": "tm_425000e2a448b39b83480a358fee5",
  "livemode": false,
  "closed": false,
  "object": "term",
  "refund_count": 0,
  "start_at": 1696086000
}

プロパティ


object String

"term"の固定文字列


id String

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


livemode Boolean

本番環境かどうか


start_at Integer

区間開始時刻のタイムスタンプ


end_at Integer

区間終了時刻のタイムスタンプ

Termが表す区間はstart_at 以上 end_at 未満 の範囲となります。

翌サイクルのTermの場合nullを返します。


closed Boolean

締め処理が完了済みならTrue


charge_count Integer

この区間内で確定された支払いの数


refund_count Integer

この区間内で確定された返金の数


dispute_count Integer

この区間内で確定されたチャージバック/チャージバックキャンセルの数

termイベント

term.created

新しい区間が作られた

term.closed

区間の売上集計処理が完了した

集計区間オブジェクトを取得

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

curl https://api.pay.jp/v1/terms/tm_b92b879e60f62b532d6756ae12af \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Term.retrieve('tm_b92b879e60f62b532d6756ae12af')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Term.retrieve('tm_b92b879e60f62b532d6756ae12af')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Term::retrieve("tm_b92b879e60f62b532d6756ae12af");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.terms.retrieve('tm_b92b879e60f62b532d6756ae12af');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Term tr = Term.retrieve("tm_b92b879e60f62b532d6756ae12af");
term, err := pay.Term.Retrieve("tm_b92b879e60f62b532d6756ae12af")

レスポンス

{
  "id": "tm_b92b879e60f62b532d6756ae12af",
  "livemode": false,
  "object": "term",
  "charge_count": 158,
  "closed": false,
  "refund_count": 25,
  "dispute_count": 2,
  "end_at": 1439650800,
  "start_at": 1438354800
}

エラーレスポンス

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

指定されたIDの集計区間オブジェクトを取得します。

引数

なし

レスポンス

termオブジェクト

集計区間のリストを取得

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

curl 'https://api.pay.jp/v1/terms?limit=10&offset=0&since_start_at=1709218800&until_start_at=1714489200' \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Term.all(limit=10, offset=0, since_start_at=1709218800, until_start_at=1714489200)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Term.all(limit: 10, offset: 0, since_start_at: 1709218800, until_start_at: 1714489200)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Term::all(array("limit" => 10, "offset" => 0, "since_start_at" => 1709218800, "until_start_at" => 1714489200));
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.terms.list({
  limit: 10,
  offset: 0,
  since_start_at: 1709218800,
  until_start_at: 1714489200
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> termParams = new HashMap<String, Object>();
termParams.put("limit", 10);
termParams.put("offset", 0);
termParams.put("since_start_at", 1709218800);
termParams.put("until_start_at", 1714489200);
TermCollection trc = Term.all(termParams);
limit :=  Int(10)
offset := Int(0)
params := &TermListParams{
    Limit: limit,
    Offset: offset,
    SinceStartAt: Int(1709218800),
    UntilStartAt: Int(1714489200),
}
res, hasMore, err := service.Term.All(params)

レスポンス

{
  "count": 2,
  "data": [
    {
      "charge_count": 0,
      "closed": false,
      "dispute_count": 0,
      "end_at": 1714489200,
      "id": "tm_cfb51c48190234dd69e49d58e6436",
      "livemode": false,
      "object": "term",
      "refund_count": 0,
      "start_at": 1711897200
    },
    {
      "charge_count": 5,
      "closed": true,
      "dispute_count": 0,
      "end_at": 1711897200,
      "id": "tm_7c9a90e3943a3417c086d15a60f55",
      "livemode": false,
      "object": "term",
      "refund_count": 0,
      "start_at": 1709218800
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/terms"
}

エラーレスポンス

{
  "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_start_at Integer

start_atが指定したタイムスタンプ以降であるオブジェクトを取得


until_start_at Integer

start_atが指定したタイムスタンプ以前であるオブジェクトを取得

レスポンス

termオブジェクトlistオブジェクト

Balance (残高)

入金管理オブジェクトの刷新に伴い、2024/06/01以降に提供されます。

PAY.JP内で発生した売上および請求の残高を表すオブジェクトです。

balanceオブジェクト

balanceオブジェクト

{
  "bank_info": {
    "bank_account_holder_name": "テスト フリコミ",
    "bank_account_number": "0000001",
    "bank_account_status": "success",
    "bank_account_type": "普通",
    "bank_branch_code": "000",
    "bank_code": "0000"
  },
  "closed": true,
  "created": 1706713200,
  "due_date": 1711897200,
  "id": "ba_013f3c308b771358605dd2445d60f",
  "livemode": false,
  "net": 14549999850,
  "object": "balance",
  "state": "transfer",
  "statements": [
    {
      "balance_id": "ba_013f3c308b771358605dd2445d60f",
      "created": 1709218801,
      "id": "st_be6b875435edcceb598aca31edd49",
      "items": [
        {
          "amount": -150,
          "name": "振込手数料",
          "subject": "transfer_fee",
          "tax_rate": "10.00"
        }
      ],
      "livemode": false,
      "net": -150,
      "object": "statement",
      "tenant_id": null,
      "term": null,
      "title": null,
      "updated": 1712430084,
      "type":"transfer_fee"
    },
    {
      "balance_id": "ba_013f3c308b771358605dd2445d60f",
      "created": 1709218800,
      "id": "st_1ad88786c727816ecd41609b6a5a1",
      "items": [
        {
          "amount": 15000000000,
          "name": "売上",
          "subject": "gross_sales",
          "tax_rate": "0.00"
        },
        {
          "amount": -450000000,
          "name": "決済手数料",
          "subject": "fee",
          "tax_rate": "0.00"
        }
      ],
      "livemode": false,
      "net": 14550000000,
      "object": "statement",
      "tenant_id": null,
      "term": {
        "charge_count": 15,
        "dispute_count": 0,
        "end_at": 1709218800,
        "id": "tm_523e1651f76f4f15b61cc66306f37",
        "livemode": false,
        "object": "term",
        "refund_count": 0,
        "start_at": 1706713200
      },
      "title": null,
      "updated": 1712430084,
      "type":"sales"
    }
  ],
  "tenant_id": null
}

プロパティ


object String

"balance"の固定文字列


id String

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


livemode Boolean

本番環境かどうか


created Integer

オブジェクト作成時刻のUTCタイムスタンプ


tenant_id String

オブジェクトを所有するTenantのID


net Integer

関連付けられているStatementの総額


statements list[statement]

関連付けられているstatementオブジェクトのリスト


state String

Balanceの状態

collecting 集計中
transfer 入金
claim 請求

closed Boolean

このBalanceの清算が終了していればtrue

state=transferであれば加盟店口座への入金作業完了、state=claimであればPAY.JPで請求額の振込が確認できたことを表します。


closed_date Integer

精算が終了した日時のタイムスタンプ

state=transferであれば着金予定日、state=claimであれば振込が確認できた日時を表します。


due_date Integer

入金予定日/請求期限日のタイムスタンプ

state=transferであれば入金予定日、state=claimであれば請求の期限日を表します。


bank_info Object

入金先口座情報 bank_infoオブジェクト

bank_infoオブジェクト

bank_infoオブジェクト

{
  "bank_code": "0000",
  "bank_branch_code": "123",
  "bank_account_type": "普通",
  "bank_account_number": "1234567",
  "bank_account_holder_name": "ペイ タロウ",
  "bank_account_status": "pending"
}

プロパティ

bank_code String

銀行コード


bank_branch_code String

支店番号


bank_account_type String

口座種別


bank_account_number String

口座番号


bank_account_holder_name String

口座名義


bank_account_status String

最新振込結果

status 内容
success 成功
failed 失敗
pending 初回振込み前

balanceイベント

balance.created

新しいBalanceが作られた

balance.fixed

Balance.stateがtransferもしくはclaimに確定された

balance.closed

入金もしくは請求処理が完了した

balance.merged

Balanceが別のBalanceにマージされた

残高を取得

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

curl https://api.pay.jp/v1/balances/ba_013f3c308b771358605dd2445d60f \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Balance.retrieve('ba_013f3c308b771358605dd2445d60f')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Balance.retrieve('ba_013f3c308b771358605dd2445d60f')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Balance::retrieve("ba_013f3c308b771358605dd2445d60f");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.balances.retrieve('ba_013f3c308b771358605dd2445d60f');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Balance bl = Balance.retrieve("ba_013f3c308b771358605dd2445d60f");
balance, err := pay.Balance.Retrieve("ba_013f3c308b771358605dd2445d60f")

レスポンス

{
  "bank_info": {
    "bank_account_holder_name": "テスト フリコミ",
    "bank_account_number": "0000001",
    "bank_account_status": "success",
    "bank_account_type": "普通",
    "bank_branch_code": "000",
    "bank_code": "0000"
  },
  "closed": true,
  "closed_date": 1711897200,
  "created": 1706713200,
  "due_date": 1711897200,
  "id": "ba_013f3c308b771358605dd2445d60f",
  "livemode": false,
  "net": 14400,
  "object": "balance",
  "state": "transfer",
  "statements": [
    {
      "balance_id": "ba_013f3c308b771358605dd2445d60f",
      "created": 1709218801,
      "id": "st_be6b875435edcceb598aca31edd49",
      "items": [
        {
          "amount": -150,
          "name": "振込手数料",
          "subject": "transfer_fee",
          "tax_rate": "10.00"
        }
      ],
      "livemode": false,
      "net": -150,
      "object": "statement",
      "tenant_id": null,
      "term": null,
      "title": null,
      "updated": 1712430084,
      "type":"transfer_fee"
    },
    {
      "balance_id": "ba_013f3c308b771358605dd2445d60f",
      "created": 1709218800,
      "id": "st_1ad88786c727816ecd41609b6a5a1",
      "items": [
        {
          "amount": 15000,
          "name": "売上",
          "subject": "gross_sales",
          "tax_rate": "0.00"
        },
        {
          "amount": -450,
          "name": "決済手数料",
          "subject": "fee",
          "tax_rate": "0.00"
        }
      ],
      "livemode": false,
      "net": 14550,
      "object": "statement",
      "tenant_id": null,
      "term": {
        "charge_count": 15,
        "dispute_count": 0,
        "end_at": 1709218800,
        "id": "tm_523e1651f76f4f15b61cc66306f37",
        "livemode": false,
        "object": "term",
        "refund_count": 0,
        "start_at": 1706713200
      },
      "title": null,
      "updated": 1712430084,
      "type":"sales"
    }
  ],
  "tenant_id": null
}

エラーレスポンス

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

特定の残高オブジェクトを取得します。

引数

なし

レスポンス

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

取引明細一括ダウンロードURLを発行

POST https://api.pay.jp/v1/balances/:id/statement_urls

curl -X POST https:/api.pay.jp/v1/balances/ba_acff063816a9622deacc90f3dd/statement_urls \
-u sk_test_c62fade9d045b54cd76d7036:
statement = payjp.Balance.retrieve('ba_acff063816a9622deacc90f3dd')
url = statement.statement_urls(platformer=False)
Payjp::Balance.statement_urls('ba_acff063816a9622deacc90f3dd')
url = \Payjp\Balance::retrieve("ba_acff063816a9622deacc90f3dd")->statementUrls->create();
payjp.balances.statementUrls('ba_acff063816a9622deacc90f3dd', {})
Balance ba = Balance.retrieve("ba_acff063816a9622deacc90f3dd");
Map<String, Object> params = new HashMap<String, Object>();
params.put("platformer", false);
StatementUrl url = ba.statementUrls(params);
url.getUrl();
balance, err = pay.Balance.Retrieve("ba_acff063816a9622deacc90f3dd")
url, err := balance.StatementUrls(payjp.StatementUrls{
    Platformer: payjp.Bool(false),
})

レスポンス

{
  "expires": 1695903280,
  "object": "statement_url",
  "url": "https://pay.jp/_/statements/bd84d2d680b84a10b0fb11eb79789205"
}

エラーレスポンス

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

Balanceに含まれるStatementすべての取引明細およびインボイスを一括ダウンロードできる一時URLを発行します。

発行されたURLにアクセスすると、含まれるStatementの取引明細・インボイスがすべて繋がった状態で表示されます。

その他のAPI仕様は取引明細ダウンロードURLを発行と同等です。

引数

platformer Boolean

trueを指定するとプラットフォーム手数料に関する明細がダウンロードできるURLを発行します。

この場合はPAY.JPが発行者である取引報告書・インボイスは表示されません。

デフォルトはfalseです。

レスポンス


object String

固定値 "statement_url"


url String

取引明細書ダウンロードURL


expires Integer

有効期限のタイムスタンプ。

有効期限は発行から1時間です。

残高リストを取得

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

curl 'https://api.pay.jp/v1/balances?since_due_date=1706713200&until_due_date=1709218800&state=collecting&closed=true&owner=tenant&tenant=ten_121673955bd7aa144de5a8f6c262' \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Balance.all(since_due_date=1706713200, until_due_date=1709218800, state='collecting', closed=true, owner='tenant', tenant='ten_121673955bd7aa144de5a8f6c262')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Balance.all(since_due_date: 1706713200, until_due_date: 1709218800, state: 'collecting', closed: true, owner: 'tenant', tenant: 'ten_121673955bd7aa144de5a8f6c262')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Balance::all(array("since_due_date" => 1706713200, "until_due_date" => 1709218800, "state" => "collecting", "closed" => true, "owner" => "tenant", tenant => "ten_121673955bd7aa144de5a8f6c262");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.balances.list({
  since_due_date: 1706713200,
  until_due_date: 1709218800,
  state: 'collecting',
  closed: true,
  owner: 'tenant',
  tenant: 'ten_121673955bd7aa144de5a8f6c262'
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> balanceParams = new HashMap<String, Object>();
balanceParams.put("since_due_date", 1706713200);
balanceParams.put("until_due_date", 1709218800);
balanceParams.put("state", "collecting");
balanceParams.put("closed", true);
balanceParams.put("owner", "tenant");
balanceParams.put("tenant", "ten_121673955bd7aa144de5a8f6c262");
BalanceCollection blc = Balance.all(balanceParams);
limit :=  Int(10)
params := &BalanceListParams{
    SinceDueDate: Int(1706713200),
    UntilDueDate: Int(1709218800),
    State:        String("collecting"),
    Closed:       Bool(true),
    Owner:        String("tenant"),
    Tenant:       String("ten_121673955bd7aa144de5a8f6c262"),
}
params.Limit = limit
res, hasMore, err := service.Balance.All(params)

レスポンス

{
  "count": 2,
  "data": [
    {
      "bank_info": null,
      "closed": false,
      "closed_date": null,
      "created": 1709218800,
      "due_date": null,
      "id": "ba_7e5d631c38b8e9cc33c9372b2f97a",
      "livemode": false,
      "net": 4850,
      "object": "balance",
      "state": "collecting",
      "statements": [
        {
          "balance_id": "ba_7e5d631c38b8e9cc33c9372b2f97a",
          "created": 1711897200,
          "id": "st_f671f9678e13bb84b01809d05caa3",
          "items": [
            {
              "amount": 5000,
              "name": "売上",
              "subject": "gross_sales",
              "tax_rate": "0.00"
            },
            {
              "amount": -150,
              "name": "決済手数料",
              "subject": "fee",
              "tax_rate": "0.00"
            }
          ],
          "livemode": false,
          "net": 4850,
          "object": "statement",
          "tenant_id": null,
          "term": {
            "charge_count": 5,
            "dispute_count": 0,
            "end_at": 1711897200,
            "id": "tm_be579c30e3563ff6b24e12bb9606f",
            "livemode": false,
            "object": "term",
            "refund_count": 0,
            "start_at": 1709218800
          },
          "title": null,
          "updated": 1712430084,
          "type":"sales"
        }
      ],
      "tenant_id": null
    },
    {
      "bank_info": {
        "bank_account_holder_name": "テスト フリコミ",
        "bank_account_number": "0000001",
        "bank_account_status": "success",
        "bank_account_type": "普通",
        "bank_branch_code": "000",
        "bank_code": "0000"
      },
      "closed": true,
      "closed_date": 1711897200,
      "created": 1706713200,
      "due_date": 1711897200,
      "id": "ba_013f3c308b771358605dd2445d60f",
      "livemode": false,
      "net": 14400,
      "object": "balance",
      "state": "transfer",
      "statements": [
        {
          "balance_id": "ba_013f3c308b771358605dd2445d60f",
          "created": 1709218801,
          "id": "st_be6b875435edcceb598aca31edd49",
          "items": [
            {
              "amount": -150,
              "name": "振込手数料",
              "subject": "transfer_fee",
              "tax_rate": "10.00"
            }
          ],
          "livemode": false,
          "net": -150,
          "object": "statement",
          "tenant_id": null,
          "term": null,
          "title": null,
          "updated": 1712430084,
          "type":"transfer_fee"
        },
        {
          "balance_id": "ba_013f3c308b771358605dd2445d60f",
          "created": 1709218800,
          "id": "st_1ad88786c727816ecd41609b6a5a1",
          "items": [
            {
              "amount": 15000,
              "name": "売上",
              "subject": "gross_sales",
              "tax_rate": "0.00"
            },
            {
              "amount": -450,
              "name": "決済手数料",
              "subject": "fee",
              "tax_rate": "0.00"
            }
          ],
          "livemode": false,
          "net": 14550,
          "object": "statement",
          "tenant_id": null,
          "term": {
            "charge_count": 15,
            "dispute_count": 0,
            "end_at": 1709218800,
            "id": "tm_523e1651f76f4f15b61cc66306f37",
            "livemode": false,
            "object": "term",
            "refund_count": 0,
            "start_at": 1706713200
          },
          "title": null,
          "updated": 1712430084,
          "type":"sales"
        }
      ],
      "tenant_id": null
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/balances"
}

エラーレスポンス

{
  "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

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


since_due_date Integer

入金予定日/振込期限日が指定したタイムスタンプ以降のデータのみ取得


until_due_date Integer

入金予定日/振込期限日が指定したタイムスタンプ以前のデータのみ取得


state String

stateが指定した値であるオブジェクトに限定


closed Boolean

closedが指定した値であるオブジェクトに限定


owner String

Balanceの所有者で絞り込みます。以下の値が指定できます。

owner 絞り込み対象
merchant 加盟店が所有者
tenant テナントが所有者

tenant String

指定したテナントが所有者であるオブジェクトに限定

レスポンス

balanceオブジェクト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");
event, err := pay.Event.Retrieve("evnt_54db4d63c7886256acdbc784ccf")
fmt.Println(event.ID) // evnt_54db4d63c7886256acdbc784ccf

// event.Dataの値はGetDataValue()を用いてアクセスします。
customerId, err := event.GetDataValue("id")
fmt.Println(customerId) // cus_a16c7b4df01168eb82557fe93de4
// 以下はcard IDの取得を試みていますが、count=0のためerrorが返却されます
cardId, err := event.GetDataValue("cards", "data", "0", "id")

// GetDataValue()は常にstring型が返却されます。 必要ならDataをご自身でパースください。
object, err := event.GetDataValue("object")
if err == nil && object == "customer" {
    var customer payjp.CustomerResponse // object=="token"ならTokenResponseとなります
    err = json.Unmarshal(event.Data, &customer)
    fmt.Println(customer.ID) // cus_a16c7b4df01168eb82557fe93de4
}
// 各リソースの削除時はDeleteResponseを使用できます。(基本的にはGetDataValue()で十分かと思います)
deleted, err := event.GetDataValue("deleted")
if err == nil && deleted == "true" {
    var delete payjp.DeleteResponse
    err = json.Unmarshal(event.Data, &delete)
    fmt.Println(delete.ID) // cus_a16c7b4df01168eb82557fe93de4
}

レスポンス

{
  "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}})
params := &payjp.EventListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(10),
        Offset: payjp.Int(0),
    },
    Type:       payjp.String("a"),
    ResourceID: payjp.String("b"),
    Object:     payjp.String("c"),
}
events, hasMore, err = pay.Event.All(params)

レスポンス

{
  "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": "PAY TARO",
          "object": "card",
          "three_d_secure_status": null,
          "email": "liveaccount@example.com",
          "phone": "+81301234567"
        },
        "created": 1442212986,
        "currency": "jpy",
        "customer": null,
        "description": "hogehoe",
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "fee_rate": "3.00",
        "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 (プロダクト)

【再掲】productオブジェクトの提供終了についてのご案内 | PAY.JP

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

支払いを作成する時に、金額と通貨の代わりにプロダクトを指定することができます。
作成された支払いの金額、通貨、メタデータ、確定するかどうかは元となったプロダクトのものが入ります。
メタデータ、確定するかどうかは支払い作成時に上書きが可能です。

productオブジェクト

productオブジェクト

{
  "amount": 350,
  "capture": true,
  "created": 1498268809,
  "currency": "jpy",
  "id": "prd_24790edf42fb15c3eb72af2c7e6a",
  "invalid_after": null,
  "livemode": false,
  "metadata": {},
  "object": "product"
}

プロパティ


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 Object

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

プロダクトを作成

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"
}

エラーレスポンス

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

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

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

引数


amount Integer 必須

50~9,999,999の整数


currency String 必須

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


invalid_after Integer

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


capture Boolean

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


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"
}

エラーレスポンス

{
  "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"
}

エラーレスポンス

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

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

引数


invalid_after Integer

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


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"
    },
    {...},
    {...}
  ],
  "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オブジェクト

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

ThreeDSecureRequest (3Dセキュアリクエスト)

3Dセキュア認証を行う際に生成されるオブジェクトです。

このオブジェクトを3-Dセキュア開始エンドポイントに渡すことで3Dセキュア認証が開始されます。
オブジェクトには有効期限があり、作成から30分で期限切れとなり、それ以上の操作ができなくなります。

NOTE: 支払い作成時の3Dセキュアとトークン作成時の3Dセキュアでもこのオブジェクトが暗黙的に作られます。
しかしながら、本APIで3Dセキュアリクエストを作成する際に指定できるリソースは現状Cardのみとなっています。

支払い作成時の3Dセキュアとトークン作成時の3Dセキュアについては下記ドキュメントをご参照ください。

three_d_secure_requestオブジェクト

three_d_secure_requestオブジェクト

{
  "created": 1730084767,
  "expired_at": null,
  "finished_at": null,
  "id": "tdsr_125192559c91c4011c1ff56f50a",
  "livemode": true,
  "object": "three_d_secure_request",
  "resource_id": "car_4ec110e0700daf893160424fe03c",
  "result_received_at": null,
  "started_at": null,
  "state": "created",
  "tenant_id": null,
  "three_d_secure_status": "unverified"
}

プロパティ


id String

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


resource_id String

3Dセキュア処理対象リソースのID


object String

"three_d_secure_request"の固定文字列


livemode Boolean

本番環境かどうか


created Integer

3Dセキュアリクエスト作成時のUTCタイムスタンプ


state String

3Dセキュア認証の現在の状態

state 意味
created 3Dセキュアオブジェクトが作成された
in_progress 3Dセキュア認証中
result_received 3Dセキュア認証結果取得済み
finished 完了

started_at Integer

カード会社画面での認証開始時のUTCタイムスタンプ

初期値はnullとなります。


result_received_at Integer

カード会社画面での認証終了時のUTCタイムスタンプ

初期値はnullとなります。


finished_at Integer

カード会社画面での認証が終了し、対応するオブジェクトの3Dセキュア完了処理が実行された時のUTCタイムスタンプ。

初期値はnullで、顧客カードに対する3Dセキュアにおいては result_received_at と同じ値となります。


expired_at Integer

3Dセキュアリクエストが期限切れとなった時刻のUTCタイムスタンプ

初期値はnullで、期限切れまでに3Dセキュア完了処理を終えられなかった場合、期限切れとなった時刻が設定されます。


tenant_id String

テナントID


three_d_secure_status String

3Dセキュアの認証結果

値についてはcharge.three_d_secure_statusに同じ


3Dセキュアリクエストを作成

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

curl https://api.pay.jp/v1/three_d_secure_requests \
-u sk_test_c62fade9d045b54cd76d7036: \
-d resource_id=car_xxxxxx
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
threeDSecureRequest = payjp.ThreeDSecureRequest.create(resource_id='car_xxxxxx')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
threeDSecureRequest = Payjp::ThreeDSecureRequest.create(:resource_id => 'car_xxxxxx')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\ThreeDSecureRequest::create(array("resource_id" => "car_xxxxxx"));
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.threeDSecureRequests.create({resource_id: 'car_xxxxxx'});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> threeDSecureRequestParams = new HashMap<String, Object>();
threeDSecureRequestParams.put("resource_id", "car_xxxxxx");
ThreeDSecureRequest.create(threeDSecureRequestParams);
threeDSecureRequest, err := pay.ThreeDSecureRequest.Create(3500, payjp.ThreeDSecureRequest{ResourceID: "car_xxxxxx"})

レスポンス

{
  "created": 1730084767,
  "expired_at": null,
  "finished_at": null,
  "id": "tdsr_125192559c91c4011c1ff56f50a",
  "livemode": true,
  "object": "three_d_secure_request",
  "resource_id": "car_4ec110e0700daf893160424fe03c",
  "result_received_at": null,
  "started_at": null,
  "state": "created",
  "tenant_id": null,
  "three_d_secure_status": "unverified"
}

エラーレスポンス

{
  "error": {
    "code": "invalid_id",
    "message": "No such card: car_xxxxxx",
    "param": "resource_id",
    "status": 400,
    "type": "client_error"
  }
}

顧客カードIDを指定して3Dセキュアリクエストを作成します。

引数


resource_id String 必須

顧客カードID


tenant_id String

PAY.JP Platform のみ設定可能

テナントID

レスポンス

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

3Dセキュアリクエスト情報を取得

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

curl https://api.pay.jp/v1/three_d_secure_requests/tdsr_ed15fa4e2a6300d5971b1b69b827 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.ThreeDSecureRequest.retrieve('tdsr_ed15fa4e2a6300d5971b1b69b827')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::ThreeDSecureRequest.retrieve('tdsr_ed15fa4e2a6300d5971b1b69b827')
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\ThreeDSecureRequest::retrieve("tdsr_ed15fa4e2a6300d5971b1b69b827");
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.threeDSecureRequests.retrieve('tdsr_ed15fa4e2a6300d5971b1b69b827');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
ThreeDSecureRequest.retrieve("tdsr_ed15fa4e2a6300d5971b1b69b827");
threeDSecureRequest, err := pay.ThreeDSecureRequest.Retrieve("tdsr_ed15fa4e2a6300d5971b1b69b827")

レスポンス

{
  "created": 1730084767,
  "expired_at": null,
  "finished_at": null,
  "id": "tdsr_125192559c91c4011c1ff56f50a",
  "livemode": true,
  "object": "three_d_secure_request",
  "resource_id": "car_4ec110e0700daf893160424fe03c",
  "result_received_at": null,
  "started_at": null,
  "state": "created",
  "tenant_id": null,
  "three_d_secure_status": "unverified"
}

エラーレスポンス

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

3Dセキュアリクエスト情報を取得します。

引数

なし

レスポンス

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

3Dセキュアリクエストリストを取得

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

curl https://api.pay.jp/v1/three_d_secure_requests/tdsr_ed15fa4e2a6300d5971b1b69b827 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.ThreeDSecureRequest.all(limit=3, offset=10)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::ThreeDSecureRequest.all(limit: 3, offset: 10)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\ThreeDSecureRequest::all(array("limit" => 3, "offset" => 10));
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.threeDSecureRequests.list({
  limit: 3,
  offset: 10
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> threeDSecureRequestParams = new HashMap<String, Object>();
threeDSecureRequestParams.put("limit", 3);
threeDSecureRequestParams.put("offset", 10);
ThreeDSecureRequest.all(threeDSecureRequestParams);
params := &payjp.ThreeDSecureRequestListParams{
    ListParams: payjp.ListParams{
        Limit:  payjp.Int(10),
        Offset: payjp.Int(0),
    },
}
threeDSecureRequests, hasMore, err = pay.ThreeDSecureRequest.All(params)

レスポンス

{
  "count": 1,
  "data": [
    {
      "result_received_at": 1728546515,
      "created": 1728546061,
      "finished_at": null,
      "state": "result_received",
      "id": "tdsr_ed15fa4e2a6300d5971b1b69b827",
      "livemode": true,
      "object": "three_d_secure_request",
      "resource_id": "car_a309d8184e2dec6840291d8896a1",
      "started_at": 1728546132,
      "tenant_id": null,
      "three_d_secure_status": "verified"
    }
  ],
  "has_more": false,
  "object": "list",
  "url": "/v1/three_d_secure_requests"
}

エラーレスポンス

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

3Dセキュアリクエスト情報のリストを取得します。

引数


limit Integer

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


offset Integer

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


since Integer

タイムスタンプ

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


until Integer

タイムスタンプ

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


resource_id String

3Dセキュア処理対象リソースのID


tenant_id String

テナントID

レスポンス

three_d_secure_requestオブジェクト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",
  "team_id": null
}

プロパティ


object String

"account"の固定文字列


id String

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


email String

メールアドレス


created Integer

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


merchant Object

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


team_id String

このアカウントに紐付くチームID

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();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.accounts.retrieve();
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Account.retrieve();
account, err := pay.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",
  "team_id": null
}

エラーレスポンス

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

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

引数

なし

レスポンス

accountオブジェクト

3-DSecure

3Dセキュア開始

3Dセキュア認証画面をエンドユーザーに表示します。 このエンドポイントはJSONではなくエンドユーザーが直接アクセスしウェブページを表示するもので、SDK、または加盟店サーバーからのアクセスは想定されていません。 詳しいご利用方法は下記チュートリアルをご参照ください。

支払いで3Dセキュアを実施する

認証

認証/モードの指定はクエリパラメータの publickey によって行います。

終了時の戻り先URL指定

リダイレクト型3Dセキュアにおける認証終了時、およびエラー時の戻り先URLの指定にはbackback_url引数を使用します。 これらはいずれも任意パラメータですが、指定しなかった場合はサブウィンドウ型3Dセキュアとみなされ、完了時/エラー時にウィンドウを閉じる旨が表示されます。 そのため、リダイレクト型でのご利用の場合はどちらかのパラメータは事実上必須となります。

back

管理画面から事前に登録しておいたURLにリダイレクトします。URLそのものではなく、登録時に指定した識別子を指定します。 簡易に実装できるのが利点ですが、事前登録のため動的に戻り先URLを決定したい場合には不向きです。 また、モバイルSDKのトークン3Dセキュアでは現状こちらの方式のみが利用できます。

back_url

戻り先URLを含んだJWS(JSON Web Signatures)形式のデータを指定します。 動的なパラメータの指定が必要な場合や、プラットフォームサービス等で一つのPAY.JPアカウント内で多数のドメインを取扱う場合など、事前登録では要件を満たしづらい場合に有用です。

指定したback_urlに問題があり正常に戻り先URLを受け取れなかった場合、識別子が _fallback であるリダイレクトURLを戻り先URLとして使用します。 _fallback リダイレクトURLの登録がない場合は、戻り先URLが判別できないため画面上はウィンドウを閉じる旨が表示されます。

GET https://api.pay.jp/v1/tds/:resource_id/start

パスパラメータ

:resource_id String

3Dセキュア対象のオブジェクトのID

引数

すべてクエリパラメータで指定します。

publickey String 必須

加盟店の公開API鍵

ここで指定した鍵によってlivemode/testmodeが決定されます。 他のパラメータについてもpublickeyで指定された鍵のモードに合わせる必要があります。(backで指定する識別子のモード、back_urlの署名秘密鍵のモード等)


back String

3Dセキュア処理後の戻り先とするリダイレクトURLの識別子

リダイレクトURLは事前に管理画面から登録します。


back_url String

戻り先URLを含むJWS形式のデータ

backとback_urlが同時指定された場合、back_urlが優先されbackは無視されます。

詳しい形式は以下の通りです。ドキュメントのリダイレクト型に具体例がございますので合わせてご確認ください。

レスポンス

3Dセキュア認証画面もしくはエラーページ

Platform API (β版)

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

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

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

本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",
  "currencies_supported": [
    "jpy"
  ],
  "default_currency": "jpy",
  "reviewed_brands": [
  ]
}

プロパティ


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

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

tenantイベント

tenant.created

テナント作成

tenant.deleted

テナント削除

tenant.updated

テナント情報の更新、本番申請(初回・更新含む)、弊社による審査結果反映

テナントを作成

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は準備中です
// 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は準備中です
// 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は準備中です
// 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は準備中です
// 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は準備中です
// 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

タイムスタンプ

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

レスポンス

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は準備中です
Payjp::Tenant.create_application_urls('ten_121673955bd7aa144de5a8f6c262')
\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は準備中です
// 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を作成します。

テストモードの場合、実際の審査は行われず情報が保存されない為、常に新規申請になります。

引数

なし

レスポンス


object String

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


url String

テナントの審査申請URL

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

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

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

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

https://pay.jp/_/applications/start/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",
          "three_d_secure_status": null
        },
        "created": 1441706750,
        "currency": "jpy",
        "customer": "cus_b92b879e60f62b532d6756ae12af",
        "description": null,
        "expired_at": null,
        "failure_code": null,
        "failure_message": null,
        "fee_rate": "3.00",
        "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,
        "three_d_secure_status": null
      }
    ],
    "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": 300,
    "charge_gross": 1000,
    "net": 690,
    "refund_amount": 0,
    "refund_count": 0,
    "dispute_amount": 0,
    "dispute_count": 0
  },
  "tenant_id": "test",
  "term_end": 1439650800,
  "term_start": 1438354800,
  "transfer_amount": null,
  "transfer_date": null
}

基本的に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