NAV Navbar
Logo
curl

1 はじめに

APIのエンドポイント

   https://api.paidy.com

トークンや決済を管理する際はPaidy APIを利用します。APIはJSON型のリクエストとレスポンスを使用するRESTエンドポイントです。

送信時の文字化けを避け、テキストがPaidyのユーザーインターフェイスに正しく表示されるよう、送信前にテキストがUTF-8でエンコードされていることを必ず確認するようにしてください。

このドキュメントでは、APIリクエストおよびレスポンスに関する情報のみをご紹介します。Paidy Checkoutを通じて決済データやトークンを作成する方法については、PaidyのHTMLドキュメントをご参照ください。

1-1 マーチャントキー

Paidy APIにはAPIキーが4つあり、テスト環境、運用時にそれぞれ別の秘密鍵と公開鍵を使用します。マーチャントのアカウントごとにテスト環境用、運用時用のAPIキーが用意されています。独立したテスト環境が存在するわけではなく、各用途のAPIキーを使い分けることでテスト環境時と運用時のトランザクションを切り替えることができます。

Paidy Checkoutで決済データを作成してAuthorizeを行う際は公開鍵を使用します。Paidyと通信を行う際にマーチャントのアカウントを識別できるよう、この鍵をマーチャントの設定に追加しておく必要があります。公開鍵はウェブページやモバイルアプリに貼り付けても構いません。

Paidy APIを利用して既存の決済を管理する際は秘密鍵を使用します。APIリクエストを送る際は必ずこの秘密鍵を認証情報に含めていただく必要があります。秘密鍵は公開したり誰かと共有したりすることはできません。

Paidy APIでは「pk_」で始まる公開鍵と「sk_」で始まる秘密鍵を使用します。これらの鍵はマーチャントダッシュボードにログインすれば確認できます。

1-2 リクエスト

通信はすべてHTTPSを介して行い、HTTP経由のリクエストはエラーになります。

リクエストを送信する際は必ずヘッダーに適切な認証情報を含める必要があり、さらに任意でAPIのバージョンを含めることもできます。

認証

ヘッダー例 

curl -X "POST" "https://api.paidy.com/payments/pay_WD1KIj4AALQAIMtZ/captures" \
     -H "Content-Type: application/json" \
     -H "Paidy-Version: 2018-04-10" \
     -H "Authorization: Bearer $secret_key" \

Paidyで認証を行う際は、Bearer Tokenによる認証が推奨されます。マーチャントダッシュボードにログインして秘密鍵を取得します。このマーチャントダッシュボードにはテスト用の鍵と運用時に使用する鍵が両方ともリストアップされていますので、用途に合った秘密鍵を選択するようにしてください。

APIキーは「Bearer」で始まるAuthorization HTTPリクエストヘッダの形で追加します。

リクエストにこの認証情報が含まれていない場合、レスポンスとして401-Unauthorized HTTP Statusコードが返ってきます。

APIのバージョン

APIのバージョンを指定するには、ヘッダーにPaidy- Versionフィールドを追加します。現行のバージョンの値は2018-04-10です。他の設定によっては、このPaidy- Versionフィールドが欠けている場合にエラーコードを伴うレスポンスが返ってくることになります。

1-3 レスポンス

レスポンスコード

Paidy APIでは通常のHTTPレスポンスコードを使用してリクエストの結果を示します。HTTPレスポンスコードは、レスポンスのリクエストヘッダに含まれています。

代表的なレスポンスコードは次の通りです。

コード 説明
200 - OK エラーなくリクエストが処理されました。
400 - Bad Request 必須パラメーターの欠損などが原因でリクエストに失敗しました。
401 - Unauthorized 有効なAPIキーが提供されませんでした。
403 - Forbidden 対象の決済が許可していない操作をリクエストしました。例えば、すでにクローズ状態になっている決済をCaptureしようとする、あるいは状態がAUTHORIZEDである決済に対してRefundを実行しようとすると、このエラーが発生します。
404 - Not Found リクエストしたリソースが見つかりませんでした。例えば、不正なPayment IDを使用して決済をUpdateしようとすると、このエラーが発生します。
409 - Conflict 状態の競合が生じるため、リクエストを処理できませんでした。例えば、すでにCLOSEDの状態になっている決済をCloseしようとすると、このエラーが発生します。

こちらの表では代表的なHTTPステータスコードだけをピックアップしています。包括的なリストについてはHTTPプロトコルのオンラインドキュメント参照ください。

エラー

エラーの例 

  {
    "reference":"err_NzM1YzU3MDdlNDE1NDk3OTg2ZDZiNmM1MWRhNGUyOGQ=",
    "status":"400",
    "code":"request_entity.invalid",
    "title":"Request entity validation failed",
    "description":"Validation of the request entity failed"
  }

Paidy APIでは、HTTPステータスコードと併せてエラーオブジェクトを使用してエラーを扱います。 APIリクエストが失敗するとレスポンスのステータスコードが400番台あるいは500番台になるとともに、レスポンスボディにエラーオブジェクトが含められます。

エラーオブジェクトのフィールドは次の通りです。

属性名データ型説明
referencestringエラーコード。
statusstringHTTPレスポンスコード。
codestring発生したエラーの種類を示すコード。現段階におけるエラーコードは下の表の通りです。
titlestring発生したエラーの種類を示すテキスト。
descriptionstringエラーの詳細を示す説明文。

エラーコード:

コード 説明
404 リクエストしたリソースが見つかりませんでした。
authentication.failed Paidyに認証は成功しませんでした。
authorization.failed Paidyに決済のAuthorizeは成功しませんでした。
method.invalid HTTPメソッドを使用できません。
media_type.unsupported サポートされていないメディアタイプ 。
request_content.malformed リクエスト本文のフォーマットが正しくありません。
service.conflict HTTPメソッドを使用できません。
service.exception サービス内部エラー。
service.forbidden 許可されていませんでした。
request_entity.invalid エンティティの検証失敗。
version.unknown リクエストしたバージョンは存在しません。

こちらは現段階で受け取る可能性があるエラーコードのみをまとめたリストです。新しいエラーコードが適宜追加される可能性があり、こちらにリストアップされているもの以外のコードを受け取る場合がありますので、ご注意ください。

2 決済

Paidyには次のように2種類の決済があります。

トークンはPaidy Checkoutを通じて作成されますが、（トークンを使って作成する）定期購入の決済はAPI経由で開始します。Paidy API経由で行える操作は次の通りです。

定期購入の決済はAPI経由で作成します。しかし単一の決済はPaidy Checkoutを通じて作成します。単一の決済データを作成する方法については、PaidyのHTMLドキュメントをご参照ください。

2-1 Paymentオブジェクト

オブジェクトの例

{
 "id":"pay_WD1KIj4AALQAIMtZ",
 "created_at":"2018-06-14T05:27:10.063Z",
 "expires_at":"2018-07-14T05:27:10.063Z",
 "amount":39800,
 "currency":"JPY",
 "description":" ",
 "store_name":"Paidy sample store",
 "test":true,
 "status":"closed",
 "tier":"classic",
 "buyer":{
    "name1":"山田　太郎",
    "name2":"ヤマダ　タロウ",
    "email":"yamada@paidy.com",
    "phone":"818000000001"
 },
 "order":{
    "items":[
     {
       "id":"PDI001",
       "title":"Paidyスニーカー",
       "description":" ",
       "unit_price":10000,
       "quantity":1
     },{
       "id":"EXC002",
       "title":"エクスコスニーカー",
       "description":" ",
       "unit_price":15000,
       "quantity":2
     },{
       "id": "CPN001",
       "title": "Discount",
       "description":" ",
       "unit_price":-1000,
       "quantity":1
     }
    ],
    "tax":300,
    "shipping":500,
    "order_ref":"88e021674",
    "updated_at":null
 },
 "shipping_address":{
    "line1":"AXISビル10F",
    "line2":"六本木4-22-1",
    "city":"港区",
    "state":"東京都",
    "zip":"106-2004"
 },
 "captures":[
    {
     "id":"cap_WFIk5yIAACIAC6n3",
     "created_at":"2018-06-15T05:06:47.189Z",
     "amount":39800,
     "tax":300,
     "shipping":500,
     "items":[
       {
         "id":"PDI001",
         "title":"Paidyスニーカー",
         "description":" ",
         "unit_price":10000,
         "quantity":1
       },{
         "id":"EXC002",
         "title":"エクスコスニーカー",
         "description":" ",
         "unit_price":15000,
         "quantity":2
       },{
         "id": "CPN001",
         "title": "Discount",
         "description":" ",
         "unit_price":-1000,
         "quantity":1
       }
     ],
     "metadata":{"key1":"value1","key2":"value2"}
    }
 ], 
 "refunds":[],
 "metadata":{}
}

