NAV Navbar
Logo
curl

1 Introduction

API endpoint

   https://api.paidy.com

The Paidy API is used to manage payments and tokens. It is exposed over a series of REST endpoints, with request and response data formatted as JSON.

To ensure that any text sent in the JSON is transmitted correctly and displayed correctly at Paidy’s user interfaces, make sure it is UTF-8 encoded.

NOTE! This specification only contains information about the API requests and responses; for information about creating payments or tokens via Paidy Checkout, see Paidy’s HTML documentation.

1-1 API keys

Every merchant account has 4 API keys: a secret key and public key for testing and a secret key and public key for the live environment. There is no separate test environment, simply use the appropriate key to perform a live or test transaction.

The public key is used by Paidy Checkout. You must add it to the merchant configuration to identify your account when communicating with Paidy. Public keys can be inserted into webpages or mobile applications.

The secret key is used by the Paidy API. All API requests must contain the secret key as part of their credentials for authenticating with Paidy. Secret keys should never be shared or made public.

In Paidy, public keys are prefixed by pk_ and secret keys are prefixed by sk_. To see your keys, log into the Merchant Dashboard.

1-2 API requests

Example header

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

All API requests must be made over HTTPS. Calls made over HTTP will fail.

The header of every request that is sent to Paidy must contain the proper credentials for authenticating with Paidy and may optionally contain the version of the API.

API authentication

To authenticate with Paidy, the preferred method is to authenticate via bearer token. Log into the Merchant Dashboard and retrieve your secret key. (The Merchant Dashboard lists your keys for both testing and production; make sure to retrieve the correct secret key.)

Add your API key to the Authorization HTTP request header prefixed with “Bearer”. If the credentials are missing or the incorrect API key is used, Paidy will respond with an error.

API version

You can set the version number in the header of each request that is made to the API.

To set the API version, add the Paidy-Version field with the value set to 2018-04-10. If the Paidy-Version field is missing, Paidy may respond with an error code.

1-3 API responses

HTTP response codes

The API uses HTTP response codes to indicate the result of the request. The response code is returned in the header.

Some of the more commonly received response codes are:

CODE MEANING
200 - OK Request was successful, everything worked as expected.
400 - Bad Request Request was not accepted; usually the result of a missing required parameter.
401 - Unauthorized Authentication issue; usually the result of using the incorrect key in the header.
403 - Forbidden Requested action is not allowed for that payment. For example, if you try to capture a payment that is already CLOSED or refund a payment that is AUTHORIZED.
404 - Not Found Requested resource does not exist. For example, if you try to update a payment using an invalid payment ID.
409 - Conflict Request could not be processed because of a conflict in state. For example, if you try and close a payment that is already CLOSED.

This table lists a small subset of the more common HTTP status codes. For the full list of HTTP status codes and their meanings, see the HTTP protocol online documentation.

Error object

Example error 

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

In addition to HTTP status codes, Paidy also uses error objects to handle errors. When an API call fails, Paidy will respond with a 4xx or 5xx status code in the header, together with an error object in the response body.

The error object contains the following fields.

ATTRIBUTE TYPE DESCRIPTION
reference string Internal error code.
status string HTTP response code.
code string Code indicating the kind of error that occurred. The list of valid codes are listed in the table below.
title string Text version of the error code. This field can sometimes provide the name of the field with which there is an issue.
description string Description providing more details about the error.

Error codes:

CODE DESCRIPTION
404 The requested resource could not be found.
authentication.failed Authentication with Paidy failed.
authorization.failed Authorization failed.
method.invalid The HTTP method used is not valid for that endpoint.
media_type.unsupported The request’s content-type is not supported.
request_content.malformed The request content was not formatted correctly.
service.conflict There was a conflict during execution.
service.exception Internal service exception.
service.forbidden The request is forbidden.
request_entity.invalid Validation of a parameter failed.
version.unknown The API version used is not correct.

Note, this is the current list of error codes returned. However, we may add new error codes at any time, so you may receive codes other than the ones listed here.

