Paidy Payments API
Manage payment authorizations, captures, refunds, updates, and closures.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/paidy:paidy-payments-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Paidy Payments API
description: Paidy is a Japanese buy now, pay later (BNPL) and digital payment service that enables Japanese consumers to make purchases and pay later via monthly consolidated billing. Merchants integrate Paidy Checkout (JavaScript) and the Paidy REST API to accept deferred payments, manage authorizations, capture funds, issue refunds, and handle recurring payments via stored tokens.
version: '2018-04-10'
contact:
name: Paidy Developer Support
url: https://paidy.com/merchant/
termsOfService: https://paidy.com/merchant/
license:
name: Proprietary
url: https://paidy.com/merchant/
servers:
- url: https://api.paidy.com
description: Production server
security:
- BearerAuth: []
tags:
- name: Payments
description: Manage payment authorizations, captures, refunds, updates, and closures.
paths:
/payments:
post:
tags:
- Payments
summary: Create a payment
description: Creates a new payment using a stored Paidy token. Used for recurring/subscription billing where the consumer has previously authorized a token via Paidy Checkout.
operationId: createPayment
parameters:
- $ref: '#/components/parameters/PaidyVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
example:
token_id: tok_example123456
amount: 5000
currency: JPY
description: Monthly subscription payment
store_name: My Store
buyer_data:
user_id: usr_12345
ltv: 50000
order_count: 10
billing_address:
line1: Shibuya 1-1
city: Tokyo
state: Tokyo
zip: 150-0001
order:
items:
- quantity: 1
id: prod_001
title: Subscription Plan A
unit_price: 5000
tax: 500
shipping: 0
order_ref: order_20260613_001
shipping_address:
line1: Shibuya 1-1
city: Tokyo
state: Tokyo
zip: 150-0001
responses:
'200':
description: Payment created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payments/{id}:
get:
tags:
- Payments
summary: Retrieve a payment
description: Retrieves a payment by its unique ID, including all captures and refunds.
operationId: getPayment
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/PaidyVersion'
responses:
'200':
description: Payment retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
tags:
- Payments
summary: Update a payment
description: Updates a payment's order reference, description, or metadata. Only these three fields can be updated; all others are ignored.
operationId: updatePayment
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/PaidyVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePaymentRequest'
responses:
'200':
description: Payment updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payments/{id}/captures:
post:
tags:
- Payments
summary: Capture a payment
description: Captures a previously authorized payment. The payment status changes to "closed" after a successful capture. An empty JSON object must be provided in the request body.
operationId: capturePayment
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/PaidyVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CapturePaymentRequest'
example:
metadata: {}
responses:
'200':
description: Payment captured successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payments/{id}/refunds:
post:
tags:
- Payments
summary: Refund a payment
description: Refunds a captured payment, either fully or partially. Requires a capture ID. Omit the amount field for a full refund.
operationId: refundPayment
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/PaidyVersion'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefundPaymentRequest'
example:
capture_id: cap_example123456
amount: 2500
reason: Customer returned item
metadata: {}
responses:
'200':
description: Refund created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/payments/{id}/close:
post:
tags:
- Payments
summary: Close a payment
description: Closes an authorized payment without capturing it. After closing, the payment cannot be captured. An empty JSON object must be provided in the request body.
operationId: closePayment
parameters:
- $ref: '#/components/parameters/PaymentId'
- $ref: '#/components/parameters/PaidyVersion'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Empty object required
example: {}
responses:
'200':
description: Payment closed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Conflict - payment already closed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Refund:
type: object
properties:
id:
type: string
description: Unique refund ID (begins with `ref_`)
example: ref_example123456
created_at:
type: string
format: date-time
description: ISO 8601 creation timestamp
example: '2026-06-13T00:00:00Z'
capture_id:
type: string
description: Associated capture ID
example: cap_example123456
amount:
type: number
format: double
description: Refunded amount in JPY
example: 2500
reason:
type: string
description: Refund reason
example: Customer returned item
metadata:
$ref: '#/components/schemas/Metadata'
Error:
type: object
properties:
status:
type: integer
description: HTTP status code
example: 400
code:
type: string
description: Paidy error code
example: request_content.malformed
message:
type: string
description: Human-readable error description
example: Missing or incorrectly formatted required fields
UpdatePaymentRequest:
type: object
properties:
order_ref:
type: string
description: Merchant-defined order reference ID
example: order_20260613_001
description:
type: string
description: Payment description
example: Updated description
metadata:
$ref: '#/components/schemas/Metadata'
Order:
type: object
required:
- items
properties:
items:
type: array
description: List of order items
items:
$ref: '#/components/schemas/OrderItem'
tax:
type: number
format: double
description: Total tax amount in JPY
example: 500
shipping:
type: number
format: double
description: Total shipping cost in JPY
example: 0
order_ref:
type: string
description: Merchant-defined order reference ID
example: order_20260613_001
updated_at:
type: string
format: date-time
description: ISO 8601 timestamp of last update
readOnly: true
Payment:
type: object
properties:
id:
type: string
description: Unique payment ID (begins with `pay_`)
example: pay_example123456
status:
type: string
description: Current payment status
enum:
- authorized
- closed
- rejected
example: authorized
created_at:
type: string
format: date-time
description: ISO 8601 creation timestamp
example: '2026-06-13T00:00:00Z'
expires_at:
type: string
format: date-time
description: ISO 8601 expiration deadline for authorization
example: '2026-07-13T00:00:00Z'
amount:
type: number
format: double
description: Total payment amount in JPY
example: 5000
currency:
type: string
description: Currency code
example: JPY
description:
type: string
description: Payment description
example: Monthly subscription payment
store_name:
type: string
description: Merchant store name
example: My Store
test:
type: boolean
description: Indicates if this is a test payment
example: false
tier:
type: string
description: Payment tier
example: classic
buyer:
$ref: '#/components/schemas/Buyer'
order:
$ref: '#/components/schemas/Order'
shipping_address:
$ref: '#/components/schemas/Address'
captures:
type: array
description: List of captures for this payment
items:
$ref: '#/components/schemas/Capture'
refunds:
type: array
description: List of refunds for this payment
items:
$ref: '#/components/schemas/Refund'
metadata:
$ref: '#/components/schemas/Metadata'
Metadata:
type: object
description: Key-value map for arbitrary data; maximum 20 keys
additionalProperties:
type: string
maxProperties: 20
example:
custom_field: value
Buyer:
type: object
properties:
name1:
type: string
description: Consumer's full name (kanji/kana)
example: 山田 太郎
name2:
type: string
description: Consumer's name in alternate script
example: Taro Yamada
email:
type: string
format: email
description: Consumer's email address
example: taro@example.com
phone:
type: string
description: Consumer's phone number
example: 090-1234-5678
OrderItem:
type: object
required:
- quantity
- unit_price
properties:
quantity:
type: integer
description: Item quantity
example: 1
id:
type: string
description: Merchant product ID
example: prod_001
title:
type: string
description: Item name for display
example: Subscription Plan A
description:
type: string
description: Item details
example: Monthly subscription
unit_price:
type: number
format: double
description: Per-unit price in JPY; use negative value for discounts
example: 5000
Capture:
type: object
properties:
id:
type: string
description: Unique capture ID (begins with `cap_`)
example: cap_example123456
created_at:
type: string
format: date-time
description: ISO 8601 creation timestamp
example: '2026-06-13T00:00:00Z'
amount:
type: number
format: double
description: Captured amount in JPY
example: 5000
tax:
type: number
format: double
description: Tax amount captured
example: 500
shipping:
type: number
format: double
description: Shipping amount captured
example: 0
items:
type: array
description: Order items captured
items:
$ref: '#/components/schemas/OrderItem'
metadata:
$ref: '#/components/schemas/Metadata'
RefundPaymentRequest:
type: object
required:
- capture_id
properties:
capture_id:
type: string
description: Capture ID to refund (begins with `cap_`)
example: cap_example123456
amount:
type: number
format: double
description: Refund amount in JPY; omit for full refund
example: 2500
reason:
type: string
description: Refund reason description
example: Customer returned item
metadata:
$ref: '#/components/schemas/Metadata'
CapturePaymentRequest:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
CreatePaymentRequest:
type: object
required:
- token_id
- amount
- currency
- buyer_data
- order
- shipping_address
properties:
token_id:
type: string
description: Paidy-generated token ID (begins with `tok_`)
example: tok_example123456
amount:
type: number
format: double
description: Total payment amount including tax and shipping in JPY
example: 5000
currency:
type: string
description: Currency code; must be JPY
enum:
- JPY
example: JPY
description:
type: string
description: Payment description
example: Monthly subscription payment
store_name:
type: string
description: Merchant store name for display
example: My Store
buyer_data:
$ref: '#/components/schemas/BuyerData'
order:
$ref: '#/components/schemas/Order'
metadata:
$ref: '#/components/schemas/Metadata'
shipping_address:
$ref: '#/components/schemas/Address'
Address:
type: object
properties:
line1:
type: string
description: Building or apartment information
example: Shibuya 1-1
line2:
type: string
description: District or land details
example: Apartment 301
city:
type: string
description: Municipality name
example: Tokyo
state:
type: string
description: Prefecture name
example: Tokyo
zip:
type: string
description: Postal code in format NNN-NNNN; required with at least one other field
example: 150-0001
BuyerData:
type: object
required:
- user_id
- ltv
- order_count
- billing_address
properties:
user_id:
type: string
description: Consumer's store user ID
example: usr_12345
age:
type: integer
description: Days since account opening
example: 365
age_platform:
type: integer
description: Days since parent organization account creation
example: 730
account_registration_date:
type: string
format: date
description: Account registration date (YYYY-MM-DD)
example: '2025-06-13'
days_since_first_transaction:
type: integer
description: Days since first transaction, excluding canceled/refunded orders
example: 90
ltv:
type: number
format: double
description: Lifetime value in JPY
example: 50000
order_count:
type: integer
description: Total number of orders made
example: 10
last_order_amount:
type: number
format: double
description: JPY amount of last order
example: 3000
last_order_at:
type: integer
description: Days since last purchase
example: 30
last_order_date:
type: string
format: date
description: Date of last order (YYYY-MM-DD)
example: '2026-05-13'
order_amount_last3months:
type: integer
description: Total spending in last 90 days
example: 15000
order_count_last3months:
type: integer
description: Number of orders in last 90 days
example: 3
additional_shipping_addresses:
type: array
description: Additional delivery locations
items:
$ref: '#/components/schemas/Address'
billing_address:
$ref: '#/components/schemas/Address'
delivery_locn_type:
type: string
description: Delivery location type
enum:
- home
- office
- shop
- combini
- locker
- post_office
- delivery_center
- forwarding_shipment_service
- gift
- not_primary_home
example: home
gender:
type: string
description: Consumer gender
example: Male
subscription_counter:
type: integer
description: Total number of subscription purchases
example: 5
previous_payment_methods:
type: object
description: Boolean flags indicating previously used payment methods
additionalProperties:
type: boolean
number_of_points:
type: integer
description: Accumulated loyalty points
example: 1000
order_item_categories:
type: array
description: Categories of ordered items (comma-separated)
items:
type: string
parameters:
PaidyVersion:
name: Paidy-Version
in: header
required: false
description: API version date. Recommended value is 2018-04-10.
schema:
type: string
example: '2018-04-10'
PaymentId:
name: id
in: path
required: true
description: Unique payment ID (begins with `pay_`)
schema:
type: string
example: pay_example123456
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 'Use your Paidy secret key (prefixed with `sk_`) as the bearer token. Never share your secret key. Use test keys for sandbox testing.
'
externalDocs:
description: Paidy API Reference
url: https://paidy.com/docs/api/en/