各決済は「pay_」で始まる一意のPayment IDで識別されます。

属性名 データ型 説明
id string Paidyが割り当てる一意のPayment ID。 このPayment IDは必ず「pay_」で始まります。
created_at string 決済データが作成された日時（ISO 8601のフォーマットに準じるUTC）。
expires_at string 決済が自動的に失効する日時。ISO 8601のフォーマットに準じるUTC）。失効後はCaptureを実行できなくなります。
amount double 税、送料を含み、値引きの対象であればさらにそれを適用した後の決済総額。
currency string 決済額の基準となる通貨を示す、ISO4217通貨コードに準じた値（JPYに設定）。
description string 決済についての説明文。
store_name string マーチャントの店舗名。MyPaidyとマーチャントダッシュボードの両方に表示されるフィールドです。
test boolean 決済がテスト用（テスト用のAPIキーを利用して作成された）かどうかを示します。
status string 決済オブジェクトの現在の状態。認証が成功した決済のstatusは「AUTHORIZED」になります。Captureが成功した決済のstatusは「CLOSED」になります。
tier string Paidyが割り当てる決済のタイプ。 初期値は「classic」に設定されています。
buyer object Buyerオブジェクト。
order object Orderオブジェクト。マーチャントがオブジェクトに渡した、注文/カートの詳細情報。
shipping_address object Shipping_addressオブジェクト。
captures object Capturesオブジェクト。 Capture（回収）した支払いを示す、オブジェクトの配列。
refunds object Refundsオブジェクト。 Refund（払い戻し）した支払いを示す、オブジェクトの配列。
metadata string マーチャント定義のメタデータ。キーと値のセットを20件まで追加できます。

2-1-1 Buyerオブジェクト