2 Payments

There are 2 types of payments at Paidy: standard payments and subscription payments.

You can use the API to:

NOTE! Subscription payments are created via the API and standard payments are created via Paidy Checkout. For more information about creating standard payments, see Paidy’s HTML documentation.

2-1 Payment object

Example object

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

Payment objects are uniquely identified by a payment ID, starting with pay_.

ATTRIBUTE TYPE DESCRIPTION
id string Unique identifier for the payment. All payment IDs begin with pay_.
created_at string Date and time the payment was created, in UTC, and displayed in ISO 8601 datetime format.
expires_at string Date and time the payment expires, in UTC, and displayed in ISO 8601 datetime format. You must capture the payment before this datetime.
amount double Total payment amount, including tax, shipping, and excluding any discounts.
currency string ISO 4217 currency code for the payment amount; set to JPY.
description string Description for the payment.
store_name string Merchant store name. This field is displayed at both MyPaidy and the Merchant Dashboard.
test boolean Indicates whether this is a test payment (created using a test API key).
status string Current status of this payment object. A payment that was successfully authorized has a status of AUTHORIZED. A payment that was successfully captured, closed, or canceled has a status of CLOSED.
tier string Paidy-assigned payment type. The default value is “classic”.
buyer object Buyer object. Consumer’s name and contact information.
order object Order object. Order/cart details passed by the merchant.
shipping_address object Shipping address object. Shipping address for the order.
captures object Captures object. Array of objects representing the captured payments.
refunds object Refunds object. Array of objects representing the refunded payments.
metadata string Merchant-defined data about the object. This field is a key-value map, limited to 20 keys.

Buyer object

ATTRIBUTE TYPE DESCRIPTION
name1 string Consumer’s name in kanji. Family name and first name must be separated by a space, e.g., 山田　太郎.
name2 string Consumer’s name in katakana. Family name and first name must be separated by a space, e.g., ヤマダ　タロウ.
email string Consumer’s email address.
phone string Consumer’s phone number, e.g., 09011112222. This must be a Japanese mobile phone where the consumer can receive text messages.

Order object

ATTRIBUTE TYPE DESCRIPTION
items object Items object. Array of objects representing the order items in this payment. If you want to offer consumers a discount, use this object to create a “discount order item”, with the unit_price set to the negative value of the discount.
tax double Total tax for the order.
shipping double Total shipping cost for the order.
order_ref string Merchant-assigned order or cart ID.
updated_at string This field is currently not used.

Items object

ATTRIBUTE TYPE DESCRIPTION
id string Merchant’s product identifier. This field is optional, but if it is sent, it will be displayed at the Merchant Dashboard and MyPaidy.
title string Name of the product. This field is optional, but we recommend sending it as part of the payload. If sent, it is shown at both the Merchant Dashboard and MyPaidy to identify the order item. If not sent, only the quantity and unit price will be displayed for the order item.
description string Description for the product. Currently, this is not displayed at the Merchant Dashboard or MyPaidy.
unit_price double Price per unit of the product. The unit_price can be a negative value to represent a discount.
quantity integer Quantity of the product ordered.

Shipping_address object

ATTRIBUTE TYPE DESCRIPTION
line1 string Building name, apartment number.
line2 string District, land number, land extension number.
city string Name of city, municipality, or village.
state string Prefecture.
zip string Postal code; format is NNN-NNNN.

Captures object

ATTRIBUTE TYPE DESCRIPTION
id string Unique capture ID, assigned by Paidy. All capture IDs begin with cap_.
created_at string Date and time the capture was created, in UTC, and displayed in ISO 8601 datetime format.
amount double Amount captured.
tax double Tax amount captured.
shipping double Shipping cost captured.
items object Array of objects representing the order items being captured.
metadata string Merchant-defined data about the capture object. This field is a key-value map, limited to 20 keys.

Refunds object

