NAV
curl Python Ruby PHP node Java

Introduction

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::setApiKey("sk_test_c62fade9d045b54cd76d7036")
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
Payjp.apikey = "sk_test_c62fade9d045b54cd76d7036";

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

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

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

プロトコル

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

メソッド

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

レスポンス形式

APIからのレスポンスデータは全てJSON形式で返されます。

タイムスタンプ

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

Error

エラーとなるリクエストには、"error"というキーが含まれたエラーレスポンスが返されます。 ステータスコードには、4xxか5xxの該当するエラーのステータスコードがセットされます。通常の成功するレスポンスでは、ステータスコードには200のステータスコードがセットされます。 エラーレスポンス “error” 内の “message” にはエラーメッセージが含まれます。エラーメッセージは事業者向けの内容となっており、エンドユーザーへ提示する内容として利用することを推奨しておりません。

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

エラーハンドリング

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 communication with Payjp failed
rescue Payjp::PayjpError => e
  # Display a very generic error to the user, and maybe send
  # yourself an email
rescue => e
  # Something else happened, completely unrelated to Payjp
end
try {
  // Use Payjp's library to make requests...
} catch(\Payjp\Error\Card $e) {
  // Since it's a decline, \Payjp\Error\Card will be caught
  $body = $e->getJsonBody();
  $err  = $body['error'];

  print('Status is:' . $e->getHttpStatus() . "\n");
  print('Type is:' . $err['type'] . "\n");
  print('Code is:' . $err['code'] . "\n");
  // param is '' in this case
  print('Param is:' . $err['param'] . "\n");
  print('Message is:' . $err['message'] . "\n");
} catch (\Payjp\Error\InvalidRequest $e) {
  // Invalid parameters were supplied to Payjp's API
} catch (\Payjp\Error\Authentication $e) {
  // Authentication with Payjp's API failed
} catch (\Payjp\Error\ApiConnection $e) {
  // Network communication with Payjp failed
} catch (\Payjp\Error\Base $e) {
  // Display a very generic error to the user, and maybe send
  // yourself an email
} catch (Exception $e) {
  // Something else happened, completely unrelated to Payjp
}
// e.g. payjp.customers.create({...})

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

Pagination

全てのトップレベルのAPIリソースでは、ページネーションを指定してデータを取得することができます。 例えば、直近の支払情報を10件まで取得したい場合、 limit=10 というクエリーを追加します。