属性名 データ型 説明
name1 string コンシューマーの氏名（漢字表記）。 姓と名をスペースで区切る必要があります(例：山田 太郎）。
name2 string コンシューマーの氏名（カタカナ表記）。 姓と名をスペースで区切る必要があります（例：ヤマダ タロウ）。
email string コンシューマーのメールアドレス。
phone string コンシューマーの電話番号（例：09011112222）。コンシューマーがテキストメッセージを受信できる日本の携帯電番号です。

2-1-2 Orderオブジェクト

属性名 データ型 説明
items object Itemsオブジェクト。この決済のすべての注文商品を示す、オブジェクトの配列。このオブジェクトを使用し、値引き額を示す負の値をunit_priceにセットした状態で「discount order item（値引き項目）」を作成することでも、コンシューマーの注文商品を値引きすることができます。
tax double 注文にかかる消費税。
shipping double 注文にかかる配送料。
order_ref string マーチャントが割り当てる注文IDまたはカートID。
updated_at string 現在は使用されていません。

2-1-3 Itemsオブジェクト

属性名 データ型 説明
id string 商品ID。任意のフィールドであり、送信後はマーチャントダッシュボードとMyPaidyの両方に表示されます。
title string 注文商品（または値引き/クーポン）の名称。任意のフィールドですが、ペイロードに含めて送信することが推奨されます。送信後はマーチャントダッシュボードとMyPaidyの両方に表示され、注文商品を識別できるようになります。送信しない場合、注文商品の数量と単価以外は表示されません。
description string 注文商品の説明。MyPaidyやマーチャントダッシュボードには表示されないフィールドですので、ご注意ください。
unit_price double 注文商品の単価。unit_priceに負の値をセットすることで、値引きを表す項目にすることができます。
quantity integer 注文商品の数。

2-1-4 Shipping_addressオブジェクト

属性名 データ型 説明
line1 string 建物名と部屋番号（国内の住所の場合）。
line2 string 番地（国内の住所の場合）。
city string 市区町村。
state string 都道府県。
zip string 郵便番号（NNN-NNNN形式）。

2-1-5 Capturesオブジェクト

属性名 データ型 説明
id string Paidyが割り当てる一意のCapture ID。 このCapture IDは必ず「cap_」で始まります。
created_at string Captureオブジェクトが生成された日時（ISO 8601のフォーマットに準じるUTC）。
amount double Captureを行う金額。
tax double Captureを行う消費税 。
shipping double Captureを行う配送料。
items object Captureを行う注文商品を示す、[オブジェクト](#orderitems_object)の配列。
metadata string マーチャント定義のメタデータ。キーと値のセットを20件まで追加できます。

2-1-6 Refundsオブジェクト

属性名 データ型 説明
id string Paidyが割り当てる一意のRefund ID。このRefund IDは必ず「ref_」で始まります。
created_at string Refundオブジェクトが生成された日時（ISO 8601のフォーマットに準じるUTC）。
capture_id string Refundの対象となる商品のCapture ID（Capture IDは必ず「cap_」で始まります）。RefundはいずれかのCaptureを指定して行う必要があります。
amount double Refundを行う金額。
reason string Refundを行う理由。
metadata string マーチャント定義のメタデータ。キーと値のセットを20件まで追加できます。

2-2 定期購入の決済を作成

リクエストの例

curl -X "POST" "https://api.paidy.com/payments" \
     -H "Content-Type: application/json" \
     -H "Paidy-Version: 2018-04-10" \
     -H "Authorization: Bearer $secret_key" \
     -d $'{
      "token_id": "tok_WL0GoQwAAAoA1beX",
      "amount": 12500,
      "currency": "JPY",
      "description": " ",
      "store_name": "Paidy sample store",
      "buyer_data": {
        "age": 29,
        "order_count": 1000,
        "ltv": 250000,
        "last_order_amount": 20000,
        "last_order_at": 20
      },
      "order": {
        "items": [{
                "quantity": 1,
                "id": "PDI001",
                "title": "Paidyスニーカー",
                "description": "Paidyスニーカー",
                "unit_price": 12000
            }],
        "tax": 300,
        "shipping": 200,
        "order_ref": "your_order_ref"
      },
      "metadata": {},
      "shipping_address": {
        "line1": "AXISビル 10F",
        "line2": "六本木4-22-1",
        "state": "港区",
        "city": "東京都",
        "zip": "106-2004"
      }
}'

レスポンスの例

{
 "id":"pay_WD1KIj4AALQAIMtZ",
 "created_at":"2018-06-14T05:27:10.063Z",
 "expires_at":"2018-07-14T05:27:10.063Z",
 "amount":12500,
 "currency":"JPY",
 "description":" ",
 "store_name":"Paidy sample store",
 "test":true,
 "status":"closed",
 "tier":"classic",
 "buyer":{
    "name1":"山田　太郎",
    "name2":"ヤマダ　タロウ",
    "email":"yamada@paidy.com",
    "phone":"818000000001"
 },
 "order":{
    "items":[
     {
       "id":"PDI001",
       "title":"Paidyスニーカー",
       "description":"Paidyスニーカー",
       "unit_price":12000,
       "quantity":1
     }
    ],
    "tax":300,
    "shipping":200,
    "order_ref":"your_order_ref",
    "updated_at":null
 },
 "shipping_address":{
    "line1":"AXISビル10F",
    "line2":"六本木4-22-1",
    "city":"港区",
    "state":"東京都",
    "zip":"106-2004"
 },
 "captures":[],
 "refunds":[],
 "metadata":{}
}

リクエストを送信することで、トークンを使用して決済データを新しく作成することができますが、その際、トークンとコンシューマーのstatusがどちらも「ACTIVE」でなければなりません。

定期購入の決済はAPI経由で作成します。しかし単一の決済はPaidy Checkoutを通じて作成します。このドキュメントでは、APIリクエストおよびレスポンスに関する情報のみをご紹介します。単一の決済データを作成する方法については、PaidyのHTMLドキュメントをご参照ください。

リクエスト

/payments にPOSTリクエストを送信します。 Authenticationに必要なデータをリクエストヘッダに含めます。 任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディ:

属性名 データ型 必須 説明
token_id string はい Paidyが生成する、「tok_」で始まるトークンID。
amount double はい 税、送料を含む決済総額。
currency string はい 決済で使用する通貨を示す、ISO4217通貨コードに準じた値です。JPYをセットしてください。
description string いいえ 決済についての説明を示します。現在のところ、MyPaidyやマーチャントダッシュボードに表示されることはありません。
store_name string いいえ MyPaidyとマーチャントダッシュボードに表示される、マーチャントの店舗名です。
buyer_data object はい コンシューマーの購入履歴に関する情報を含むbuyer_dataオブジェクト。
order object はい 注文についてのデータ.
metadata string いいえ マーチャントが定義する、オブジェクトについてのデータです。 このフィールドにはキーと値のセットを20件まで追加できます。
shipping_address object はい コンシューマーの配送先.

Buyer_dataオブジェクト:

属性名 データ型 必須 説明
age integer はい コンシューマーがマーチャントの店舗でアカウントを作成してから経過した日数。
order_count integer はい コンシューマーがマーチャントと取引を開始してから現在までに行った注文総数。キャンセル、否決、返金された取引はこれに含めず、またPaidy決済も除外します。
ltv double はい Lifetime value（顧客の生涯価値）の略語であり、コンシューマーがマーチャントと取引を開始してから現在までに行った注文の総額（円）を示します。キャンセル、否決、返金された取引はこれに含めず、またPaidy決済も除外します。
last_order_amount double はい 最後に行った注文の金額（円）。Paidy決済は除外します。
last_order_at integer はい コンシューマーが最後に注文してから経過した日数、またPaidy決済も除外します。

Orderオブジェクト:

属性名 データ型 必須 説明
items object はい Itemsオブジェクト。この決済のすべての注文商品を示す、オブジェクトの配列。このオブジェクトを使用し、値引き額を示す負の値をunit_priceにセットした状態で「discount order item（値引き項目）」を作成することでも、コンシューマーの注文商品を値引きすることができます。
tax double いいえ 注文にかかる消費税。
shipping double いいえ 注文にかかる配送料。
order_ref string いいえ マーチャントが割り当てる注文IDまたはカートID。

Itemsオブジェクト:

属性名 データ型 必須 説明
quantity integer はい 注文商品の数。
id string いいえ 商品ID。任意のフィールドであり、送信後はマーチャントダッシュボードとMyPaidyの両方に表示されます。
title string いいえ 注文商品（または値引き/クーポン）の名称。任意のフィールドですが、ペイロードに含めて送信することが推奨されます。送信後はマーチャントダッシュボードとMyPaidyの両方に表示され、注文商品を識別できるようになります。送信しない場合、注文商品の数量と単価以外は表示されません。
description string いいえ 注文商品の説明。MyPaidyやマーチャントダッシュボードには表示されないフィールドですので、ご注意ください。
unit_price double はい 注文商品の単価。unit_priceに負の値をセットすることで、値引きを表す項目にすることができます。

Shipping_addressオブジェクト:

属性名 データ型 必須 説明
line1 string いいえ 建物名と部屋番号（国内の住所の場合）。
line2 string いいえ 番地（国内の住所の場合）。
city string いいえ 市区町村。
state string いいえ 都道府県。
zip string はい 郵便番号（NNN-NNNN形式）。
重要：zipは必須フィールドです。addressオブジェクトに含まれる他のフィールドはいずれも必須項目ではありませんが、このzipフィールドとともに他のフィールドを1つ以上指定する必要があります。shipping addressのフィールドを2つ提供しなければ、リクエストは失敗します。

レスポンス

リクエストが成功すると、paymentオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
400
request_content.malformed		 必須フィールドのいずれかが欠けている、あるいは書式が正しくありません。
いずれかのフィールドの書式が正しくない場合、エラーのタイトルは「Validation of the request content failed（リクエスト内容の検証に失敗）」になります。詳細については、errorオブジェクトのdescriptionフィールドを参照してください。
必須フィールドのいずれかがリクエストに含まれていない場合、エラーのタイトルは「Malformed request content（リクエスト内容の形式が不正）」になります。
400
version.unknown		 間違ったAPIのバージョン番号をヘッダーで指定しているか、Paidy-Versionフィールドが欠けています。 現行のバージョンの値は2018-04-10です。
401
authentication.failed		 必要な認証情報がリクエストヘッダに含まれていません。Paidyで認証を行うために、適切な認証情報を各リクエストに含める必要があります。APIキーをヘッダーに含めた状態でリクエストを再送信してください。
403
authorization.failed		 ヘッダーに設定しているAPIキーが正しくありません。 マーチャントダッシュボードにログインして正しいキーを取得してください。

2-3 決済のCapture

リクエストの例

curl -X "POST" "https://api.paidy.com/payments/pay_WD1KIj4AALQAIMtZ/captures" \
 -H "Content-Type: application/json" \
 -H "Paidy-Version: 2018-04-10" \
 -H "Authorization: Bearer $secret_key" \
 -d $'{"metadata": {"key1": "value1","key2": "value2"}}'

レスポンスの例

{
 "id":"pay_WD1KIj4AALQAIMtZ",
 "created_at":"2018-06-14T05:27:10.063Z",
 "expires_at":"2018-07-14T05:27:10.063Z",
 "amount":39800,
 "currency":"JPY",
 "description":" ",
 "store_name":"Paidy sample store",
 "test":true,
 "status":"closed",
 "tier":"classic",
 "buyer":{
    "name1":"山田　太郎",
    "name2":"ヤマダ　タロウ",
    "email":"yamada@paidy.com",
    "phone":"818000000001"
 },
 "order":{
    "items":[
     {
       "id":"PDI001",
       "title":"Paidyスニーカー",
       "description":" ",
       "unit_price":10000,
       "quantity":1
     },{
       "id":"EXC002",
       "title":"エクスコスニーカー",
       "description":" ",
       "unit_price":15000,
       "quantity":2
     },{
       "id": "CPN001",
       "title": "Discount",
       "description":" ",
       "unit_price":-1000,
       "quantity":1
     }
    ],
    "tax":300,
    "shipping":500,
    "order_ref":"88e021674",
    "updated_at":null
 },
 "shipping_address":{
    "line1":"AXISビル10F",
    "line2":"六本木4-22-1",
    "city":"港区",
    "state":"東京都",
    "zip":"106-2004"
 },
 "captures":[
    {
     "id":"cap_WFIk5yIAACIAC6n3",
     "created_at":"2018-06-15T05:06:47.189Z",
     "amount":39800,
     "tax":300,
     "shipping":500,
     "items":[
       {
         "id":"PDI001",
         "title":"Paidyスニーカー",
         "description":" ",
         "unit_price":10000,
         "quantity":1
       },{
         "id":"EXC002",
         "title":"エクスコスニーカー",
         "description":" ",
         "unit_price":15000,
         "quantity":2
       },{
         "id": "CPN001",
         "title": "Discount",
         "description":" ",
         "unit_price":-1000,
         "quantity":1
       }
     ],
     "metadata":{"key1":"value1","key2":"value2"}
    }
 ], 
 "refunds":[],
 "metadata":{}
}

コンシューマーに請求を行う準備ができたら、マーチャントはCaptureリクエストを送信します。

Captureできるのはstatusが「AUTHORIZED」の決済だけです。リクエストがAuthorizeされると、有効期間が自動的に設定されますのでご注意ください。この有効期間は利用規約に明記されており、期限が過ぎると注文をCaptureできなくなります。

リクエスト

/payments/{id}/captures（{id}の部分はPayment ID）にPOSTリクエストを送信します。 Authenticationに必要なデータをリクエストヘッダに含めます。 任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディは空にしておくか、あるいはmetadataフィールドを含めることもできます。このフィールドには、captureオブジェクトについての補足的な情報を示す、キーと値のセットを20件まで追加できます。

重要：Captureリクエストのボディにフィールドを含めない場合でも、波括弧を付けて送信する必要があります。システムがチェックを行う際、この波括弧が無ければリクエストが失敗します。

レスポンス

リクエストが成功すると、paymentオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
400
request_content.malformed		 必須フィールドのいずれかが欠けている、あるいは書式が正しくありません。
いずれかのフィールドの書式が正しくない場合、エラーのタイトルは「Validation of the request content failed（リクエスト内容の検証に失敗）」になります。詳細については、errorオブジェクトのdescriptionフィールドを参照してください。
必須フィールドのいずれかがリクエストに含まれていない、あるいはリクエストボディに波括弧が含まれていない場合、「Malformed request content（リクエスト内容の形式が不正）」というエラーが返されます。
400
payment.authorization.expired		 決済がすでにクローズ状態になっている（有効期限が切れているため）。決済の有効期限が切れると、Captureを実行できなくなります。
400
version.unknown		 間違ったAPIのバージョン番号をヘッダーで指定しているか、Paidy-Versionフィールドが欠けています。 現行のバージョンの値は2018-04-10です。
401
authentication.failed		 必要な認証情報がリクエストヘッダに含まれていません。Paidyで認証を行うために、適切な認証情報を各リクエストに含める必要があります。APIキーをヘッダーに含めた状態でリクエストを再送信してください。
403
authorization.failed		 ヘッダーに設定しているAPIキーが正しくありません。 マーチャントダッシュボードにログインして正しいキーを取得してください。
403
service.forbidden		 すでにクローズ状態になっているリクエストに対してCaptureを実行しようとしました。Captureの対象にできるのは、ステータスがAUTHORIZEDであるリクエストだけです。
404
404		 間違ったPayment IDをURIパラメーターとして使用しています。

2-4 決済のRefund

リクエストの例

curl -X "POST" "https://api.paidy.com/payments/pay_WD1KIj4AALQAIMtZ/refunds" \
     -H "Content-Type: application/json" \
     -H "Paidy-Version: 2018-04-10" \
     -H "Authorization: Bearer $secret_key" \
     -d "{\"capture_id\":\"cap_WFIk5yIAACIAC6n3",\"amount\":10000}"

レスポンスの例

{
 "id":"pay_WD1KIj4AALQAIMtZ",
 "created_at":"2018-06-14T05:27:10.063Z",
 "expires_at":"2018-07-14T05:27:10.063Z",
 "amount":39800,
 "currency":"JPY",
 "description":" ",
 "store_name":"Paidy sample store",
 "test":true,
 "status":"closed",
 "tier":"classic",
 "buyer":{
    "name1":"山田　太郎",
    "name2":"ヤマダ　タロウ",
    "email":"yamada@paidy.com",
    "phone":"818000000001"
 },
 "order":{
    "items":[
     {
       "id":"PDI001",
       "title":"Paidyスニーカー",
       "description":" ",
       "unit_price":10000,
       "quantity":1
     },{
       "id":"EXC002",
       "title":"エクスコスニーカー",
       "description":" ",
       "unit_price":15000,
       "quantity":2
     },{
       "id": "CPN001",
       "title": "Discount",
       "description":" ",
       "unit_price":-1000,
       "quantity":1
     }
    ],
    "tax":300,
    "shipping":500,
    "order_ref":"88e021674",
    "updated_at":null
 },
 "shipping_address":{
    "line1":"AXISビル10F",
    "line2":"六本木4-22-1",
    "city":"港区",
    "state":"東京都",
    "zip":"106-2004"
 },
 "captures":[
    {
     "id":"cap_WFIk5yIAACIAC6n3",
     "created_at":"2018-06-15T05:06:47.189Z",
     "amount":39800,
     "tax":300,
     "shipping":500,
     "items":[
       {
         "id":"PDI001",
         "title":"Paidyスニーカー",
         "description":" ",
         "unit_price":10000,
         "quantity":1
       },{
         "id":"EXC002",
         "title":"エクスコスニーカー",
         "description":" ",
         "unit_price":15000,
         "quantity":2
       },{
         "id": "CPN001",
         "title": "Discount",
         "description":" ",
         "unit_price":-1000,
         "quantity":1
       }
     ],
     "metadata":{"key1":"value1","key2":"value2"}
    }
 ], 
 "refunds":[
    {
     "id":"ref_WFImZyIAAD8AC6pC",
     "created_at":"2018-06-15T05:13:11.800Z",
     "capture_id":"cap_WFIk5yIAACIAC6n3",
     "amount":10000,
     "reason":"unknown",
     "metadata":{}
    }
 ],
 "metadata":{}
}

Paidy決済の全額あるいは一部を払い戻します。 RefundはCapture済みの決済に対してのみ実行できます。

リクエスト

/payments/{id}/refunds（{id}の部分はPayment ID）にPOSTリクエストを送信します。 Authenticationに必要なデータをリクエストヘッダに含めます。 任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストデータ：

属性名 データ型 必須 説明
capture_id string はい Refundリクエストは特定のCaptureを指定して行うため、リクエストにcapture_idを含める必要があります。このCapture IDは必ず「cap_」で始まります。
amount double いいえ Refundを行う金額。 Paidy APIではこのフィールドの値を基にしてリクエストがPartial Refund（一部払い戻し）なのかFull Refund（全額払い戻し）なのかを判断します。 amountフィールドを指定しない場合、Capture済みの金額すべてが払い戻しの対象になります。
reason string いいえ Refundを行う理由。
metadata string いいえ オブジェクトを表す構造化データを追加する際にこのフィールドを使用します。キーと値のセットを20件まで追加できます。

レスポンス

リクエストが成功すると、paymentオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
400
request_content.malformed		 必須フィールドのいずれかが欠けている、あるいは書式が正しくありません。
いずれかのフィールドの書式が正しくない場合、エラーのタイトルは「Validation of the request content failed（リクエスト内容の検証に失敗）」になります。詳細については、errorオブジェクトのdescriptionフィールドを参照してください。
必須フィールドのいずれかがリクエストに含まれていない場合、エラーのタイトルは「Malformed request content（リクエスト内容の形式が不正）」になります。
400
payment.refund.amount		 払い戻そうとした金額が正しくありません。
400
payment.refund.captureId		 リクエストボディ内のCapture IDが間違っています。
400
version.unknown		 間違ったAPIのバージョン番号をヘッダーで指定しているか、Paidy-Versionフィールドが欠けています。 現行のバージョンの値は2018-04-10です。
401
authentication.failed		 必要な認証情報がリクエストヘッダに含まれていません。Paidyで認証を行うために、適切な認証情報を各リクエストに含める必要があります。APIキーをヘッダーに含めた状態でリクエストを再送信してください。
403
authorization.failed		 ヘッダーに設定しているAPIキーが正しくありません。 マーチャントダッシュボードにログインして正しいキーを取得してください。
403
service.forbidden		 全額分の払い戻しがすでに完了している決済に対してRefundを実行しようとしています。
404
404		 間違ったPayment IDをURIパラメーターとして使用しています。

2-5 決済データの取得

リクエストの例

curl -X "GET" "https://api.paidy.com/payments/pay_WD1KIj4AALQAIMtZ" \
     -H "Content-Type: application/json" \
     -H "Paidy-Version: 2018-04-10" \
     -H "Authorization: Bearer $secret_key" \
     -d "{}"

レスポンスの例

{
 "id":"pay_WD1KIj4AALQAIMtZ",
 "created_at":"2018-06-14T05:27:10.063Z",
 "expires_at":"2018-07-14T05:27:10.063Z",
 "amount":39800,
 "currency":"JPY",
 "description":" ",
 "store_name":"Paidy sample store",
 "test":true,
 "status":"closed",
 "tier":"classic",
 "buyer":{
    "name1":"山田　太郎",
    "name2":"ヤマダ　タロウ",
    "email":"yamada@paidy.com",
    "phone":"818000000001"
 },
 "order":{
    "items":[
     {
       "id":"PDI001",
       "title":"Paidyスニーカー",
       "description":" ",
       "unit_price":10000,
       "quantity":1
     },{
       "id":"EXC002",
       "title":"エクスコスニーカー",
       "description":" ",
       "unit_price":15000,
       "quantity":2
     },{
       "id": "CPN001",
       "title": "Discount",
       "description":" ",
       "unit_price":-1000,
       "quantity":1
     }
    ],
    "tax":300,
    "shipping":500,
    "order_ref":"88e021674",
    "updated_at":null
 },
 "shipping_address":{
    "line1":"AXISビル10F",
    "line2":"六本木4-22-1",
    "city":"港区",
    "state":"東京都",
    "zip":"106-2004"
 },
 "captures":[
    {
     "id":"cap_WFIk5yIAACIAC6n3",
     "created_at":"2018-06-15T05:06:47.189Z",
     "amount":39800,
     "tax":300,
     "shipping":500,
     "items":[
       {
         "id":"PDI001",
         "title":"Paidyスニーカー",
         "description":" ",
         "unit_price":10000,
         "quantity":1
       },{
         "id":"EXC002",
         "title":"エクスコスニーカー",
         "description":" ",
         "unit_price":15000,
         "quantity":2
       },{
         "id": "CPN001",
         "title": "Discount",
         "description":" ",
         "unit_price":-1000,
         "quantity":1
       }
     ],
     "metadata":{"key1":"value1","key2":"value2"}
    }
 ], 
 "refunds":[
    {
     "id":"ref_WFImZyIAAD8AC6pC",
     "created_at":"2018-06-15T05:13:11.800Z",
     "capture_id":"cap_WFIk5yIAACIAC6n3",
     "amount":10000,
     "reason":"unknown",
     "metadata":{}
    }
 ],
 "metadata":{}
}

決済の詳細情報を確認する際はpaymentsエンドポイントを利用します。

これは決済の現在の状態、実行したRefundについての情報など、決済の詳細情報をすべて取得できるエンドポイントです。Payment IDが有効であればデータを取得できます。

リクエスト

/payments/{id}（{id}の部分はPayment ID）にGETリクエストを送信します。 Authenticationに必要なデータをリクエストヘッダに含めます。 任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディは空のままにしてください。

レスポンス

リクエストが成功すると、paymentオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
400
request_content.malformed		 必須フィールドのいずれかが欠けている、あるいは書式が正しくありません。
いずれかのフィールドの書式が正しくない場合、エラーのタイトルは「Validation of the request content failed（リクエスト内容の検証に失敗）」になります。詳細については、errorオブジェクトのdescriptionフィールドを参照してください。
必須フィールドのいずれかがリクエストに含まれていない場合、エラーのタイトルは「Malformed request content（リクエスト内容の形式が不正）」になります。
400
version.unknown		 間違ったAPIのバージョン番号をヘッダーで指定しているか、Paidy-Versionフィールドが欠けています。 現行のバージョンの値は2018-04-10です。
401
authentication.failed		 必要な認証情報がリクエストヘッダに含まれていません。Paidyで認証を行うために、適切な認証情報を各リクエストに含める必要があります。APIキーをヘッダーに含めた状態でリクエストを再送信してください。
403
authorization.failed		 ヘッダーに設定しているAPIキーが正しくありません。 マーチャントダッシュボードにログインして正しいキーを取得してください。
404
404		 間違ったPayment IDをURIパラメーターとして使用しています。

2-6 決済のUpdate

リクエストの例

curl -X "PUT" "https://api.paidy.com/payments/pay_WD1KIj4AALQAIMtZ" \
     -H "Content-Type: application/json" \
     -H "Paidy-Version: 2018-04-10" \
     -H "Authorization: Bearer $secret_key" \
     -d "{\"order_ref":"88e021674",\"description":"スニーカー"\}"