ATTRIBUTE TYPE DESCRIPTION
id string Unique refund ID, assigned by Paidy. All refund IDs begin with ref_.
created_at string Date and time the refund was created, in UTC, and displayed in ISO 8601 datetime format.
capture_id string Capture ID of the items being refunded. A refund must map to a capture. All capture IDs begin with cap_.
amount double Amount refunded.
reason string Reason for the refund.
metadata string Merchant-defined data about the refund. This field is a key-value map, limited to 20 keys.

2-2 Create a payment

Example request

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

Example response

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

Creates a new subscription payment using a token. The token and the consumer must have a status of ACTIVE.

NOTE! Subscription payments are created via the API and standard payments are created via Paidy Checkout. This specification only contains information about the API requests and responses. For more information about creating standard payments, see Paidy’s HTML documentation.

Request

Send a POST request to /payments. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

Request body:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
token_id string required Paidy-generated token ID, beginning with tok_.
amount double required Total payment amount, including tax and shipping.
currency string required ISO 4217 currency code for this order. Set to JPY.
description string optional Description for the payment. Currently not displayed at MyPaidy or the Merchant Dashboard.
store_name string optional Merchant store name; this is displayed at MyPaidy and the Merchant Dashboard.
buyer_data object required Buyer_data object containing information about the consumer’s purchasing history.
order object required Order object. Order/cart details passed by the merchant.
metadata string optional Merchant-defined data about the object. This field is a key-value map, limited to 20 keys.
shipping_address object required Consumer’s shipping address.

Buyer_data object:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
age integer required Time in days since the consumer opened the account with the merchant.
order_count integer required Number of orders the consumer has made since signing up with the merchant, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
ltv double required Lifetime value. The total amount (in JPY) the consumer has ordered since signing up with the merchant, excluding canceled, rejected, or refunded transactions. Also excluding Paidy payments.
last_order_amount double required Amount (in JPY) of the last order, excluding Paidy payments.
last_order_at integer required Time in days since the last order, excluding Paidy payments.

Order object:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
items object required Array of items objectsrepresenting all of the items in the order. If you want to offer consumers a discount, use this object to create a “discount order item”, with the unit_price set to the negative value of the discount.
tax double optional Total tax charged on the order.
shipping double optional Total shipping charges for the order.
order_ref string optional Merchant’s order ID or reference. (In the Paidy API v2, this field is not required and does not need to be unique.)

Items object:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
quantity integer required Quantity of the item added to the order.
id string optional Merchant’s product identifier. This field is optional, but if sent, it will be displayed at the Merchant Dashboard and MyPaidy.
title string optional Title of the order item (or discount/coupon). This field is optional, but we recommend sending it as part of the payload. If sent, it is shown at both the Merchant Dashboard and MyPaidy to identify the order item. If not sent, only the quantity and unit price will be displayed for the order item.
description string optional Description of the item. Currently, this is not displayed at the Merchant Dashboard or MyPaidy.
unit_price double required Price per unit for the item. If the order item is a discount or coupon, make sure the unit_price is set to a negative value, so that it will be subtracted from the total amount for the order.

Shipping_address object:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
line1 string optional For Japanese addresses: building name, apartment number.
line2 string optional For Japanese addresses: building name, apartment number.
city string optional Name of city, municipality, or village.
state string optional Prefecture.
zip string required Postal code; format is NNN-NNNN.
NOTE! Zip is required. Each of the other fields in the address object are optional, but in addition to the zip field, at least one of the other fields must be populated. If two fields are not provided in the shipping address, the request will fail.

Response

Upon success, returns a 200 HTTP status code and the payment object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
request_content.malformed		 One of the required fields is missing or is not formatted correctly.
If the error title is “Validation of the request content failed”, one of the fields is formatted incorrectly. See the description field in the error object for more details.
If the error title is “Malformed request content”, one of the required fields is missing from the request.
400
version.unknown		 You are using the incorrect API version number in the header or the Paidy-Version field is missing. The current API version is 2018-04-10.
401
authentication.failed		 The required authentication is missing from the request header. Every request must contain the proper credentials for authenticating with Paidy. Please add your API key to the header and resend the request.
403
authorization.failed		 The API key supplied in the header is not valid. Please log into the Merchant Dashboard to retrieve the correct key.

