API changelog

This page helps you keep track of updates to the Paidy API and the online documentation. Updates on this page are organized into 3 categories:

A documentation update is posted when there are only corrections or additions to the online documentation.
A revision is posted when there are changes to the existing API that are backward compatible. Backward compatible changes will not break anything in how Paidy processes your existing requests. Requests that were successfully processed by Paidy before a backwards compatible change will also be successfully processed by Paidy after the change, without you having to make any changes to the requests you send. For example, if we add a new optional field to an object or a new API endpoint. However, sometimes changes may be made to the API that better enforce features previously released. It is important to always code to our API specification or these changes may cause your requests to fail.
Occasionally changes need to be made that are not backward compatible, such as a change to the format of an existing field or some other change that may break your code; these changes will released in a new version of the API. And a release will be posted that highlights the features in the new API version and what has changed from the previous version of the API.

2024-12-19 documentation update

Removed the request body from example GET requests.
Updated the description of the payment verification process.
Updated the following error code descriptions for token requests:
- 401 authentication.failed
- 403 token.suspended
- 403 authorization.failed
- 404 token.not_found

2024-09-19 documentation update

Added descriptions for supported webhook events.
Updated the description for checkout field delivery_locn_type and added "not_primary_home" as a possible value.
Updated the description of the 403 service.forbidden response to "Refund a payment" request.

22024-07-25 documentation update

Added on_close as a callback function of Paidy Checkout for tokens.

2023-02-20 documentation update

Updated the combini fee (in the Branding section and Legal Notation).

2022-08-26 documentation update

Updated the logo_url, days_since_first_transaction, last_order_amount, last_order_at, and last_order_date fields in the Paidy Checkout request.
Updated the browser and OS compatibility information.

2022-03-25 documentation update

Updated the OS compatibility information.
Updated the assets in the branding section.
Updated the site design.

2021-11-01 documentation update

Updated the buyer_data object (subscription_counter and number_of_points fields).
Updated the download link for the Paidy landing page assets.

2021-09-22 documentation update

Updated the Paidy logos and the branding section.

2021-05-13 revision

Modified the origin object of token object. Previously, this field contained data provided by the consumer in checkout. This field now contains data provided in the buyer object of the merchant payload.

2021-04-21 documentation update

Updated the branding section.
Updated the OS compatibility information.

2021-03-01 documentation update

Updated the branding section.

2020-12-03 documentation update

Updated the "Legal notation" section.
Updated the banners in the branding section.

2020-09-15 documentation update

Updated the buyer_data object.
Updated the banners and product name in the branding section.

2020-07-30 documentation update

Updated the TLS version for Paidy Checkout.
Updated the description for shipping address.
Updated the browser and OS compatibility information.

2019-11-29 documentation update

Updated the fee charged for convenience store payments.

2019-09-24 documentation update

Updated the list of IP addresses from which Webhooks are sent.

2018-12-14 documentation update

Corrected the metadata field (the field type is an object).

2018-11-29 revision

Paidy is continually working on improving its security. Since November 19, Paidy Checkout no longer supports TLS 1.0 and 1.1; it only supports TLS 1.2 and above.
Corrected the name1 field in the buyer object; this is a required field.

2018-11-08 documentation update

Updated OS and browser compatibility information in the Paidy Checkout section.

2018-09-28 documentation update

Updated the section about latency and retries for Webhook notifications.
Updated the email and phone fields as “optional” fields in the request payload (for payment creation and token creation). If these fields are included in the payload, they will be pre-filled in the Paidy Checkout app when it launches. If these fields are not included in the payload, the consumer must enter them during checkout.

2018-07-06 revision

Added the user_id field to the buyer_data object; this field is optional.

2018-06-29 documentation update

Corrected the number of retry attempts for failed webhooks. (The system will make up to 15 attempts to resend a notification.)
Added legal notation for the Specified Commercial Transactions Act (特定商取引法の記載).

2018-04-10 release

This version of the API includes changes that are needed to support new types of payments that will be offered by Paidy on a merchant-by-merchant basis in the future. We recommend that merchants use the latest version of the API to take advantage of any features and/or improvements to the service. You can set the version number in the header of each request that is made to the API.

Other than changing the version number in the header of each request, merchants using version 2016-07-01 will not need to make any other additional changes to their implementation, as long as it is correctly implemented. While we recommend that merchants use this version of the API, the previous version of the API (version 2016-07-01) will continue to be supported.

2018-03-29 documentation update

Corrected the name of the token ID parameter that is returned to Paidy Checkout in the callback.

2017-10-24 revision

A new optional field called tier has been added to the payment object. This field will be returned in the (successful) responses to API requests. We continually work to support new types of products and payments and as these are added in the future, this field will be used to identify them. The standard Paidy payment is now referred to as Paidy Classic, and the value of this field for existing payments will default to “classic”.

2017-08-04 documentation update

Added TLS compatibility information.
Removed API libraries section.

2017-04-24 revision

Added information about tokens.

2017-03-31 documentation update

Corrected the shipping_address object that is sent as part of the Paidy Checkout payload; the documentation previously said it was optional, but this object is required.

2017-03-06 documentation update

Corrected the description field and title field in the order items object.
Added browser compatibility information to the Paidy Checkout section.
Added information on how to implement a discount in the order items object.

2016-07-01 release

The 2016-07-01 release provides endpoints for the following API calls:

Capture payment: collects payment when you are ready to charge the customer.
Refund payment: partially or fully refunds a payment capture.
Update payment: updates the order_ref, description, and/or metadata fields for a payment.
Get payment: retrieves a payment.
Close payment: closes an authorized, but uncaptured payment.

Changes from previous release:

The API now uses 4 keys: a public and private key for testing and a public and private key for the production environment.
The format of the endpoints has been updated to include the payment ID. Consequently, the payment ID no longer needs to be sent as a parameter in the API requests. The new endpoint URIs are:
- /payments/{id}/captures
- /payments/{id}/refunds
- /payments/{id}/close
- /payments/{id}
A new optional metadata field has been added to the payment object, the captures object, and the refunds 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.
The order_ref field is not a required field, and does not need to be unique.