レスポンスの例

{
 "id":"pay_WD1KIj4AALQAIMtZ",
 "created_at":"2018-06-14T05:27:10.063Z",
 "expires_at":"2018-07-14T05:27:10.063Z",
 "amount":39800,
 "currency":"JPY",
 "description":" ",
 "store_name":"Paidy sample store",
 "test":true,
 "status":"closed",
 "tier":"classic",
 "buyer":{
    "name1":"山田　太郎",
    "name2":"ヤマダ　タロウ",
    "email":"yamada@paidy.com",
    "phone":"818000000001"
 },
 "order":{
    "items":[
     {
       "id":"PDI001",
       "title":"Paidyスニーカー",
       "description":" ",
       "unit_price":10000,
       "quantity":1
     },{
       "id":"EXC002",
       "title":"エクスコスニーカー",
       "description":" ",
       "unit_price":15000,
       "quantity":2
     },{
       "id": "CPN001",
       "title": "Discount",
       "description":" ",
       "unit_price":-1000,
       "quantity":1
     }
    ],
    "tax":300,
    "shipping":500,
    "order_ref":"88e021674",
    "updated_at":null
 },
 "shipping_address":{
    "line1":"AXISビル10F",
    "line2":"六本木4-22-1",
    "city":"港区",
    "state":"東京都",
    "zip":"106-2004"
 },
 "captures":[
    {
     "id":"cap_WFIk5yIAACIAC6n3",
     "created_at":"2018-06-15T05:06:47.189Z",
     "amount":39800,
     "tax":300,
     "shipping":500,
     "items":[
       {
         "id":"PDI001",
         "title":"Paidyスニーカー",
         "description":" ",
         "unit_price":10000,
         "quantity":1
       },{
         "id":"EXC002",
         "title":"エクスコスニーカー",
         "description":" ",
         "unit_price":15000,
         "quantity":2
       },{
         "id": "CPN001",
         "title": "Discount",
         "description":" ",
         "unit_price":-1000,
         "quantity":1
       }
     ],
     "metadata":{"key1":"value1","key2":"value2"}
    }
 ], 
 "refunds":[
    {
     "id":"ref_WFImZyIAAD8AC6pC",
     "created_at":"2018-06-15T05:13:11.800Z",
     "capture_id":"cap_WFIk5yIAACIAC6n3",
     "amount":10000,
     "reason":"unknown",
     "metadata":{}
    }
 ],
 "metadata":{}
}