2-3 Capture a payment

Example request

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

Example response

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

When you are ready to charge the consumer, you perform a capture request.

The payment must have a status of AUTHORIZED. All authorized requests automatically expire. The expiration period is specified in your contract and after this period, they are marked as expired and cannot be captured.

Request

Send a POST request to /payments/{id}/captures, where {id} is the Paidy payment ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

The body of the request can be empty or contain the metadata field. This field is a key-value map, limited to 20 keys, that contains additional data about the capture object.

NOTE: Even if you are not sending fields in the body of the capture request, you must include the curly brackets. The system checks for these and the request will fail if they are not there.

Response

Upon success, returns a 200 HTTP status code and the updated payment object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
request_content.malformed		 One of the required fields is missing or is not formatted correctly.
If the error title is “Validation of the request content failed”, one of the fields is formatted incorrectly. See the description field in the error object for more details.
If the error title is “Malformed request content”, one of the required fields is missing from the request or the curly brackets are missing from the body of the request.
400
payment.authorization.expired		 The payment is already closed because it is expired. You cannot capture an expired payment.
400
version.unknown		 You are using the incorrect API version number in the header or the Paidy-Version field is missing. The current API version is 2018-04-10.
401
authentication.failed		 The required authentication is missing from the request header. Every request must contain the proper credentials for authenticating with Paidy. Please add your API key to the header and resend the request.
403
authorization.failed		 The API key supplied in the header is not valid. Please log into the Merchant Dashboard to retrieve the correct key.
403
service.forbidden		 You tried to capture a request that was already closed. You can only capture a request if it has a status of AUTHORIZED.
404
404		 You are using the incorrect payment ID as the URI parameter.

2-4 Refund a payment

Example request

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

Example response

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

Refunds all or part of a Paidy payment. You can only refund a payment that has captured.

Request

Send a POST request to /payments/{id}/refunds, where {id} is the Paidy payment ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

Request data:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
capture_id string Required Since a refund request is executed on the specified capture, the capture_id must be included in the request. All capture IDs begin with cap_.
amount double No The amount to refund. Paidy uses this field to determine whether the request is for a partial refund or full refund. If no amount is specified, Paidy refunds the full amount for that capture.
reason string No The reason for the refund.
metadata string No You can use this field to store additional structured information about the refund. It is a key-value map, limited to 20 keys.

Response

Upon success, returns a 200 HTTP status code and the updated payment object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
request_content.malformed		 One of the required fields is missing or is not formatted correctly.
If the error title is “Validation of the request content failed”, one of the fields is formatted incorrectly. See the description field in the error object for more details.
If the error title is “Malformed request content”, one of the required fields is missing from the request.
400
payment.refund.amount		 You tried to refund an invalid amount.
400
payment.refund.captureId		 The capture ID was incorrect.
400
version.unknown		 You are using the incorrect API version number in the header or the Paidy-Version field is missing. The current API version is 2018-04-10.
401
authentication.failed		 The required authentication is missing from the request header. Every request must contain the proper credentials for authenticating with Paidy. Please add your API key to the header and resend the request.
403
authorization.failed		 The API key supplied in the header is not valid. Please log into the Merchant Dashboard to retrieve the correct key.
403
service.forbidden		 You tried to refund a payment that is already fully refunded.
404
404		 You are using the incorrect payment ID as the URI parameter.

2-5 Retrieve a payment

Example request

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

Example response

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

Retrieves the specified payment. If successful, returns the entire payment object, including the status, any captures, and any refunds.

Request

Send a GET request to /payments/{id}, where {id} is the Paidy payment ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

The body of the request is empty.

Response

