# API reference: Payments

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

## 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](#payment).

## List payments

`GET /api/v1/payments` · Secret key only

| Parameter | Type | Required | |
|---|---|---|---|
| `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". |

Answers `200` with [PaginatedPaymentList](#paginatedpaymentlist).

## Fetch one payment

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

| Parameter | Type | Required | |
|---|---|---|---|
| `payment_id` | uuid | yes |  |

Answers `200` with [Payment](#payment).

## Offer a payment page again

`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](#payment).

## Shapes

### 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](#paymentsmoney) | yes |  |
| `refunded` | [PaymentsMoney](#paymentsmoney) | yes |  |
| `refundable` | [PaymentsMoney](#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](#refund) | yes |  |

### PaginatedPaymentList

| Field | Type | Always there | |
|---|---|---|---|
| `count` | integer | yes |  |
| `results` | list of [Payment](#payment) | yes |  |

### PaymentsMoney

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

### Refund

| Field | Type | Always there | |
|---|---|---|---|
| `id` | uuid | yes |  |
| `amount` | [PaymentsMoney](#paymentsmoney) | yes |  |
| `status` | string | yes | One of `pending`, `succeeded`, `failed`, `cancelled`. |
| `reason` | string | yes |  |
| `created_at` | date-time | yes |  |