決済のorder_refとdescriptionとmetadataフィールドを更新する際は/payments/{id}エンドポイントを利用します。1度のPUTリクエストで複数のフィールドを更新することも可能です。

このエンドポイントを利用して更新できるのは前述の3つのフィールドだけです。その他のフィールドがリクエストに含まれていても無視されます。

更新を行う決済のstatusは「AUTHORIZED」でも「CLOSED」でも構いません。

リクエスト

/payments/{id}（{id}の部分はPayment ID）にPUTリクエストを送信します。 Authenticationに必要なデータをリクエストヘッダに含めます。 任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストデータ：

属性名 データ型 必須 説明
order_ref string いいえ マーチャントが割り当てる注文IDまたはカートID。order_refフィールドは必須項目ではなくなりました。また、今後は一意の値を指定する必要もありません。
description string いいえ 決済についての説明文。
metadata string いいえ 決済オブジェクトには任意のmetadataフィールドが含まれており、マーチャントは自分で定義した決済に関する補足的なデータをこのフィールドに保存できます。このフィールドにはキーと値のセットを20件まで追加できます。フィールドを更新すると、既存の値が上書きされます。そのため、metadataフィールドに含まれている既存のリストにキーと値のペアを追加する際は、元々あったキーと値のペアを含めた状態でUpdateリクエストを行うようにしてください。

レスポンス

リクエストが成功すると、paymentオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
HTTP STATUS/CODE DETAILS
400
request_content.malformed		 必須フィールドのいずれかが欠けている、あるいは書式が正しくありません。
いずれかのフィールドの書式が正しくない場合、エラーのタイトルは「Validation of the request content failed（リクエスト内容の検証に失敗）」になります。詳細については、errorオブジェクトのdescriptionフィールドを参照してください。
必須フィールドのいずれかがリクエストに含まれていない場合、エラーのタイトルは「Malformed request content（リクエスト内容の形式が不正）」になります。
400
version.unknown		 間違ったAPIのバージョン番号をヘッダーで指定しているか、Paidy-Versionフィールドが欠けています。 現行のバージョンの値は2018-04-10です。
401
authentication.failed		 必要な認証情報がリクエストヘッダに含まれていません。Paidyで認証を行うために、適切な認証情報を各リクエストに含める必要があります。APIキーをヘッダーに含めた状態でリクエストを再送信してください。
403
authorization.failed		 ヘッダーに設定しているAPIキーが正しくありません。 マーチャントダッシュボードにログインして正しいキーを取得してください。
404
404		 間違ったPayment IDをURIパラメーターとして使用しています。