Upon success, returns a 200 HTTP status code and the payment object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
request_content.malformed		 One of the required fields is missing or is not formatted correctly.
If the error title is “Validation of the request content failed”, one of the fields is formatted incorrectly. See the description field in the error object for more details.
If the error title is “Malformed request content”, one of the required fields is missing from the request.
400
version.unknown		 You are using the incorrect API version number in the header or the Paidy-Version field is missing. The current API version is 2018-04-10.
401
authentication.failed		 The required authentication is missing from the request header. Every request must contain the proper credentials for authenticating with Paidy. Please add your API key to the header and resend the request.
403
authorization.failed		 The API key supplied in the header is not valid. Please log into the Merchant Dashboard to retrieve the correct key.
404
404		 You are using the incorrect payment ID as the URI parameter.

2-6 Update a payment

Example request

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":"スニーカー"\}"

Example response

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

Updates the order_ref, description, and/or metadata fields for a payment. You can only use this endpoint to update these 3 fields. If you send other fields in the request, they will simply be ignored by Paidy.

The payment to be updated can have a status of AUTHORIZED or CLOSED.

You can update one or more fields in one PUT request.

Request

Send a PUT request to /payments/{id}, where {id} is the Paidy payment ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is -07-01.

Request data:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
order_ref string No Merchant-assigned order or cart ID. In the API v2, this field is not required, and does not need to be unique.
description string No Description for this payment.
metadata string No Optional field in the payment object that can be used to store additional merchant-defined data about a payment. The field is a key-value map, limited to 20 keys. When you update a field, the existing values will be overwritten. So, if you are adding key-value pairs to an existing list in the metadata field, remember to include the existing key-value pairs in the update request.

Response

Upon success, returns a 200 HTTP status code and the payment object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
request_content.malformed		 One of the required fields is missing or is not formatted correctly.
If the error title is “Validation of the request content failed”, one of the fields is formatted incorrectly. See the description field in the error object for more details.
If the error title is “Malformed request content”, one of the required fields is missing from the request.
400
version.unknown		 You are using the incorrect API version number in the header or the Paidy-Version field is missing. The current API version is 2018-04-10.
401
authentication.failed		 The required authentication is missing from the request header. Every request must contain the proper credentials for authenticating with Paidy. Please add your API key to the header and resend the request.
403
authorization.failed		 The API key supplied in the header is not valid. Please log into the Merchant Dashboard to retrieve the correct key.
404
404		 You are using the incorrect payment ID as the URI parameter.

2-7 Close a payment

Example request

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

Example response

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

Closes a Paidy payment that was successfully authorized, but not captured. The payment must have a status of AUTHORIZED.

Request

Send a POST request to /payments/{id}/close, where {id} is the Paidy payment ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version fSield; the current version of the API is 2018-04-10.

The body of the request is empty.

Response

Upon success, returns a 200 HTTP status code and the payment object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
version.unknown		 You are using the incorrect API version number in the header or the Paidy-Version field is missing. The current API version is 2018-04-10.
401
authentication.failed		 The required authentication is missing from the request header. Every request must contain the proper credentials for authenticating with Paidy. Please add your API key to the header and resend the request.
403
authorization.failed		 The API key supplied in the header is not valid. Please log into the Merchant Dashboard to retrieve the correct key.
404
404		 You are using the incorrect payment ID as the URI parameter.
409
service.conflict		 You tried to close a payment that is already CLOSED. You can only close a payment if it has a status of AUTHORIZED.

3 Tokens

Tokens provide merchants with a simple and secure way to handle subscriptions in Paidy. Tokens are created and authenticated via Paidy Checkout. Once created, you can use the Paidy API to manage the lifecycle of a token.

You can use the API to:

3-1 Token object

Example object

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

When a subscription payment is authenticated via Paidy Checkout, a token object is created.

