API reference: Payments

Every payments endpoint: what it takes, what it answers with, and which key it needs.

Generated from the API itself About 2 minutes View as Markdown

Open a payment page

POST /api/v1/checkouts · Secret key only · needs an Idempotency-Key

Field	Type	Required
`amount`	integer	yes
`currency`	string		Defaults to the project's own. One a project can be priced in, the same list its settings screen offers: counted in hundredths, so JPY, KWD and the like answer invalid_currency.
`description`	string
`customer_email`	email or empty
`customer_name`	string
`success_url`	uri	yes	{id} in it becomes the payment's id.
`cancel_url`	uri	yes	{id} in it becomes the payment's id.
`metadata`	object		Your own references: at most 20 keys, each value text of up to 500 characters. Returned on the payment and in its payment.* events.

Answers 201 with Payment.

GET /api/v1/payments · Secret key only

Parameter	Type
`page`	integer	A page number within the paginated result set.
`page_size`	integer	Number of results to return per page.
`status`	string	One of `created`, `pending`, `requires_action`, `paid`, `failed`, `cancelled`, `expired`, `partially_refunded`, `refunded`.
`subject_id`	string	The subject's id.
`subject_type`	string	For example "bookings.booking".

GET /api/v1/payments/{payment_id} · Secret key only

Parameter	Type	Required
`payment_id`	uuid	yes

Answers 200 with Payment.

POST /api/v1/payments/{payment_id}/checkout · Secret key only

Parameter	Type	Required
`payment_id`	uuid	yes

Field	Type	Required
`success_url`	uri	yes	{id} in it becomes the payment's id.
`cancel_url`	uri	yes	{id} in it becomes the payment's id.
`description`	string

Answers 200 with Payment.

Field	Type	Always there
`id`	uuid	yes
`livemode`	boolean	yes	False for a payment a test key asked for, at the provider's test mode.
`status`	string	yes	One of `created`, `pending`, `requires_action`, `paid`, `failed`, `cancelled`, `expired`, `partially_refunded`, `refunded`.
`amount`	PaymentsMoney	yes
`refunded`	PaymentsMoney	yes
`refundable`	PaymentsMoney	yes
`subject_type`	string	yes
`subject_id`	uuid or null	yes
`customer`	object	yes
`metadata`	object	yes	Your own references, as the checkout was given them. Empty when there were none.
`checkout_url`	string	yes
`checkout_expires_at`	date-time or null	yes
`created_at`	date-time	yes
`paid_at`	date-time or null	yes
`failure_code`	string	yes
`failure_message`	string	yes
`refunds`	list of Refund	yes

Field	Type	Always there
`count`	integer	yes
`results`	list of Payment	yes

Field	Type	Always there
`amount`	integer	yes
`currency`	string	yes

Field	Type	Always there
`id`	uuid	yes
`amount`	PaymentsMoney	yes
`status`	string	yes	One of `pending`, `succeeded`, `failed`, `cancelled`.
`reason`	string	yes
`created_at`	date-time	yes