2-7 決済のClose

リクエストの例

curl -X "POST" "https://api.paidy.com/payments/pay_WD1KIj4AALQAIMtZ/close" \
     -H "Content-Type: application/json" \
     -H "Paidy-Version: 2018-04-10" \
     -H "Authorization: Bearer $secret_key" \
     -d "{}"

レスポンスの例

{
 "id":"pay_WD1KIj4AALQAIMtZ",
 "created_at":"2018-06-14T05:27:10.063Z",
 "expires_at":"2018-07-14T05:27:10.063Z",
 "amount":39800,
 "currency":"JPY",
 "description":" ",
 "store_name":"Paidy sample store",
 "test":true,
 "status":"closed",
 "tier":"classic",
 "buyer":{
    "name1":"山田　太郎",
    "name2":"ヤマダ　タロウ",
    "email":"yamada@paidy.com",
    "phone":"818000000001"
 },
 "order":{
    "items":[
     {
       "id":"PDI001",
       "title":"Paidyスニーカー",
       "description":" ",
       "unit_price":10000,
       "quantity":1
     },{
       "id":"EXC002",
       "title":"エクスコスニーカー",
       "description":" ",
       "unit_price":15000,
       "quantity":2
     },{
       "id": "CPN001",
       "title": "Discount",
       "description":" ",
       "unit_price":-1000,
       "quantity":1
     }
    ],
    "tax":300,
    "shipping":500,
    "order_ref":"88e021674",
    "updated_at":null
 },
 "shipping_address":{
    "line1":"AXISビル10F",
    "line2":"六本木4-22-1",
    "city":"港区",
    "state":"東京都",
    "zip":"106-2004"
 },
 "captures":[
    {
     "id":"cap_WFIk5yIAACIAC6n3",
     "created_at":"2018-06-15T05:06:47.189Z",
     "amount":39800,
     "tax":300,
     "shipping":500,
     "items":[
       {
         "id":"PDI001",
         "title":"Paidyスニーカー",
         "description":" ",
         "unit_price":10000,
         "quantity":1
       },{
         "id":"EXC002",
         "title":"エクスコスニーカー",
         "description":" ",
         "unit_price":15000,
         "quantity":2
       },{
         "id": "CPN001",
         "title": "Discount",
         "description":" ",
         "unit_price":-1000,
         "quantity":1
       }
     ],
     "metadata":{"key1":"value1","key2":"value2"}
    }
 ], 
 "refunds":[
    {
     "id":"ref_WFImZyIAAD8AC6pC",
     "created_at":"2018-06-15T05:13:11.800Z",
     "capture_id":"cap_WFIk5yIAACIAC6n3",
     "amount":10000,
     "reason":"unknown",
     "metadata":{}
    }
 ],
 "metadata":{}
}

オープン状態の決済をクローズします。クローズできるのはstatusが「AUTHORIZED」の決済だけです。

リクエスト

/payments/{id}/close（{id}の部分はPayment ID）にPOSTリクエストを送信します。 Authenticationに必要なデータをリクエストヘッダに含めます。 任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディは空のままにしてください。

レスポンス

リクエストが成功すると、paymentオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
400
version.unknown		 間違ったAPIのバージョン番号をヘッダーで指定しているか、Paidy-Versionフィールドが欠けています。 現行のバージョンの値は2018-04-10です。
401
authentication.failed		 必要な認証情報がリクエストヘッダに含まれていません。Paidyで認証を行うために、適切な認証情報を各リクエストに含める必要があります。APIキーをヘッダーに含めた状態でリクエストを再送信してください。
403
authorization.failed		 ヘッダーに設定しているAPIキーが正しくありません。 マーチャントダッシュボードにログインして正しいキーを取得してください。
404
404		 間違ったPayment IDをURIパラメーターとして使用しています。
409
service.conflict		 すでにCLOSEDの状態になっている決済をCloseしようとしました。Closeの対象にできるのは、ステータスがAUTHORIZEDである決済だけです。

3 トークン

トークンを使用することで、マーチャントは定期購入の決済を安全かつ簡単に処理できます。トークンはPaidy Checkoutによって作成・認証され、作成後はPaidy APIを利用してライフサイクルを管理していきます。可能な操作は次の通りです。

3-1 tokenオブジェクト

オブジェクトの例

{
  "id":"tok_WK5KjCEAAA0RvPp9",
  "merchant_id":"mer_V0uhW6HCtgod-xpu",
  "wallet_id":"default",
  "status":"suspended",
  "origin":{
     "name1":"山田　太郎",
     "name2":"ヤマダ　タロウ",
     "email":"yamada@paidy.com",
     "phone":"818000000001",
     "address":null
  },
  "description":"This is the first token",
  "kind":"recurring",
  "metadata":{},
  "webhook_url":null,
  "consumer_id":"con_12121412",
  "suspensions":[
     {
        "timestamp":"2017-02-23T02:54:15.172Z",
        "authority":"merchant"
     }
  ],
  "test":true,
  "version_nr":5,
  "created_at":"2017-02-23T02:35:56.462Z",
  "updated_at":"2017-02-23T02:54:15.172Z",
  "activated_at":"2017-02-23T02:51:53.504Z",
  "deleted_at":null
}

トークンはすべてPaidy Checkoutによって作成され、Authenticateされます。

属性名 データ型 説明
id string トークンの一意のIDです。
merchant_id string Paidyが生成する、「mer_」で始まるマーチャントID。
wallet_id string マーチャントが指定するウォレットIDです。傘下に複数のマーチャントが存在する大規模なマーチャント、あるいは他のマーチャントの代理となる決済サービスプロバイダーの場合は、それぞれのマーチャントをこのwallet_idを使用して識別できます。初期値は「default」に設定されていますが、このフィールドの値を空にした状態で送信しないでください。値を設定するか、tokenオブジェクトにこのフィールドを含めずに送信を行う必要があります。
status string トークンのステータスを示します。有効な値はACTIVE、SUSPENDED、DELETEDのいずれかです。
origin object コンシューマーのデータ（originオブジェクトの項目を参照）。
description string トークンについての説明。
kind string トークンの種類を返します。必ず「recurring」と表記されます。
metadata string マーチャントが定義する、オブジェクトについてのデータです。このフィールドにはキーと値のセットを20件まで追加できます。
webhook_url string 現在は使用されていません。
consumer_id string Paidyが生成する、「con_」で始まるコンシューマーID。
suspensions object トークンが一時的に無効化されている場合、無効化に関するデータがこのオブジェクトに含まれます。Suspensionsオブジェクトの項目をご参照ください。
test string リクエストがテスト用のものかどうかを示すフラグ。
version_nr number トークンに対してリクエストが実行される度に1ずつ増加する数値です。これにより、確認中のトークンが最新バージョンのものかどうか判断できます。
created_at string トークンが作成された日時（ISO 8601のフォーマットに準じるUTC）。
updated_at string トークンが最後に更新された日時（ISO 8601のフォーマットに準じるUTC）。
activated_at string トークンが初めて有効化された日時（ISO 8601のフォーマットに準じるUTC）。
deleted_at string トークンが削除された日時（ISO 8601のフォーマットに準じるUTC）。

Originオブジェクト