ATTRIBUTE TYPE DESCRIPTION
id string Unique identifier for the token. All token IDs begin with tok_.
merchant_id string Paidy-generated merchant ID, beginning with mer_.
wallet_id string Merchant-provided wallet ID. You can use this field to group tokens. For example, large-scale merchants who have multiple sub-merchants or act as a payment service provider for other merchants can use the wallet_id to identify these sub-merchants. The default value is set to “default”.
status string Status of the token. Valid values are: ACTIVE, SUSPENDED, or DELETED.
origin object Origin object which contains the buyer data and the consumer’s shipping address.
description string Description for the token.
kind string Returns the token type. This will always be set to “recurring”.
metadata string Merchant-defined data about the object. This field is a key-value map, limited to 20 keys.
webhook_url string This field is currently not used.
consumer_id string Paidy-generated consumer ID, beginning with con_.
suspensions object If the token is suspended, this object contains data related to the suspension. suspensions object.
test string Flag to indicate whether the request is a test request.
version_nr number A number that increments with each request that is executed against his token. This allows you to know if you are looking at the most recent version of the token.
created_at string Date and time the token was created, in UTC, and displayed in ISO 8601 format.
updated_at string Date and time the token was last updated, in UTC, and displayed in ISO 8601 format.
activated_at string Date and time the token was first activated, in UTC, and displayed in ISO 8601 format.
deleted_at string Date and time the token was deleted, in UTC, and displayed in ISO 8601 format.

Origin object

ATTRIBURE TYPE DESCRIPTION
name1 string Consumer’s name in kanji. Family name and first name must be separated by a space, e.g., 山田　太郎.
name2 string Consumer’s name in katakana. Family name and first name must be separated by a space, e.g., ヤマダ　タロウ.
email string Consumer’s email address.
phone string Consumer’s phone number, e.g., 09011112222. This must be a Japanese mobile phone where the consumer can receive text messages.
address object This field is currently not used.

Suspensions object

ATTRIBUTE TYPE DESCRIPTION
timestamp string Date and time the token was suspended, in UTC, and displayed in ISO 8601 format.
authority string The person responsible for suspending the token; for API requests, this is set to “merchant”.

3-2 Suspend a token

Example request

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

Example response

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

Suspends a token. The token to be suspended must have a status of ACTIVE. If successful, the token status is updated to SUSPENDED and all authorization requests for a new payment using the token will be rejected.

Request

Send a POST request to /tokens/{id}/suspend, where {id} is the token ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

Request body:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
wallet_id string optional Merchant-provided wallet ID. Default value is “default”.
When the token was created, if the value of this field was set to “default”, this field is optional. However, if a merchant-specific wallet ID was set, this field is required. If you do not sent this field or you send the incorrect value, Paidy will return an error.
reason object required Reason for the request. See the reason object.

Reason object:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
code string required Paidy-defined reason code for the request. Only use one of the following values:
  • consumer.requested
  • merchant.requested
  • fraud.suspected
  • general
If you use a value other than the ones listed here, Paidy will return an error.
description string required Additional, more specific details about the reason. This field cannot be empty.

Response

Upon success, returns a 200 HTTP status code and the updated token object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
request_content.malformed		 One of the required fields is missing or is not formatted correctly.
If the error title is “Validation of the request content failed”, one of the fields is formatted incorrectly. See the description field in the error object for more details.
If the error title is “Malformed request content”, one of the required fields is missing from the request.
401
authentication.failed		 The authentication was not set or the wrong API key was used.
If the error title is “Authentication invalid”, the API key supplied in the header is not valid.
If the error title is “Authentication required”, the required authentication is missing from the request header.
403
request_content.malformed		 Invalid action as this token is already suspended. You can only suspend a token that is active.
404
404		 Invalid action as this token is already deleted. You can only suspend a token that is active.

3-3 Resume a token

Example request

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

Example response

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

Resumes a token. If successful, the token status is updated to ACTIVE and the merchant can use this token again to create payments.

A token can only be resumed by the same authority that suspended it. If you try to resume a token that was suspended by a consumer, Paidy will return an error.

Request

Send a POST request to /tokens/{id}/resume, where {id} is the token ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