クエリー 詳細
limit 取得するデータ数の最大値(1~100まで)
offset 基準点からのデータ取得を行う開始位置
curl https://api.pay.jp/v1/customers?limit=3&offset=10 \
-u sk_test_c62fade9d045b54cd76d7036:
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.subscriptions.all(limit=3, offset=10)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
customer.subscriptions.all(limit: 3, offset: 10)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
\Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517")->subscription->all(array("limit"=>3, "offset"=>10));
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.subscriptions.list('cus_121673955bd7aa144de5a8f6c262', {
  limit: 3,
  offset: 10
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Customer cu = Customer.retrieve("cus_4df4b5ed720933f4fb9e28857517");
Map<String, Object> listParams = new HashMap<String, Object>();
listParams.put("limit", 3);
listParams.put("offset", 10);
cu.getSubscriptions().all(listParams);

Metadata

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

メタデータを利用するには、対象オブジェクトの作成もしくは更新リクエストに metadata[キー]=バリュー を追加します。

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

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

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

Charge (支払い)

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

支払いを作成

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

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

レスポンス

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

エラーレスポンス

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

トークンID、カードを保有している顧客ID、カードオブジェクトのいずれかのパラメーターを指定して支払いを作成します。 顧客IDを使って支払いを作成する場合はcardパラメータに顧客の保有するカードのIDを指定でき、省略された場合はデフォルトカードとして登録されているものが利用されます。

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

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

引数 詳細
amount Integer 50~9,999,999の整数 (amountとcurrencyもしくはprodcutのどちらかは必須パラメータ)
currency String 3文字のISOコード(現状 “jpy” のみサポート, amountとcurrencyもしくはprodcutのどちらかは必須パラメータ)
product String プロダクトID (amountとcurrencyもしくはprodcutのどちらかは必須パラメータ)
customer String 顧客ID (cardかcustomerのどちらかは必須パラメータ)
card String トークンID または 顧客の保有しているカードID (cardかcustomerのどちらかは必須パラメータ)
card Object カードオブジェクト(cardかcustomerのどちらかは必須)
card[number] String カード番号
card[exp_month] String 有効期限月
card[exp_year] String 有効期限年
card[cvc] String 3~4桁のCVCコード
card[address_state] String 都道府県
card[address_city] String 市区町村
card[address_line1] String 番地など
card[address_line2] String 建物名など
card[address_zip] String 郵便番号
card[name] String カード保有者名(e.g. “YUI ARAGAKI”)
card[country] String 2桁のISOコード(e.g. JP)
description String 概要
capture Boolean 支払い処理を確定するかどうか (falseの場合、カードの認証と支払い額の確保のみ行う)
expiry_days Integer 認証状態が失効するまでの日数
metadata Object キーバリューの任意データ

支払い情報を取得

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

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

レスポンス

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

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"charge"
id String ch_で始まる一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer この支払い作成時のUTCタイムスタンプ
amount Integer 支払い額
currency String 3文字のISOコード(現状 “jpy” のみサポート)
paid Boolean 認証処理が成功しているかどうか。
expired_at Integer 認証状態が自動的に失効される日時のタイムスタンプ
captured Boolean 支払い処理を確定しているかどうか
captured_at Integer 支払い処理確定時のUTCタイムスタンプ
card Dictionary 支払いされたクレジットカードの情報
card[object] String オブジェクト名 値は"card"
card[id] String car_で始まる一意なオブジェクトを示す文字列
card[created] Integer カード作成時のUTCタイムスタンプ
card[name] String カード保有者名(e.g. YUI ARAGAKI)
card[last4] String カード番号の下四桁
card[exp_month] String 有効期限月
card[exp_year] String 有効期限年
card[brand] String カードブランド名
card[cvc_check] String CVCコードチェックの結果
card[fingerprint] String このクレジットカード番号に紐づけられた一意(他と重複しない)キー
card[address_city] String 市区町村
card[address_line1] String 番地など
card[address_line2] String 建物名など
card[address_state] String 都道府県
card[country] String 2桁のISOコード(e.g. JP)
card[address_zip] String 郵便番号
card[address_zip_check] String 郵便番号存在チェックの結果
customer String 顧客ID
description String 概要
failure_code String 失敗した支払いのエラーコード
failure_message String 失敗した支払いの説明
refunded Boolean 返金済みかどうか
amount_refunded Integer この支払いに対しての返金額
refund_reason String 返金理由
subscription String sub_から始まる定期課金のID
metadata Object キーバリューの任意データ

支払い情報を更新

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

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

レスポンス

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

エラーレスポンス

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

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

引数 詳細
description String 概要
metadata Object キーバリューの任意データ

返金する

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

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

レスポンス

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

エラーレスポンス

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

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

引数 詳細
amount Integer 1~9,999,999の整数
refund_reason string 返金理由

支払いを再認証する

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

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

レスポンス

{
  "amount": 775,
  "amount_refunded": 0,
  "captured": false,
  "captured_at": null,
  "card": {
    "address_city": null,
    "address_line1": null,
    "address_line2": null,
    "address_state": null,
    "address_zip": null,
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": "JP",
    "created": 1470087896,
    "customer": null,
    "cvc_check": "passed",
    "exp_month": 12,
    "exp_year": 2017,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_d3f7bb8572250f8c5ab1328e4764",
    "last4": "4242",
    "livemode": false,
    "metadata": {},
    "name": null,
    "object": "card"
  },
  "created": 1470088864,
  "currency": "jpy",
  "customer": "cus_137f2aec147eeafe849841d093a3",
  "description": null,
  "expired_at": 1470175385,
  "failure_code": null,
  "failure_message": null,
  "id": "ch_82a41a81849c9e354c774cbd2d9e0",
  "livemode": false,
  "metadata": {},
  "object": "charge",
  "paid": true,
  "refund_reason": null,
  "refunded": false,
  "subscription": null
}

エラーレスポンス

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

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

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

引数 詳細
expiry_days Integer 認証状態が失効するまでの日数

支払い処理を確定する

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

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

レスポンス

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

エラーレスポンス

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

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

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

amount をセットした場合、amount_refunded に認証時の amount との差額が入ります。

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

引数 詳細
amount Integer 50~9,999,999の整数

支払いリストを取得

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

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

レスポンス

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

エラーレスポンス

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

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

引数 詳細
limit Integer 1〜100
offset Integer
customer String 顧客ID
subscription String 定期課金ID
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

Customer (顧客)

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

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

顧客を作成

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

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

レスポンス

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

エラーレスポンス

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

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

作成と同時にカード情報を登録する場合、トークンIDかカードオブジェクトのどちらかを指定します。

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

引数 詳細
email String メールアドレス
description String 概要
id String 一意の顧客ID
card String トークンID(トークンIDかカードオブジェクトのどちらかのみ指定可能)
card Object カードオブジェクト(トークンIDかカードオブジェクトのどちらかのみ指定可能)
card[number] String カード番号
card[exp_month] String 有効期限月
card[exp_year] String 有効期限年
card[cvc] String 3~4桁のCVCコード
card[address_state] String 都道府県
card[address_city] String 市区町村
card[address_line1] String 番地など
card[address_line2] String 建物名など
card[address_zip] String 郵便番号
card[country] String 2桁のISOコード(e.g. JP)
card[name] String カード保有者名(e.g. “YUI ARAGAKI”)
metadata Object キーバリューの任意データ

顧客情報を取得

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

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

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

レスポンス

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

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"customer"
id String 一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer この顧客作成時のUTCタイムスタンプ
default_card String 支払いにデフォルトで使用されるカードのcar_から始まるID
cards List この顧客に紐づけられているカードのリスト
email String メールアドレス
description String 概要
subscriptions List この顧客が購読している定期課金のリスト
metadata Object キーバリューの任意データ

顧客情報を更新

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

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

レスポンス

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

エラーレスポンス

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

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

引数 詳細
email String メールアドレス
description String 概要
default_card String 保持しているカードID
card String トークンID(トークンIDかカードオブジェクトのどちらかのみ指定可能)
card Object カードオブジェクト(トークンIDかカードオブジェクトのどちらかのみ指定可能)
card[number] String カード番号
card[exp_month] String 有効期限月
card[exp_year] String 有効期限年
card[cvc] String 3~4桁のCVCコード
card[address_state] String 都道府県
card[address_city] String 市区町村
card[address_line1] String 番地など
card[address_line2] String 建物名など
card[address_zip] String 郵便番号
card[country] String 2桁のISOコード(e.g. JP)
card[name] String カード保有者名(e.g. “YUI ARAGAKI”)
metadata Object キーバリューの任意データ

顧客を削除

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

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

レスポンス

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

エラーレスポンス

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

生成した顧客情報を削除します。削除した顧客情報は、もう一度生成することができないためご注意ください。

顧客リストを取得

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

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

レスポンス

{
  "count": 3,
  "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
offset Integer
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

顧客のカードを作成

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

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

レスポンス

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

エラーレスポンス

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

トークンIDかカード情報のパラメーターのどちらかを指定して、新たにカードを追加します。ただし同じカード番号および同じ有効期限年/月のカードは、重複追加することができません。

引数 詳細
card String トークンID(トークンIDか下記カード情報のパラメーターのどちらかのみ指定可能)
number String カード番号
exp_month String 有効期限月
exp_year String 有効期限年
cvc String 3~4桁のCVCコード
address_state String 都道府県
address_city String 市区町村
address_line1 String 番地など
address_line2 String 建物名など
address_zip String 郵便番号
country String 2桁のISOコード(e.g. JP)
name String カード保有者名(e.g. “YUI ARAGAKI”)
metadata Object キーバリューの任意データ

顧客のカード情報を取得

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

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

レスポンス

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

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"card"
id String car_で始まる一意なオブジェクトを示す文字列
created Integer カード作成時のUTCタイムスタンプ
name String カード保有者名(e.g. “YUI ARAGAKI”)
last4 String カード番号の下四桁
exp_month String 有効期限月
exp_year String 有効期限年
brand String カードブランド名
cvc_check String CVCコードチェックの結果
fingerprint String このクレジットカード番号に紐づけられた一意(他と重複しない)キー
address_state String 都道府県
address_city String 市区町村
address_line1 String 番地など
address_line2 String 建物名など
country String 2桁のISOコード(e.g. JP)
address_zip String 郵便番号
address_zip_check String 郵便番号存在チェックの結果
metadata Object キーバリューの任意データ

顧客のカードを更新

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

curl https://api.pay.jp/v1/customers/cus_4df4b5ed720933f4fb9e28857517/cards/car_f7d9fa98594dc7c2e42bfcd641ff \
-u sk_test_c62fade9d045b54cd76d7036: \
-d exp_year=2026 \
-d exp_month=05
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = payjp.Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
card = customer.cards.retrieve('car_f7d9fa98594dc7c2e42bfcd641ff')
card.exp_year=2026
card.exp_month=2
card.save()
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
customer = Payjp::Customer.retrieve('cus_4df4b5ed720933f4fb9e28857517')
card = customer.cards.retrieve('car_f7d9fa98594dc7c2e42bfcd641ff')
card.exp_year=2026
card.exp_month=2
card.save
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$cu = \Payjp\Customer::retrieve("cus_4df4b5ed720933f4fb9e28857517");
$card = $cu->cards->retrieve("car_f7d9fa98594dc7c2e42bfcd641ff");
$card->exp_year = "2026";
$card->exp_month = "05";
$card->save();
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.customers.cards.update(
  'cus_121673955bd7aa144de5a8f6c262',
  'car_f7d9fa98594dc7c2e42bfcd641ff', {
  exp_year: 2026,
  exp_month: 5
});
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("exp_year", "2026");
updateParams.put("exp_month", "05");
ca.update(updateParams);

レスポンス

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

エラーレスポンス

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

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

引数 詳細
exp_month String 有効期限月
exp_year String 有効期限年
cvc String 3~4桁のCVCコード
address_state String 都道府県
address_city String 市区町村
address_line1 String 番地など
address_line2 String 建物名など
address_zip String 郵便番号
country String 2桁のISOコード(e.g. JP)
name String カード保有者名(e.g. “YUI ARAGAKI”)
metadata Object キーバリューの任意データ

顧客のカードを削除

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

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

レスポンス

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

エラーレスポンス

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

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

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

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

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

レスポンス

{
  "count": 3,
  "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": 1433127983,
      "customer": null,
      "cvc_check": "unchecked",
      "exp_month": 2,
      "exp_year": 2020,
      "fingerprint": "e1d8225886e3a7211127df751c86787f",
      "id": "car_f7d9fa98594dc7c2e42bfcd641ff",
      "last4": "4242",
      "livemode": false,
      "metadata": null,
      "name": null,
      "object": "card"
    },
    {...},
    {...}
  ],
  "object": "list",
  "has_more": true,
  "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
offset Integer
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

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

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

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

レスポンス

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

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"subscription"
id String sub_で始まる一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer この定期課金作成時のUTCタイムスタンプ
start Integer この定期課金開始時のUTCタイムスタンプ
customer String この定期課金を購読している顧客のID
plan Dictionary この定期課金のプラン情報
plan[object] String オブジェクト名 値は"plan"
plan[id] String 一意なオブジェクトを示す文字列
plan[created] Integer このプラン作成時のUTCタイムスタンプ
plan[amount] Integer プラン金額
plan[currency] String 3文字のISOコード(現状 “jpy” のみサポート)
plan[interval] String 課金周期(現状"month"のみサポート)
plan[name] String プラン名
plan[trial_days] Integer トライアル日数
plan[billing_day] Integer 課金日(1-31)
status String この定期課金の現在の状態
current_period_start Integer 現在の購読期間開始時のUTCタイムスタンプ
current_period_end Integer 現在の購読期間終了時のUTCタイムスタンプ
trial_start Integer トライアル期間開始時のUTCタイムスタンプ
trial_end Integer トライアル期間終了時のUTCタイムスタンプ
paused_at Integer 定期課金が停止状態になった時のUTCタイムスタンプ
canceled_at Integer 定期課金がキャンセル状態になった時のUTCタイムスタンプ
resumed_at Integer 停止またはキャンセル状態の定期課金が有効状態になった時のUTCタイムスタンプ
metadata Object キーバリューの任意データ

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

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

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

レスポンス

{
  "count": 3,
  "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": true,
  "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
offset Integer
plan String プランID
status String ステータス(active, trial, canceled, paused)
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

Plan (プラン)

定期購入のときに使用する静的なプラン情報です。

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

生成したプランは、顧客と紐付けて定期購入処理を行うことができます。

プランを作成

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

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

レスポンス

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

エラーレスポンス

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

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

期間は月次と年次を指定できます。

トライアル日数を指定することで、トライアル付きのプランを生成することができます。

また、課金日(billing_day)を指定すると、支払い日の固定されたプランを生成することができます(月次のみ)。

引数 詳細
amount Integer 必須
50~9,999,999の整数
currency String 必須
3文字のISOコード(現状 “jpy” のみサポート)
interval String 必須
“month"および"year"が指定可能
id String プランID
name String プランの名前
trial_days Integer トライアル日数
billing_day Integer 月次プランに指定可能な課金日(1〜31)
metadata Object キーバリューの任意データ

プラン情報を取得

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

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

レスポンス

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

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"plan”
id String 一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer このプラン作成時のUTCタイムスタンプ
amount Integer プラン金額
currency String 3文字のISOコード(現状 “jpy” のみサポート)
interval String 課金周期(“month"もしくは"year”)
name String プラン名
trial_days Integer トライアル日数
billing_day Integer 月次プランの課金日(1-31, 年次の場合は"null")
metadata Object キーバリューの任意データ

プランを更新

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

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

レスポンス

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

エラーレスポンス

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

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

引数 詳細
name String プランの名前
metadata Object キーバリューの任意データ

プランを削除

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

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

レスポンス

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

エラーレスポンス

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

プランを削除します。

プランリストを取得

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

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

レスポンス

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

エラーレスポンス

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

生成したプランのリストを取得します。リストは、直近で生成された順番に取得されます。

引数 詳細
limit Integer 取得するデータ数の最大値(1~100まで)
offset Integer 基準点からのデータ取得を行う開始位置
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

Subscription (定期課金)

月もしくは年単位で定期的な支払い処理を行います。顧客IDとプランIDを指定して生成します。

status="trial" の場合は支払いは行われず、status="active" の場合のみ支払いが行われます。

支払い処理は、はじめに定期課金を生成した瞬間に行われ、そこを基準にして定期的な支払いが行われていきます。 定期課金は、顧客に複数紐付けるができ、生成した定期課金は停止・再開・キャンセル・削除することができます。

詳しい実装方法については チュートリアル - 定期課金 をご覧ください。

定期課金を作成

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

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

レスポンス

{
  "canceled_at": null,
  "created": 1433127983,
  "current_period_end": 1435732422,
  "current_period_start": 1433140422,
  "customer": "cus_4df4b5ed720933f4fb9e28857517",
  "id": "sub_567a1e44562932ec1a7682d746e0",
  "livemode": false,
  "metadata": null,
  "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を指定して、定期課金を開始することができます。trial_endを指定することで、プラン情報を上書きするトライアル設定も可能です。 最初の支払いは定期課金作成時に実行されます。課金日(billing_day)が指定されている月次プランの場合は日割り設定(prorate)を有効化しない限り、作成時よりもあとの課金日に最初の支払いが行われます。

トライアル設定がある場合は、トライアル終了時に支払い処理が行われ、そこを基準にして定期課金が開始されます。課金日(billing_day)が指定されている場合も同様に、トライアル終了時に支払い処理(日割り設定(prorate)が有効の場合は日割額、無効の場合は満額)が行われますのでご注意ください。

引数 詳細
customer String 必須
顧客ID
plan String 必須
プランID
trial_end Integer リクエスト時より未来のUTCタイムスタンプ
trial_end String nowのみ指定可能
prorate Boolean 日割り課金を設定するかどうか(デフォルトはfalse)
metadata Object キーバリューの任意データ

定期課金情報を取得

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

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

レスポンス

{
  "canceled_at": null,
  "created": 1433127983,
  "current_period_end": 1435732422,
  "current_period_start": 1433140422,
  "customer": "cus_4df4b5ed720933f4fb9e28857517",
  "id": "sub_567a1e44562932ec1a7682d746e0",
  "livemode": false,
  "metadata": null,
  "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"
  }
}

生成した特定の定期課金情報を取得します。

プロパティ名 詳細
object String オブジェクト名 値は"subscription"
id String sub_で始まる一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer この定期課金作成時のUTCタイムスタンプ
start Integer この定期課金開始時のUTCタイムスタンプ
customer String この定期課金を購読している顧客のID
plan Dictionary この定期課金のプラン情報
plan[object] String オブジェクト名 値は"plan"
plan[id] String 一意なオブジェクトを示す文字列
plan[created] Integer このプラン作成時のUTCタイムスタンプ
plan[amount] Integer プラン金額
plan[currency] String 3文字のISOコード(現状 “jpy” のみサポート)
plan[interval] String 課金周期(“month"もしくは"year”)
plan[name] String プラン名
plan[trial_days] Integer トライアル日数
plan[billing_day] Integer 月次プランの課金日(1-31, 年次の場合は"null")
status String この定期課金の現在の状態
prorate Boolean 日割り課金が有効かどうか
current_period_start Integer 現在の購読期間開始時のUTCタイムスタンプ
current_period_end Integer 現在の購読期間終了時のUTCタイムスタンプ
trial_start Integer トライアル期間開始時のUTCタイムスタンプ
trial_end Integer トライアル期間終了時のUTCタイムスタンプ
paused_at Integer 定期課金が停止状態になった時のUTCタイムスタンプ
canceled_at Integer 定期課金がキャンセル状態になった時のUTCタイムスタンプ
resumed_at Integer 停止またはキャンセル状態の定期課金が有効状態になった時のUTCタイムスタンプ
metadata Object キーバリューの任意データ

定期課金を更新

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

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

レスポンス

{
  "canceled_at": null,
  "created": 1433127983,
  "current_period_end": 1435732422,
  "current_period_start": 1433140422,
  "customer": "cus_4df4b5ed720933f4fb9e28857517",
  "id": "sub_567a1e44562932ec1a7682d746e0",
  "livemode": false,
  "metadata": null,
  "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=now とする事により、トライアル期間を終了し課金を即時実行できます。

プランを変更する場合は、 plan に新しいプランのIDを指定してください。同時に prorate=true とする事により、 日割り課金を有効化できます。

引数 詳細
trial_end Integer リクエスト時より未来のUTCタイムスタンプ
trial_end String nowのみ指定可能
plan String プランID
prorate Boolean 日割り課金を設定するかどうか
metadata Object キーバリューの任意データ

定期課金を停止

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

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

レスポンス

{
  "canceled_at": null,
  "created": 1432965397,
  "current_period_end": 1435643801,
  "current_period_start": 1432965401,
  "customer": "cus_2498ea9cb54644f4516a9bf6dc78",
  "id": "sub_f9fb5ef2507b46c00a1a84c47bed",
  "livemode": false,
  "metadata": null,
  "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"
  }
}

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

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

定期課金を再開

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

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

レスポンス

{
  "canceled_at": null,
  "created": 1432965397,
  "current_period_end": 1435733621,
  "current_period_start": 1433141621,
  "customer": "cus_2498ea9cb54644f4516a9bf6dc78",
  "id": "sub_f9fb5ef2507b46c00a1a84c47bed",
  "livemode": false,
  "metadata": null,
  "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"
  }
}

停止もしくはキャンセル状態の定期課金を再開させます。 トライアル日数が残っていて再開日がトライアル終了日時より前の場合と trial_end にUTCタイムスタンプが指定された場合は、 トライアル状態で定期課金が再開されます。

trial_end にUTCタイムスタンプを指定することで、トライアル終了日を任意の日時に再指定する事ができます。 trial_endnow を指定することで、トライアル期間を終了し課金を即時実行できます。

再開時に current_period_end が過去の日時の場合、trial_end にUTCタイムスタンプを指定しなければ、先に支払いの試行が行われます。例えば、支払いの失敗により停止した場合、 current_period_end は支払い失敗時の値になるため、必ず過去の日時がセットされます。 再開時の支払いに失敗すると、定期課金は再開されません。

この場合は、有効なカードを顧客のデフォルトカードにセットしてから、再度定期課金の再開を行ってください。

trial_end にUTCタイムスタンプを指定した場合は、トライアル状態で再開されるため支払いの試行は行われません。

またprorate を指定することで、日割り課金を有効化することができます。プランに課金日(billing_day)が設定されてる場合は、再開日から直近の課金日までの日数分で日割りした金額が課金されます。

引数 詳細
trial_end Integer リクエスト時より未来のUTCタイムスタンプ
trial_end String nowのみ指定可能
prorate Boolean 日割り課金を設定するかどうか

定期課金をキャンセル

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

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

レスポンス

{
  "canceled_at": 1433141780,
  "created": 1432965397,
  "current_period_end": 1435643801,
  "current_period_start": 1432965401,
  "customer": "cus_d43eb7c419c0da28ca0fd414108e",
  "id": "sub_19f6a2123363b514a743d1334109",
  "livemode": false,
  "metadata": null,
  "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)を行うことで、 キャンセルを取り消すことができます。終了日をむかえた定期課金は、自動的に削除されますのでご注意ください。

定期課金を削除

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

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

レスポンス

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

エラーレスポンス

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

定期課金をすぐに削除します。次回以降の課金は行われずに、一度削除した定期課金は、再び戻すことができません。 日割り設定(prorate)を有効化すると、削除時から現在の周期の終了日までの日割り分を算出し、同時に返金処理を行います。

引数 詳細
prorate Boolean 日割り課金を設定するかどうか

定期課金のリストを取得

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

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

レスポンス

{
  "count": 3,
  "data": [
    {
      "canceled_at": null,
      "created": 1432965397,
      "current_period_end": 1435643801,
      "current_period_start": 1432965401,
      "customer": "cus_ca2676897435d6476c4f6205a6f5",
      "id": "sub_80ac5ef1c0073a3e443a7d7deb93",
      "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
      },
      "resumed_at": null,
      "start": 1432965401,
      "status": "active",
      "trial_end": null,
      "trial_start": null,
      "prorate": false
    },
    {...},
    {...}
  ],
  "has_more": true,
  "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
offset Integer
plan String プランID
status String ステータス(active, trial, canceled, paused)
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

Token (トークン)

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

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

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

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

トークンを作成

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

curl https://api.pay.jp/v1/tokens \
-u sk_test_c62fade9d045b54cd76d7036: \
-d "card[number]=4242424242424242" \
-d "card[cvc]=123" \
-d "card[exp_month]=02" \
-d "card[exp_year]=2020"
import payjp
payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
payjp.Token.create(
    card={
        'number' : '4242424242424242',
        'cvc' : '123',
        'exp_month' : '2',
        'exp_year' : '2020'
    }
)
require 'payjp'
Payjp.api_key = 'sk_test_c62fade9d045b54cd76d7036'
Payjp::Token.create(
  :card => {
    :number => '4242424242424242',
    :cvc => '123',
    :exp_month => '2',
    :exp_year => '2020'
  }
)
\Payjp\Payjp::setApiKey("sk_test_c62fade9d045b54cd76d7036");
$card = array(
        "number" => "4242424242424242",
        "cvc" => "123",
        "exp_month" => "2",
        "exp_year" =>"2020"
);

\Payjp\Token::create(array(
              "card" => $card
));

var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.tokens.create({
  number: 4242424242424242,
  cvc: 123,
  exp_month: 2,
  exp_year: 2020
});
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Map<String, Object> tokenParams = new HashMap<String, Object>();
Map<String, Object> cardParams = new HashMap<String, Object>();
cardParams.put("number", "4242424242424242");
cardParams.put("cvc", "123");
cardParams.put("exp_month", "2");
cardParams.put("exp_year", "2020");
tokenParams.put("card", cardParams);
Token.create(tokenParams);

レスポンス

{
  "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": 2020,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_e3ccd4e0959f45e7c75bacc4be90",
    "livemode": false,
    "metadata": {},
    "last4": "4242",
    "name": null,
    "object": "card"
  },
  "created": 1442290383,
  "id": "tok_5ca06b51685e001723a2c3b4aeb4",
  "livemode": false,
  "object": "token",
  "used": false
}

エラーレスポンス

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

カード情報を指定して、トークンを生成します。

トークンはサーバーサイドからのリクエストでも生成可能ですが、通常は チェックアウトやpayjp.js を利用して、ブラウザ経由でパブリックキーとカード情報を指定して生成します。 トークンは二度以上使用することができません。

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

引数 詳細
card[number] String 必須
カード番号
card[exp_month] String 必須
有効期限月
card[exp_year] String 必須
有効期限年
card[cvc] String 3~4桁のCVCコード
card[address_state] String 都道府県
card[address_city] String 市区町村
card[address_line1] String 番地など
card[address_line2] String 建物名など
card[address_zip] String 郵便番号
card[country] String 2桁のISOコード(e.g. JP)
card[name] String カード保有者名(e.g. “YUI ARAGAKI”)

トークン情報を取得

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

curl https://api.pay.jp/v1/tokens/tok_eff34b780cbebd61e87f09ecc9c6 \
-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");
var payjp = require('payjp')('sk_test_c62fade9d045b54cd76d7036');
payjp.tokens.retrieve('tok_5ca06b51685e001723a2c3b4aeb4');
Payjp.apiKey = "sk_test_c62fade9d045b54cd76d7036";
Token.retrieve("tok_eff34b780cbebd61e87f09ecc9c6");

レスポンス

{
  "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": 2020,
    "fingerprint": "e1d8225886e3a7211127df751c86787f",
    "id": "car_e3ccd4e0959f45e7c75bacc4be90",
    "livemode": false,
    "metadata": {},
    "last4": "4242",
    "name": null,
    "object": "card"
  },
  "created": 1442290383,
  "id": "tok_5ca06b51685e001723a2c3b4aeb4",
  "livemode": false,
  "object": "token",
  "used": true
}

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"token"
id String tok_で始まる一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer このトークン作成時のUTCタイムスタンプ
used Boolean このトークンが使用済みかどうか
card Dictionary クレジットカードの情報
card[object] String オブジェクト名 値は"card"
card[id] String car_で始まる一意なオブジェクトを示す文字列
card[created] Integer カード作成時のUTCタイムスタンプ
card[name] String カード保有者名(e.g. YUI ARAGAKI)
card[last4] String カード番号の下四桁
card[exp_month] String 有効期限月
card[exp_year] String 有効期限年
card[brand] String カードブランド名
card[cvc_check] String CVCコードチェックの結果
card[fingerprint] String このクレジットカード番号に紐づけられた一意(他と重複しない)キー
card[address_city] String 市区町村
card[address_line1] String 番地など
card[address_line2] String 建物名など
card[address_state] String 都道府県
card[country] String 2桁のISOコード(e.g. JP)
card[address_zip] String 郵便番号
card[address_zip_check] String 郵便番号存在チェックの結果

Transfer (入金)

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

入金情報を取得

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

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

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

レスポンス

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

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"transfer"
id String tr_で始まる一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer この入金作成時のUTCタイムスタンプ
amount Integer 入金予定額
currency String 3文字のISOコード(現状 “jpy” のみサポート)
status String この入金の処理状態
charges List この入金に含まれる支払いのリスト
scheduled_date Date 入金予定日
summary Dictionary この入金に関する集計情報
summary[charge_count] Integer 支払い総数
summary[charge_fee] Integer 支払い手数料
summary[charge_gross] Integer 総売上
summary[net] Integer 差引額
summary[refund_amount] Integer 返金総額
summary[refund_count] Integer 返金総数
description String 概要
term_start Integer 集計期間開始時のUTCタイムスタンプ
term_end Integer 集計期間終了時のUTCタイムスタンプ
transfer_amount Integer 入金額
transfer_date Date 入金日
carried_balance Integer 繰越金

入金リストを取得

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

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

レスポンス

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

エラーレスポンス

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

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

引数 詳細
limit Integer 1〜100
offset Integer
status String ステータス(pending, paid, failed, canceled)
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

入金の内訳を取得

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

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

レスポンス

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

エラーレスポンス

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

入金内訳の支払いリストを取得します。リストは、直近で生成された順番に取得されます。

引数 詳細
limit Integer 1〜100
offset Integer
customer String 顧客ID
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

Event (イベント)

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

イベント情報を取得

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

レスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"event"
id String evnt_で始まる一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer このイベント作成時のUTCタイムスタンプ
type String このイベントのタイプ
pending_webhooks Integer 設定されたURLへの通知が完了していない(2xxのレスポンスが得られていない)webhookの数
data Dictionary このイベントに関連したデータ

イベントリストを取得

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

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

レスポンス

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

エラーレスポンス

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

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

引数 詳細
limit Integer 1〜100
offset Integer
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 ここに指定したタイムスタンプ以前に作成されたデータを取得

Product (プロダクト)

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

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

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

プロダクトを作成

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

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

レスポンス

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

エラーレスポンス

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

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

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

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

引数 詳細
amount Integer 必須
50~9,999,999の整数
currency String 必須
3文字のISOコード(現状 “jpy” のみサポート)
invalid_after Integer このプロダクトの有効日時を示す、リクエスト時より未来のUTCタイムスタンプ
capture Boolean このプロダクトと紐づいた支払いを作成した時に、支払い処理を確定するかどうか (falseの場合、カードの認証と支払い額の確保のみ行う)
metadata[display_name] Object PAY IDでの購入者に表示されるプロダクト名
metadata Object キーバリューの任意データ

プロダクト情報を取得

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

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

レスポンス

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

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"product"
id String 一意なオブジェクトを示す文字列
livemode Boolean 本番環境かどうか
created Integer このプロダクト作成時のUTCタイムスタンプ
amount Integer プロダクト金額
currency String 3文字のISOコード(現状 “jpy” のみサポート)
capture Boolean このプロダクトを購入時に通常、支払い処理を確定するかどうか (falseの場合、カードの認証と支払い額の確保のみ行う)
invalid_after Integer このプロダクトの有効日時を示す、リクエスト時より未来のUTCタイムスタンプ
metadata[display_name] Object PAY IDでの購入者に表示されるプロダクト名
metadata Object キーバリューの任意データ
paycode_url String このプロダクトのPAYCode(QRコード)画像が配置されてるURL

プロダクトを更新

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

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

レスポンス

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

エラーレスポンス

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

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

引数 詳細
invalid_after Integer このプロダクトの有効日時を示す、リクエスト時より未来のUTCタイムスタンプ
metadata[display_name] Object PAY IDでの購入者に表示されるプロダクト名
metadata Object キーバリューの任意データ

プロダクトを削除

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

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

レスポンス

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

エラーレスポンス

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

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

プロダクトリストを取得

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

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

レスポンス

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

エラーレスポンス

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

生成したプロダクトのリストを取得します。リストは、直近で生成された順番に取得されます。

引数 詳細
limit Integer 取得するデータ数の最大値(1~100まで)
offset Integer 基準点からのデータ取得を行う開始位置
since Integer ここに指定したタイムスタンプ以降に作成されたデータを取得
until Integer ここに指定したタイムスタンプ以前に作成されたデータを取得

Account (アカウント)

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

アカウント情報を取得

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

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

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

レスポンス

{
  "created": 1439706600,
  "email": "liveaccount@example.com",
  "id": "acct_8a27db83a7bf11a0c12b0c2833f",
  "merchant": {
    "bank_enabled": false,
    "brands_accepted": [
      "Visa",
      "MasterCard",
      "JCB",
      "American Express",
      "Diners Club",
      "Discover"
    ],
    "business_type": null,
    "charge_type": null,
    "contact_phone": 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_detail": null,
    "product_name": null,
    "product_type": null,
    "site_published": null,
    "url": null
  },
  "object": "account"
}

エラーレスポンス

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

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

プロパティ名 詳細
object String オブジェクト名 値は"account"
id String acct_で始まる一意なオブジェクトを示す文字列
email String メールアドレス
created Integer このアカウント作成時のUTCタイムスタンプ
merchant Dictionary マーチャントアカウントの詳細情報
merchant[object] String オブジェクト名 値は"merchant"
merchant[id] String acct_mch_で始まる一意なオブジェクトを示す文字列
merchant[bank_enabled] Boolean 入金先銀行口座情報が設定済みかどうか
merchant[brands_accepted] List 本番環境で利用可能なカードブランドのリスト
merchant[currencies_supported] List 対応通貨のリスト
merchant[default_currency] String 3文字のISOコード(現状 “jpy” のみサポート)
merchant[details_submitted] Boolean 本番環境申請情報が提出済みかどうか
merchant[business_type] String 業務形態
merchant[contact_phone] String 電話番号
merchant[country] String 所在国
merchant[charge_type] List 支払い方法種別のリスト
merchant[product_detail] String 販売商品の詳細
merchant[product_name] String 販売商品名
merchant[product_type] List 販売商品の種類リスト
merchant[livemode_enabled] Boolean 本番環境が有効かどうか
merchant[livemode_activated_at] Integer 本番環境が許可された日時のUTCタイムスタンプ
merchant[site_published] Boolean 申請対象のサイトがオープン済みかどうか
merchant[url] String 申請対象サイトのURL
merchant[created] Integer 登録日時