属性名 データ型 説明
name1 string コンシューマーの氏名（漢字表記）。 姓と名をスペースで区切る必要があります(例：山田 太郎）。 スペースは半角（Unicode U+0020）でも全角（U+3000）でも構いません。
name2 string コンシューマーの氏名（カタカナ表記）。 姓と名をスペースで区切る必要があります（例：ヤマダ タロウ）。 スペースは半角（Unicode U+0020）でも全角（U+3000）でも構いません。
email string コンシューマーのメールアドレス。
phone string コンシューマーの電話番号（例：09011112222）。コンシューマーがテキストメッセージを受信できる日本の携帯電番号です。
address object 現在は使用されていません。

Suspensionsオブジェクト

属性名 データ型 説明
timestamp string トークンが一時的に無効化された日時（ISO 8601のフォーマットに準じるUTC）。
authority string トークンを一時的に無効化した人物を示します。APIリクエストを行う場合は必ず値を「merchant」にセットすることになります。

3-2 トークンの一時的な無効化

リクエストの例

curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/suspend" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
                "wallet_id": "default",
                "reason": {
                    "code": "fraud.suspected",
                    "description": "Token suspended because fraud suspected."
                }
            }'

レスポンスの例

{
  "id":"tok_WK5KjCEAAA0RvPp9",
  "merchant_id":"mer_V0uhW6HCtgod-xpu",
  "wallet_id":"default",
  "status":"suspended",
  "origin":{
     "name1":"山田　太郎",
     "name2":"ヤマダ　タロウ",
     "email":"yamada@paidy.com",
     "phone":"818000000001",
     "address":null
  },
  "description":"This is the first token",
  "kind":"recurring",
  "metadata":{},
  "webhook_url":null,
  "consumer_id":"con_12121412",
  "suspensions":[
     {
        "timestamp":"2017-02-23T02:54:15.172Z",
        "authority":"merchant"
     }
  ],
  "test":true,
  "version_nr":5,
  "created_at":"2017-02-23T02:35:56.462Z",
  "updated_at":"2017-02-23T02:54:15.172Z",
  "activated_at":"2017-02-23T02:51:53.504Z",
  "deleted_at":null
}

マーチャントはAPI経由でトークンを一時的に無効化することができます。その際、無効化するトークンのstatusは「ACTIVE」でなければなりません。リクエストが成功するとstatusが「SUSPENDED」に変わり、そのトークンを使用して決済データを新規作成できなくなります。

リクエスト

/tokens/{id}/suspend（{id}の部分はPaidyのトークンID）にPOSTリクエストを送信します。 authenticationに必要なデータをリクエストヘッダに含めます。 任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディ:

属性名 データ型 必須 説明
wallet_id string いいえ マーチャントが指定するウォレットIDです。このフィールドの値を空にした状態で送信しないでください。値を設定するか、tokenオブジェクトにこのフィールドを含めずに送信を行う必要があります。このフィールドが送信されない場合、値として「default」がセットされます。
reason object はい リクエストを行う理由についてのデータを示します。このオブジェクトには、codeとdescriptionという2つの必須フィールドが含まれています。

理由についてのデータ:

属性名 データ型 必須 説明
code string はい トークンのステータスを変更する理由。次のいずれかをセットできます。
  • consumer.requested
  • merchant.requested
  • fraud.suspected
  • general
この表にないコードを送信した場合、システムはエラーを返します。
description string はい トークンのステータス変更について説明するテキスト。トークンを一時的に無効化する理由として最適なものが既存のreasonコードの中にない場合は、このフィールドに詳細な情報を含められます。

レスポンス

リクエストが成功すると、tokenオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
400
request_content.malformed		 必須フィールドのいずれかが欠けている、あるいは書式が正しくありません。
いずれかのフィールドの書式が正しくない場合、エラーのタイトルは「Validation of the request content failed（リクエスト内容の検証に失敗）」になります。詳細については、errorオブジェクトのdescriptionフィールドを参照してください。
必須フィールドのいずれかがリクエストに含まれていない場合、エラーのタイトルは「Malformed request content（リクエスト内容の形式が不正）」になります。
401
authentication.failed		 認証情報がセットされていないか、APIキーが間違っています。
ヘッダーに含まれているAPIキーが正しくない場合、エラーのタイトルは「Authentication invalid（不正な認証）」になります。
必要な認証情報がリクエストヘッダに含まれていない場合、エラーのタイトルは「Authentication required（認証が必要）」になります。
403
request_content.malformed		 すでにトークンが一時的に無効化されているため、操作を実行できません。 一時的に無効化できるのは、有効（ACTIVE）なトークンだけです。
404
404		 すでにトークンが削除されているため、操作を実行できません。一時的に無効化できるのは、有効（ACTIVE）なトークンだけです。

3-3 トークンの回復

リクエストの例

curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/resume" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
                "wallet_id": "default",
                "reason": {
                    "code": "merchant.requested",
                    "description": "Token is being resumed because the subscription item is back in stock"
                }
            }'

レスポンスの例

{
  "id":"tok_WK5KjCEAAA0RvPp9",
  "merchant_id":"mer_V0uhW6HCtgod-xpu",
  "wallet_id":"default",
  "status":"active",
  "origin":{
     "name1":"山田　太郎",
     "name2":"ヤマダ　タロウ",
     "email":"yamada@paidy.com",
     "phone":"818000000001",
     "address":null
  },
  "description":"This is the first token",
  "kind":"recurring",
  "metadata":{},
  "webhook_url":null,
  "consumer_id":"con_12121412",
  "suspensions":[],
  "test":true,
  "version_nr":6,
  "created_at":"2017-02-23T02:35:56.462Z",
  "updated_at":"2017-02-23T02:55:36.643Z",
  "activated_at":"2017-02-23T02:51:53.504Z",
  "deleted_at":null
}

マーチャントは一時的に無効化されたトークンをAPI経由で回復させることができます。Resumeリクエストが成功するとstatusが「ACTIVE」に変わり、再びそのトークンを使用して決済データを作成できるようになります。

このトークンを回復できるのは、無効化した人物だけです。そのため、コンシューマーが無効化したトークンをマーチャントが回復させようとすると、エラーが返されます。

リクエスト

/tokens/{id}/resume（{id}の部分はPaidyのトークンID）にPOSTリクエストを送信します。 authenticationに必要なデータをリクエストヘッダに含めます。任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディ:

属性名 データ型 必須 説明
wallet_id string いいえ マーチャントが指定するウォレットIDです。このフィールドの値を空にした状態で送信しないでください。値を設定するか、tokenオブジェクトにこのフィールドを含めずに送信を行う必要があります。このフィールドが送信されない場合、値として「default」がセットされます。
reason object はい リクエストを行う理由についてのデータを示します。このオブジェクトには、codeとdescriptionという2つの必須フィールドが含まれています。

理由についてのデータ:

属性名 データ型 必須 説明
code string はい トークンのステータスを変更する理由。次のいずれかをセットできます。
  • consumer.requested
  • merchant.requested
  • general
この表にないコードを送信した場合、システムはエラーを返します。
description string はい トークンのステータス変更について説明するテキスト。トークンを一時的に無効化する理由として最適なものが既存のreasonコードの中にない場合は、このフィールドに詳細な情報を含められます。

レスポンス

リクエストが成功すると、tokenオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
400
request_content.malformed		 必須フィールドのいずれかが欠けている、あるいは書式が正しくありません。
いずれかのフィールドの書式が正しくない場合、エラーのタイトルは「Validation of the request content failed（リクエスト内容の検証に失敗）」になります。詳細については、errorオブジェクトのdescriptionフィールドを参照してください。
必須フィールドのいずれかがリクエストに含まれていない場合、エラーのタイトルは「Malformed request content（リクエスト内容の形式が不正）」になります。
401
authentication.failed		 認証情報がセットされていないか、APIキーが間違っています。
ヘッダーに含まれているAPIキーが正しくない場合、エラーのタイトルは「Authentication invalid（不正な認証）」になります。
必要な認証情報がリクエストヘッダに含まれていない場合、エラーのタイトルは「Authentication required（認証が必要）」になります。
404
404		 すでにトークンが削除されているため、操作を実行できません。一時的に無効化できるのは、有効（ACTIVE）なトークンだけです。

3-4 トークンの削除

リクエストの例

curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/delete" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
                "wallet_id": "default",
                "reason": {
                    "code": "consumer.requested",
                    "description": "Token was deleted because consumer canceled the subscription"
                }
            }'