Request body:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
wallet_id string optional Merchant-provided wallet ID. Default value is “default”.
When the token was created, if the value of this field was set to “default”, this field is optional. However, if a merchant-specific wallet ID was set, this field is required. If you do not sent this field or you send the incorrect value, Paidy will return an error.
reason object required Reason for the request. See the reason object.

Reason object:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
code string required Paidy-defined reason code for the request. Only use one of the following values:
  • consumer.requested
  • merchant.requested
  • general
If you use a value other than the ones listed here, Paidy will return an error.
description string required Additional, more specific details about the reason. This field cannot be empty.

Response

Upon success, returns a 200 HTTP status code and the updated token object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
request_content.malformed		 One of the required fields is missing or is not formatted correctly.
If the error title is “Validation of the request content failed”, one of the fields is formatted incorrectly. See the description field in the error object for more details.
If the error title is “Malformed request content”, one of the required fields is missing from the request.
401
authentication.failed		 The authentication was not set or the wrong API key was used.
If the error title is “Authentication invalid”, the API key supplied in the header is not valid.
If the error title is “Authentication required”, the required authentication is missing from the request header.
404
404		 Invalid action as this token is already deleted. You can only suspend a token that is active.

3-4 Delete a token

Example request

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

Example response

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

Permanently “disables” a token. The token to be deleted can have a status of ACTIVE or SUSPENDED.

Request

Send a POST request to /tokens/{id}/delete, where {id} is the token ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

Request body:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
wallet_id string optional Merchant-provided wallet ID. Default value is “default”.
When the token was created, if the value of this field was set to “default”, this field is optional. However, if a merchant-specific wallet ID was set, this field is required. If you do not sent this field or you send the incorrect value, Paidy will return an error.
reason object required Reason for the request. See the reason object.

Reason object:

ATTRIBUTE TYPE REQUIRED DESCRIPTION
code string required Paidy-defined reason code for the request. Only use one of the following values:
  • consumer.requested
  • subscription.expired
  • merchant.requested
  • fraud.detected
  • general
If you use a value other than the ones listed here, Paidy will return an error.
description string required Additional, more specific details about the reason. This field cannot be empty.

Response

Upon success, returns a 200 HTTP status code and the updated token object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
400
request_content.malformed		 One of the required fields is missing or is not formatted correctly.
If the error title is “Validation of the request content failed”, one of the fields is formatted incorrectly. See the description field in the error object for more details.
If the error title is “Malformed request content”, one of the required fields is missing from the request.
401
authentication.failed		 The authentication was not set or the wrong API key was used.
If the error title is “Authentication invalid”, the API key supplied in the header is not valid.
If the error title is “Authentication required”, the required authentication is missing from the request header.

3-5 Retrieve a token

Example request

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 $'{}'

Example response

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

Retrieves the specified token object. You need a valid token ID, beginning with tok_.

Request

Send a GET request to /tokens/{id}, where {id} is the token ID. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

The body of the request is empty.

Response

Upon success, returns a 200 HTTP status code and the token object. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
401
authentication.failed		 The authentication was not set or the wrong API key was used.
If the error title is “Authentication invalid”, the API key supplied in the header is not valid.
If the error title is “Authentication required”, the required authentication is missing from the request header.

3-6 Retrieve all tokens

Example request

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 $'{}'

Example response

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

Retrieve a list of all tokens, with a status of ACTIVE or SUSPENDED, for all your consumers.

Request

Send a GET request to /tokens/. The header of the request must contain the data necessary for authentication. It can optionally contain the Paidy-Version field; the current version of the API is 2018-04-10.

The body of the request is empty.

Response

Upon success, returns a 200 HTTP status code and an array containing the token objects. Upon failure, returns a 4xx or 5xx HTTP status code and an error object containing the details of the failure.

Error scenarios:

HTTP STATUS/CODE DETAILS
401
authentication.failed		 The authentication was not set or the wrong API key was used.
If the error title is “Authentication invalid”, the API key supplied in the header is not valid.
If the error title is “Authentication required”, the required authentication is missing from the request header.

curl