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'];
echo 'Status is:' . $e->getHttpStatus() . PHP_EOL;
echo 'Type is:' . $err['type'] . PHP_EOL;
echo 'Code is:' . $err['code'] . PHP_EOL;
// param is '' in this case
echo 'Param is:' . $err['param'] . PHP_EOL;
echo 'Message is:' . $err['message'] . PHP_EOL;
} 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
キーがない場合などもあります。
error[type]
: 大まかなエラー種別が入ります(下表)。error[code]
: 詳細なエラー内容の識別子が入ります(下表)。error[message]
:error[code]
の文章説明が入ります。これは事業者向けの内容となっており、エンドユーザーへ提示する内容として利用することは推奨しておりません。error[status]
: HTTPステータスコードと同様の値が数値型で入ります(下表)。
なお、各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 | 顧客のカードとして登録されていないか、削除済み |
three_d_secure_expired | 3Dセキュアの認証完了期限が切れている |
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アルゴリズム に従って実装されています。
各ゾーンに対するリクエストは一旦バケットに入り、入った順に流速の値に従って処理されていきます。
- 例) バケット10・流速1のゾーンに瞬間的に3リクエストが着信すると、1秒に1つずつ処理されていき、3秒後にすべてのリクエストが処理される。
流速を超えてリクエストを行うと、バケットの処理待ちリクエスト数が増加します。バケットの上限値を超えてしまう場合は、そのリクエストはエラーとなります。
- 例) バケット10・流速1のゾーンに瞬間的に12リクエストが着信すると、10番目まではバケットに入り、11,12番目のリクエストはエラーとなる。
- 例) バケット10・流速1のゾーンに、2リクエスト/秒の速度でリクエストを送り続けると、約10秒後にバケットがいっぱいになり、以降は半分程度がエラーとなる。
エラーとなった場合、ステータスコード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)) // ログ出力。デフォルトではログは出力されません。
)
チュートリアル - レートリミットへの対応 をご参照ください
また、リトライに対応しているライブラリでは、オプションを設定することによりライブラリ側でレートリミットに対する自動リトライを有効化することができます。オプションの指定方法は右ペインのサンプルコードをご参照ください。
(対応済み言語のみサンプルを記載しています。対応言語は随時拡大して参ります。)
最大リトライ回数
を1以上に設定することにより(デフォルトは0)、その回数までリトライを行うようになります。- 各リトライ間のディレイは、
初期ディレイ
を元に初期ディレイ * (2 ^ リトライ回数)
で増加していきます。結果が最大ディレイ
以上になる場合、代わりに最大ディレイ
がディレイ値となります。 - 実際のディレイは、上記によって算出された値を基準として、
基準値 * 0.5 <= 実際のディレイ <= 基準値
の範囲でランダムに決定されます。 最大リトライ回数
に到達した場合、その回の試行で得られたレスポンスを元に値を返却します。
ヘルプ - レートリミットにもよくある質問への回答が記載されています。
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([
'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([
'metadata' => [
'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の送信が行われます。
イベント一覧
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": 2099,
"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
プラットフォーマーに振り分けられる入金金額。
tenant String
テナントID
platform_fee_rate String
テナント作成時に指定したプラットフォーム利用料率(%)
total_platform_fee Integer
プラットフォーム利用料総額
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([
'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": 2099,
"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を指定して支払いを作成します。 なお、以前はカードオブジェクトの指定ができましたが非通過対応により既に当該パラメーターは利用出来ないようになっております。 詳しくは カード情報非通過化対応のお願い をご覧ください。
テスト用のキーでは、本番用の決済ネットワークへは接続されず、実際の請求が行われることもありません。 本番用のキーでは、決済ネットワークで処理が行われ、実際の請求が行われます。
支払いを確定せずに、カードの認証と支払い額のみ確保する場合は、 capture
に false
を指定してください。
このとき expiry_days
を指定することで、認証の期間を定めることができます。 expiry_days
はデフォルトで7日となっており、1日~60日の間で設定が可能です。なお60日に設定した場合、認証期限は59日後の11:59PM(日本時間)までになります。また確保されました与信枠は、expiry_days
で設定されました期間を過ぎると解放されるようなっております。
three_d_secure
にtrueを指定することで、3Dセキュアを開始できます。
指定した場合、支払いオブジェクトは作成されますが実際の決済処理は保留された状態になります。
保留中の支払いは、引数指定の内容に関わらずcaptured
はfalse
、captured_at
はnull
、expired_at
はnull
と表示されます。
なお、支払い作成から一定時間を経過すると、3Dセキュアフローはタイムアウトし、処理が進められなくなります。
3Dセキュアの進め方は、 支払いで3Dセキュアを実施する を参照してください。
引数
amount Integer
50~9,999,999の整数
amount
とcurrency
の両方が必須
currency String
3文字のISOコード(現状 "jpy" のみサポート)
amount
とcurrency
の両方が必須
customer String
合わせて顧客の保有するカードIDを card
に指定することで、そのカードを支払いに利用できます。
card
を省略した場合はデフォルトカードとして登録されているものが利用されます。
card
かcustomer
のどちらかは必須
card String
トークンIDを指定することで、一度限りの支払いが可能です。 カード情報を使い回したい場合はCustomer (顧客)を利用ください。
customer
を指定している場合、カードIDを指定することで、顧客のデフォルトカード以外のカードを利用できます。
card
かcustomer
のどちらかは必須
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": 2099,
"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');
$charge = \Payjp\Charge::retrieve('ch_fa990a4c10672a93053a774730b0a');
$charge->tdsFinish();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.charges.tds_finish('ch_fa990a4c10672a93053a774730b0a');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Charge charge = Charge.tdsFinish("ch_fa990a4c10672a93053a774730b0a", null, null);
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": 2099,
"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エラーとなる点も同様です。
保留中の支払いで固定値となっていたcapture
、captured_at
、expired_at
は、支払い作成時に指定した通りに反映されます。captured_at
、expired_at
の時刻は本APIにリクエストした時刻を基準として設定されます。
three_d_secure_status
がverified
、attempted
でない支払いに対して本APIをリクエストした場合、エラーとなります。
引数
なし
レスポンス
支払い情報を更新
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');
$charge = \Payjp\Charge::retrieve('ch_fa990a4c10672a93053a774730b0a');
$charge->description = 'Updated';
$charge->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": 2099,
"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');
$charge = \Payjp\Charge::retrieve('ch_fa990a4c10672a93053a774730b0a');
$charge->refund();
// 一部返金する場合
$charge->refund(['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": 2099,
"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": 2099,
"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');
$charge = \Payjp\Charge::retrieve('ch_cce2fce62e9cb5632b3d38b0b1621');
$charge->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": 2099,
"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([
'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": 2099,
"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
レスポンス
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": 2099,
"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([
'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');
$customer = \Payjp\Customer::retrieve('cus_121673955bd7aa144de5a8f6c262');
$customer->email = 'added@example.com';
$customer->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');
$customer = \Payjp\Customer::retrieve('cus_121673955bd7aa144de5a8f6c262');
$customer->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([
'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');
$customer = \Payjp\Customer::retrieve('cus_4df4b5ed720933f4fb9e28857517');
$customer->cards->create([
'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": 2099,
"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
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');
$customer = \Payjp\Customer::retrieve('cus_4df4b5ed720933f4fb9e28857517');
$customer->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": 2099,
"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');
$customer = \Payjp\Customer::retrieve('cus_4df4b5ed720933f4fb9e28857517');
$card = $customer->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": 2099,
"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');
$customer = \Payjp\Customer::retrieve('cus_4df4b5ed720933f4fb9e28857517');
$card = $customer->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([
'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": 2099,
"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');
$customer = \Payjp\Customer::retrieve('cus_4df4b5ed720933f4fb9e28857517');
$customer->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([
'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([
'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');
$plan = \Payjp\Plan::retrieve('pln_45dd3268a18b2837d52861716260');
$plan->name = 'NewPlan';
$plan->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');
$plan = \Payjp\Plan::retrieve('pln_45dd3268a18b2837d52861716260');
$plan->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([
'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\Payjp::setApiKey('sk_test_c62fade9d045b54cd76d7036');
\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')
\Payjp\Payjp::setApiKey('sk_test_c62fade9d045b54cd76d7036');
$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は以下のいずれかの条件で失効します。
- 発行から1時間以上経過した
- 同じオブジェクト +
platformer
パラメータの組み合わせに対して新しいダウンロード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\Payjp::setApiKey('sk_test_c62fade9d045b54cd76d7036');
\Payjp\Statement::all([
'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の値で絞り込みます。
レスポンス
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([
'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を指定して、定期課金を開始します。
前払い式のため、定期課金作成時に最初の課金が実行されます。但し以下の場合には作成時の課金はされません。
- トライアル状態(
status=trial
)で作成された場合 - プランの課金日(
billing_day
)が指定され、定期課金の日割り設定(prorate
)が設定されていない場合
引数
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');
$subscription = \Payjp\Subscription::retrieve('sub_567a1e44562932ec1a7682d746e0');
$subscription->trial_end = 1473911903;
$subscription->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 | 無し |
指定するプランについては、以下に注意ください。
- プランに設定されているトライアル期間は無視されます
- この定期課金に紐づく顧客が、指定するプランを既に別の定期課金で購読している場合、または別の定期課金の
next_cycle_plan
として設定されている場合はエラーとなります
なお 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');
$subscription = \Payjp\Subscription::retrieve('sub_567a1e44562932ec1a7682d746e0');
$subscription->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');
$subscription = \Payjp\Subscription::retrieve('sub_567a1e44562932ec1a7682d746e0');
$subscription->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');
$subscription = \Payjp\Subscription::retrieve('sub_567a1e44562932ec1a7682d746e0');
$subscription->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');
$subscription = \Payjp\Subscription::retrieve('sub_567a1e44562932ec1a7682d746e0');
$subscription->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([
'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
のみ指定可能。
レスポンス
リストは、直近で生成された順番に取得されます。
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": 2099,
"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]=2099"
-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' : '2099'
},
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 => '2099'
}},
{
'X-Payjp-Direct-Token-Generate': 'true'
}
)
\Payjp\Payjp::setApiKey('sk_test_c62fade9d045b54cd76d7036');
\Payjp\Token::create([
'card' => [
"number" => "4242424242424242",
"exp_month" => "12",
"exp_year" => "2099",
]
], [
'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: 2099
},
}, {
'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", "2099");
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: "2099",
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": 2099,
"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": 2099,
"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オブジェクト
トークンに対する3Dセキュアフローを完了する
POST https://api.pay.jp/v1/tokens/:id/tds_finish
curl https://api.pay.jp/v1/tokens/tok_5ca06b51685e001723a2c3b4aeb4/tds_finish \
-u sk_test_c62fade9d045b54cd76d7036: \
-XPOST
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
token = payjp.Token.retrieve('tok_5ca06b51685e001723a2c3b4aeb4')
finished_token = token.tds_finish()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
finished_token = Payjp::Token.tds_finish('tok_5ca06b51685e001723a2c3b4aeb4')
\Payjp\Payjp::setApiKey('sk_test_c62fade9d045b54cd76d7036');
$token = \Payjp\Token::retrieve('tok_5ca06b51685e001723a2c3b4aeb4');
$finishedToken = $token->tdsFinish();
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.tokens.tds_finish('tok_5ca06b51685e001723a2c3b4aeb4');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Token finishedToken = Token.tdsFinish("tok_5ca06b51685e001723a2c3b4aeb4", null, null);
finishedToken, err := pay.Token.TdsFinish("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": 2099,
"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"
}
}
カード会社画面での3Dセキュア認証が終了したトークンに対し、3Dセキュアフローを完了させ、カードの有効性確認を行います。
引数
なし
レスポンス
指定した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": 2099,
"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": 2099,
"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": 2099,
"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
レスポンス
入金の内訳を取得
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([
'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": 2099,
"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
レスポンス
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の集計区間オブジェクトを取得します。
引数
なし
レスポンス
集計区間のリストを取得
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([
'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が指定したタイムスタンプ以前であるオブジェクトを取得
レスポンス
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
残高を取得
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')
\Payjp\Payjp::setApiKey('sk_test_c62fade9d045b54cd76d7036');
$url = \Payjp\Balance::retrieve('ba_013f3c308b771358605dd2445d60f')
->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([
'since_due_date' => 1706713200,
'until_due_date' => 1709218800,
'state' => 'collecting',
'closed' => true,
'owner' => 'tenant',
// 'tenant' => 'ten_121673955bd7aa144de5a8f6c262', // tenant の Balance を取得したいときに利用します。
]);
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
指定したテナントが所有者であるオブジェクトに限定
レスポンス
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([
'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": 2099,
"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
ここに指定したタイムスタンプ以前に作成されたデータを取得
レスポンス
リストは、直近で生成された順番に取得されます。
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_4ec110e0700daf893160424fe03c
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
three_d_secure_request = payjp.ThreeDSecureRequest.create(resource_id='car_4ec110e0700daf893160424fe03c')
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
three_d_secure_request = Payjp::ThreeDSecureRequest.create(:resource_id => 'car_4ec110e0700daf893160424fe03c')
\Payjp\Payjp::setApiKey('sk_test_c62fade9d045b54cd76d7036');
$threeDSecureRequest = \Payjp\ThreeDSecureRequest::create([
'resource_id' => 'car_4ec110e0700daf893160424fe03c',
]);
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
const threeDSecureRequest = payjp.three_d_secure_requests.create({resource_id: 'car_4ec110e0700daf893160424fe03c'});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> threeDSecureRequestParams = new HashMap<String, Object>();
threeDSecureRequestParams.put("resource_id", "car_4ec110e0700daf893160424fe03c");
ThreeDSecureRequest threeDSecureRequest = ThreeDSecureRequest.create(threeDSecureRequestParams);
threeDSecureRequest, err := pay.ThreeDSecureRequest.Create(payjp.ThreeDSecureRequest{ResourceID: "car_4ec110e0700daf893160424fe03c"})
レスポンス
{
"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_4ec110e0700daf893160424fe03c",
"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.three_d_secure_requests.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([
'limit' => 3,
'offset' => 10,
]);
const payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.three_d_secure_requests.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"
}
}
あなたのアカウント情報を取得します。
引数
なし
レスポンス
3-DSecure
3Dセキュア開始
3Dセキュア認証画面をエンドユーザーに表示します。 このエンドポイントはJSONではなくエンドユーザーが直接アクセスしウェブページを表示するもので、SDK、または加盟店サーバーからのアクセスは想定されていません。 詳しいご利用方法は下記チュートリアルをご参照ください。
認証
認証/モードの指定はクエリパラメータの publickey
によって行います。
終了時の戻り先URL指定
リダイレクト型3Dセキュアにおける認証終了時、およびエラー時の戻り先URLの指定にはback
かback_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は無視されます。
詳しい形式は以下の通りです。ドキュメントのリダイレクト型に具体例がございますので合わせてご確認ください。
- ペイロード
url
キーに戻り先URLを指定します。- URLエンコード済みの値としてください。このURLがそのままエンドユーザーにアクセスされます。
url
以外のキーは無視されます。
- 署名アルゴリズム
- HS256
- シークレット
- 加盟店の秘密鍵
レスポンス
3Dセキュア認証画面もしくはエラーページ
※ 戻り先 URL にリダイレクトされる時に、PAY.JPから特別なパラメーターが付与されたりすることはありません。
開始エンドポイントへの誘導前にあらかじめリソースのIDをセッションなどに保持しておいてください。
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 と異なります。
- charge 作成時に
tenant
の指定が必要 - charge 作成時にプラットフォーマーの入金金額として
platform_fee
を指定可能 - chargeリスト取得時に
tenant
を指定可能(未指定の場合は全テナントを対象) - 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([
'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_...');
$tenant = \Payjp\Tenant::retrieve('ten_121673955bd7aa144de5a8f6c262');
$tenant->platform_fee_rate = '30';
$tenant->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_...');
$tenant = \Payjp\Tenant::retrieve('ten_121673955bd7aa144de5a8f6c262');
$tenant->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([
'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
タイムスタンプ
指定したタイムスタンプ以前に作成されたデータのみ取得
レスポンス
テナントの審査申請ページの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は以下の条件で失効します。
- 一度でもアクセスした場合
- 使用期限(発行から5分)が過ぎた場合
- 再度このAPIが叩かれ、新しい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": 2099,
"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
tenant_transferイベント
tenant_transfer.succeeded
テナントの入金内容の確定
テナントの入金情報を取得
GET https://api.pay.jp/v1/tenant_transfers/:tenant_transfer_id
curl https://api.pay.jp/v1/tenant_transfers/ten_tr_23748b8c95c79edff22a8b7b795xx \
-u sk_test_...:
SDKは準備中です
SDKは準備中です
\Payjp\Payjp::setApiKey('sk_test_...');
\Payjp\TenantTransfer::retrieve('ten_tr_23748b8c95c79edff22a8b7b795xx');
const payjp = require('payjp')('sk_test_...');
payjp.tenant_transfers.retrieve('ten_tr_23748b8c95c79edff22a8b7b795xx');
SDKは準備中です
レスポンス
{
"amount": 1000,
"carried_balance": null,
"charges": {
"count": 1,
"data": [
{
"amount": 1000,
"amount_refunded": 0,
"captured": true,
"captured_at": 1441706750,
"card": {
"address_city": null,
"address_line1": null,
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "Visa",
"country": null,
"created": 1441706750,
"customer": null,
"cvc_check": "unchecked",
"exp_month": 5,
"exp_year": 2099,
"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
}
エラーレスポンス
{
"error": {
"message": "There is no tenant transfer with ID: dummy",
"param": "id",
"status": 404,
"type": "client_error"
}
}
テナントの入金情報を取得します。
引数
なし
レスポンス
指定したidのtenant_transferオブジェクト
テナント入金の取引明細ダウンロードURLを発行
POST https://api.pay.jp/v1/tenant_transfers/:tenant_transfer_id/statement_urls
curl -X POST https://api.pay.jp/v1/tenant_transfers/ten_tr_23748b8c95c79edff22a8b7b795xx/statement_urls\
-u sk_test_...:
SDKは準備中です
SDKは準備中です
\Payjp\TenantTransfer::retrieve('ten_tr_23748b8c95c79edff22a8b7b795xx')
->statementUrls
->create();
payjp.tenant_transfers.statementUrls('ten_tr_23748b8c95c79edff22a8b7b795xx', {})
SDKは準備中です