レスポンスの例

{
  "id":"tok_WK5KjCEAAA0RvPp9",
  "merchant_id":"mer_V0uhW6HCtgod-xpu",
  "wallet_id":"default",
  "status":"deleted",
  "origin":{
     "name1":"山田　太郎",
     "name2":"ヤマダ　タロウ",
     "email":"yamada@paidy.com",
     "phone":"818000000001",
     "address":null
  },
  "description":"This is the first token",
  "kind":"recurring",
  "metadata":{},
  "webhook_url":null,
  "consumer_id":"con_12121412",
  "suspensions":[],
  "test":true,
  "version_nr":7,
  "created_at":"2017-02-23T02:35:56.462Z",
  "updated_at":"2017-02-23T03:11:39.028Z",
  "activated_at":"2017-02-23T02:51:53.504Z",
  "deleted_at":"2017-02-23T03:11:39.028Z"
}

マーチャントは不要になったトークンを削除できます。その際、削除するトークンのstatusは「ACTIVE」でも「SUSPENDED」でも構いません。

このリクエストによって実際にトークンが削除されるわけではありませんが、statusが「DELETED」に変わり、そのトークンを決済に使用できなくなります。また、削除したトークンは回復させることができません。

リクエスト

/tokens/{id}/delete（{id}の部分はPaidyのトークンID）にPOSTリクエストを送信します。 authenticationに必要なデータをリクエストヘッダに含めます。任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディ:

属性名 データ型 必須 説明
wallet_id string いいえ マーチャントが指定するウォレットIDです。このフィールドの値を空にした状態で送信しないでください。値を設定するか、tokenオブジェクトにこのフィールドを含めずに送信を行う必要があります。このフィールドが送信されない場合、値として「default」がセットされます。
reason object はい リクエストを行う理由についてのデータを示します。このオブジェクトには、codeとdescriptionという2つの必須フィールドが含まれています。

理由についてのデータ:

属性名 データ型 必須 説明
code string はい トークンのステータスを変更する理由。次のいずれかをセットできます。
  • consumer.requested
  • subscription.expired
  • merchant.requested
  • fraud.detected
  • general
この表にないコードを送信した場合、システムはエラーを返します。
description string はい トークンのステータス変更について説明するテキスト。トークンを一時的に無効化する理由として最適なものが既存のreasonコードの中にない場合は、このフィールドに詳細な情報を含められます。

レスポンス

リクエストが成功すると、tokenオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
400
request_content.malformed		 必須フィールドのいずれかが欠けている、あるいは書式が正しくありません。
いずれかのフィールドの書式が正しくない場合、エラーのタイトルは「Validation of the request content failed（リクエスト内容の検証に失敗）」になります。詳細については、errorオブジェクトのdescriptionフィールドを参照してください。
必須フィールドのいずれかがリクエストに含まれていない場合、エラーのタイトルは「Malformed request content（リクエスト内容の形式が不正）」になります。
401
authentication.failed		 認証情報がセットされていないか、APIキーが間違っています。
ヘッダーに含まれているAPIキーが正しくない場合、エラーのタイトルは「Authentication invalid（不正な認証）」になります。
必要な認証情報がリクエストヘッダに含まれていない場合、エラーのタイトルは「Authentication required（認証が必要）」になります。

3-5 特定のtokenオブジェクトを取得

リクエストの例

curl -X "GET" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{}'

レスポンスの例

{
  "id":"tok_WK5KjCEAAA0RvPp9",
  "merchant_id":"mer_V0uhW6HCtgod-xpu",
  "wallet_id":"default",
  "status":"suspended",
  "origin":{
     "name1":"山田　太郎",
     "name2":"ヤマダ　タロウ",
     "email":"yamada@paidy.com",
     "phone":"818000000001",
     "address":null
  },
  "description":"This is the first token",
  "kind":"recurring",
  "metadata":{},
  "webhook_url":null,
  "consumer_id":"con_12121412",
  "suspensions":[
     {
        "timestamp":"2017-02-23T02:54:15.172Z",
        "authority":"merchant"
     }
  ],
  "test":true,
  "version_nr":5,
  "created_at":"2017-02-23T02:35:56.462Z",
  "updated_at":"2017-02-23T02:54:15.172Z",
  "activated_at":"2017-02-23T02:51:53.504Z",
  "deleted_at":null
}

トークンの詳細情報を確認する際はtokensエンドポイントを利用します。トークンのToken IDが有効であればデータを取得できます。

リクエスト

/tokens/{id}（{id}の部分はPaidyのトークンID）にGETリクエストを送信します。 authenticationに必要なデータをリクエストヘッダに含めます。任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディは空のままにしてください。

レスポンス

リクエストが成功すると、tokenオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
401
authentication.failed		 認証情報がセットされていないか、APIキーが間違っています。
ヘッダーに含まれているAPIキーが正しくない場合、エラーのタイトルは「Authentication invalid（不正な認証）」になります。
必要な認証情報がリクエストヘッダに含まれていない場合、エラーのタイトルは「Authentication required（認証が必要）」になります。

3-6 すべてのトークンを取得

リクエストの例

curl -X "GET" "https://api.paidy.com/tokens/" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{}'

レスポンスの例

[{
  "id":"tok_WK5KjCEAAA0RvPp9",
  "merchant_id":"mer_V0uhW6HCtgod-xpu",
  "wallet_id":"default",
  "status":"suspended",
  "origin":{
     "name1":"山田　太郎",
     "name2":"ヤマダ　タロウ",
     "email":"yamada@paidy.com",
     "phone":"818000000001",
     "address":null
  },
  "description":"This is the first token",
  "kind":"recurring",
  "metadata":{},
  "webhook_url":null,
  "consumer_id":"con_12121412",
  "suspensions":[
     {
        "timestamp":"2017-02-23T02:54:15.172Z",
        "authority":"merchant"
     }
  ],
  "test":true,
  "version_nr":5,
  "created_at":"2017-02-23T02:35:56.462Z",
  "updated_at":"2017-02-23T02:54:15.172Z",
  "activated_at":"2017-02-23T02:51:53.504Z",
  "deleted_at":null
},
{
  "id":"tok_WjE399PvAA61Pp963",
  "merchant_id":"mer_V0uhW6HCtgod-xpu",
  "wallet_id":"default",
  "status":"active",
  "origin":{
     "name1":"田中　愛子",
     "name2":"タナカ　アイコ",
     "email":"tanaka@paidy.com",
     "phone":"818000000002",
     "address":null
  },
  "description":"This is the second token",
  "kind":"recurring",
  "metadata":{},
  "webhook_url":null,
  "consumer_id":"con_76400088",
  "suspensions":[],
  "test":true,
  "version_nr":3,
  "created_at":"2017-02-23T02:35:56.462Z",
  "updated_at":"2017-02-23T02:54:15.172Z",
  "activated_at":"2017-02-23T02:51:53.504Z",
  "deleted_at":null
}]

マーチャントが取り引きするすべてのコンシューマーを対象にして、statusが「ACTIVE」あるいは「SUSPENDED」であるトークンの全リストを取得できるリクエストです。

リクエスト

/tokens/ にGETリクエストを送信します。 authenticationに必要なデータをリクエストヘッダに含めます。任意でAPIのバージョンを含めることもできます。APIのバージョンを指定する場合は、2018-04-10という値を持つPaidy-Versionフィールドをヘッダーに追加します。

リクエストボディは空のままにしてください。

レスポンス

リクエストが成功すると、tokenオブジェクトが200番台のHTTPステータスコードとともに返ってきます。 リクエストが失敗すると、エラーについての詳細情報を含むerrorオブジェクトが4xx番台または5xx番台のHTTPステータスコードとともに返ってきます。

以下の場合はリクエストが失敗します。

コード 説明
401
authentication.failed		 認証情報がセットされていないか、APIキーが間違っています。
ヘッダーに含まれているAPIキーが正しくない場合、エラーのタイトルは「Authentication invalid（不正な認証）」になります。
必要な認証情報がリクエストヘッダに含まれていない場合、エラーのタイトルは「Authentication required（認証が必要）」になります。

curl