# Client API: Payments

> Payment methods, checkout sessions, and available gateways.

Source: https://docs.coritan.com/api/reference/client/payments/

Payment methods, checkout sessions, and available gateways.

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Client API reference](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/payments/attempts`](#op-get-api-v1-payments-attempts) | List payment attempts |
| GET | [`/api/v1/payments/countries`](#op-get-api-v1-payments-countries) | Countries a customer can bill from, with the one we think they are in |
| GET | [`/api/v1/payments/currencies`](#op-get-api-v1-payments-currencies) | Payment currencies a customer can actually be charged in |
| GET | [`/api/v1/payments/disputes`](#op-get-api-v1-payments-disputes) | List disputes tied to the caller's payment attempts / invoices only |
| GET | [`/api/v1/payments/gateways`](#op-get-api-v1-payments-gateways) | List live gateway accounts, optionally filtered by pay currency |
| GET | [`/api/v1/payments/geo-currency`](#op-get-api-v1-payments-geo-currency) | Unauthenticated country → suggested pay currency (clamped to enabled) |
| POST | [`/api/v1/payments/invoices/{invoice_id}/charge`](#op-post-api-v1-payments-invoices-invoice-id-charge) | Canonical saved-method charge for an invoice (alias of /pay) |
| POST | [`/api/v1/payments/invoices/{invoice_id}/checkout`](#op-post-api-v1-payments-invoices-invoice-id-checkout) | Create invoice checkout |
| POST | [`/api/v1/payments/invoices/{invoice_id}/confirm-payment`](#op-post-api-v1-payments-invoices-invoice-id-confirm-payment) | Finalize a platform invoice charge after customer completes SCA |
| GET | [`/api/v1/payments/invoices/{invoice_id}/gateways`](#op-get-api-v1-payments-invoices-invoice-id-gateways) | List invoice gateways |
| POST | [`/api/v1/payments/invoices/{invoice_id}/pay`](#op-post-api-v1-payments-invoices-invoice-id-pay) | Charge a saved payment method for an invoice (legacy path; prefer /charge) |
| POST | [`/api/v1/payments/invoices/{invoice_id}/pay-intent`](#op-post-api-v1-payments-invoices-invoice-id-pay-intent) | Create an in-page Stripe Payment Element intent for an invoice |
| POST | [`/api/v1/payments/invoices/{invoice_id}/paypal-capture`](#op-post-api-v1-payments-invoices-invoice-id-paypal-capture) | Capture an approved PayPal order for a platform invoice |
| GET | [`/api/v1/payments/methods`](#op-get-api-v1-payments-methods) | List payment methods |
| POST | [`/api/v1/payments/methods/confirm`](#op-post-api-v1-payments-methods-confirm) | Confirm payment method |
| POST | [`/api/v1/payments/methods/setup`](#op-post-api-v1-payments-methods-setup) | Setup payment method |
| DELETE | [`/api/v1/payments/methods/{method_id}`](#op-delete-api-v1-payments-methods-method-id) | Remove payment method |
| PUT | [`/api/v1/payments/methods/{method_id}/default`](#op-put-api-v1-payments-methods-method-id-default) | Set default payment method |
| GET | [`/api/v1/payments/payment-config`](#op-get-api-v1-payments-payment-config) | Eligible gateway accounts + non-secret public config for embedded UIs |
| GET | [`/api/v1/payments/preference`](#op-get-api-v1-payments-preference) | Get payment preference |
| PATCH | [`/api/v1/payments/preference`](#op-patch-api-v1-payments-preference) | Update payment preference |

### List payment attempts {#op-get-api-v1-payments-attempts}

`GET /api/v1/payments/attempts`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].invoice_id` | integer or null |
| `[].user_id` | integer or null |
| `[].user_email` | string or null |
| `[].gateway_name` | string |
| `[].gateway_config_id` | integer or null |
| `[].payment_method_id` | integer or null |
| `[].amount` | integer |
| `[].currency` | string |
| `[].base_amount` | string or null |
| `[].fx_rate` | string or null |
| `[].status` | string |
| `[].gateway_reference` | string or null |
| `[].error_message` | string or null |
| `[].decline_type` | string or null |
| `[].decline_code` | string or null |
| `[].is_auto_charge` | boolean or null |
| `[].charge_schedule_id` | integer or null |
| `[].idempotency_key` | string or null |
| `[].refunded_amount` | integer or null |
| `[].created_at` | string (date-time) |
| `[].completed_at` | string (date-time) or null |
| `[].gateway_response` | object or null |
| `[].client_secret` | string or null |

### Countries a customer can bill from, with the one we think they are in {#op-get-api-v1-payments-countries}

`GET /api/v1/payments/countries`

Countries a customer can bill from, with the one we think they are in.

Served rather than shipped in the bundle so the picker, the currency
default and gateway routing cannot drift apart.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Payment currencies a customer can actually be charged in {#op-get-api-v1-payments-currencies}

`GET /api/v1/payments/currencies`

Payment currencies a customer can actually be charged in.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### List disputes tied to the caller's payment attempts / invoices only {#op-get-api-v1-payments-disputes}

`GET /api/v1/payments/disputes`

List disputes tied to the caller's payment attempts / invoices only.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List live gateway accounts, optionally filtered by pay currency {#op-get-api-v1-payments-gateways}

`GET /api/v1/payments/gateways`

List live gateway accounts, optionally filtered by pay currency.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `currency` | query | string or null | no |
| `country` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Unauthenticated country → suggested pay currency (clamped to enabled) {#op-get-api-v1-payments-geo-currency}

`GET /api/v1/payments/geo-currency`

Unauthenticated country → suggested pay currency (clamped to enabled).

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Canonical saved-method charge for an invoice (alias of /pay) {#op-post-api-v1-payments-invoices-invoice-id-charge}

`POST /api/v1/payments/invoices/{invoice_id}/charge`

Canonical saved-method charge for an invoice (alias of ``/pay``).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `payment_method_id` | integer | yes |
| `amount_cents` | integer or null | no |
| `currency` | string or null | no |
| `amount_usd` | number or string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `invoice_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `gateway_name` | string |
| `gateway_config_id` | integer or null |
| `payment_method_id` | integer or null |
| `amount` | integer |
| `currency` | string |
| `base_amount` | string or null |
| `fx_rate` | string or null |
| `status` | string |
| `gateway_reference` | string or null |
| `error_message` | string or null |
| `decline_type` | string or null |
| `decline_code` | string or null |
| `is_auto_charge` | boolean or null |
| `charge_schedule_id` | integer or null |
| `idempotency_key` | string or null |
| `refunded_amount` | integer or null |
| `created_at` | string (date-time) |
| `completed_at` | string (date-time) or null |
| `gateway_response` | object or null |
| `client_secret` | string or null |

### Create invoice checkout {#op-post-api-v1-payments-invoices-invoice-id-checkout}

`POST /api/v1/payments/invoices/{invoice_id}/checkout`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `gateway_name` | string | yes |
| `return_url` | string | yes |
| `cancel_url` | string | yes |
| `amount_cents` | integer or null | no |
| `currency` | string or null | no |
| `amount_usd` | number or string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Finalize a platform invoice charge after customer completes SCA {#op-post-api-v1-payments-invoices-invoice-id-confirm-payment}

`POST /api/v1/payments/invoices/{invoice_id}/confirm-payment`

Finalize a platform invoice charge after customer completes SCA.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `gateway_name` | query | string | yes |
| `payment_intent_id` | query | string | yes |
| `currency` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List invoice gateways {#op-get-api-v1-payments-invoices-invoice-id-gateways}

`GET /api/v1/payments/invoices/{invoice_id}/gateways`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `currency` | query | string or null | no |
| `country` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Charge a saved payment method for an invoice (legacy path; prefer /charge) {#op-post-api-v1-payments-invoices-invoice-id-pay}

`POST /api/v1/payments/invoices/{invoice_id}/pay`

Charge a saved payment method for an invoice (legacy path; prefer ``/charge``).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `payment_method_id` | integer | yes |
| `amount_cents` | integer or null | no |
| `currency` | string or null | no |
| `amount_usd` | number or string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `invoice_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `gateway_name` | string |
| `gateway_config_id` | integer or null |
| `payment_method_id` | integer or null |
| `amount` | integer |
| `currency` | string |
| `base_amount` | string or null |
| `fx_rate` | string or null |
| `status` | string |
| `gateway_reference` | string or null |
| `error_message` | string or null |
| `decline_type` | string or null |
| `decline_code` | string or null |
| `is_auto_charge` | boolean or null |
| `charge_schedule_id` | integer or null |
| `idempotency_key` | string or null |
| `refunded_amount` | integer or null |
| `created_at` | string (date-time) |
| `completed_at` | string (date-time) or null |
| `gateway_response` | object or null |
| `client_secret` | string or null |

### Create an in-page Stripe Payment Element intent for an invoice {#op-post-api-v1-payments-invoices-invoice-id-pay-intent}

`POST /api/v1/payments/invoices/{invoice_id}/pay-intent`

Create an in-page Stripe Payment Element intent for an invoice.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `gateway_name` | string or null | no |
| `currency` | string or null | no |
| `country_code` | string or null | no |
| `amount_usd` | number or string or null | no |
| `save_method` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Capture an approved PayPal order for a platform invoice {#op-post-api-v1-payments-invoices-invoice-id-paypal-capture}

`POST /api/v1/payments/invoices/{invoice_id}/paypal-capture`

Capture an approved PayPal order for a platform invoice.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `order_id` | query | string | yes |
| `gateway_name` | query | string | yes |
| `currency` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List payment methods {#op-get-api-v1-payments-methods}

`GET /api/v1/payments/methods`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].gateway_name` | string |
| `[].gateway_config_id` | integer or null |
| `[].currency` | string or null |
| `[].method_type` | string |
| `[].display_label` | string |
| `[].brand` | string or null |
| `[].last4` | string or null |
| `[].expires_month` | integer or null |
| `[].expires_year` | integer or null |
| `[].email` | string or null |
| `[].is_default` | boolean |
| `[].is_active` | boolean |
| `[].created_at` | string (date-time) |

### Confirm payment method {#op-post-api-v1-payments-methods-confirm}

`POST /api/v1/payments/methods/confirm`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `gateway_name` | string | yes |
| `session_id` | string | yes |
| `set_as_default` | boolean | no |
| `callback_data` | object or null | no |
| `currency` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `gateway_name` | string |
| `gateway_config_id` | integer or null |
| `currency` | string or null |
| `method_type` | string |
| `display_label` | string |
| `brand` | string or null |
| `last4` | string or null |
| `expires_month` | integer or null |
| `expires_year` | integer or null |
| `email` | string or null |
| `is_default` | boolean |
| `is_active` | boolean |
| `created_at` | string (date-time) |

### Setup payment method {#op-post-api-v1-payments-methods-setup}

`POST /api/v1/payments/methods/setup`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `gateway_name` | string or null | no |
| `currency` | string or null | no |
| `country_code` | string or null | no |
| `return_url` | string | yes |
| `cancel_url` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove payment method {#op-delete-api-v1-payments-methods-method-id}

`DELETE /api/v1/payments/methods/{method_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `method_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set default payment method {#op-put-api-v1-payments-methods-method-id-default}

`PUT /api/v1/payments/methods/{method_id}/default`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `method_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Eligible gateway accounts + non-secret public config for embedded UIs {#op-get-api-v1-payments-payment-config}

`GET /api/v1/payments/payment-config`

Eligible gateway accounts + non-secret public config for embedded UIs.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `currency` | query | string or null | no |
| `country` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get payment preference {#op-get-api-v1-payments-preference}

`GET /api/v1/payments/preference`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Update payment preference {#op-patch-api-v1-payments-preference}

`PATCH /api/v1/payments/preference`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `currency` | string or null | no |
| `country_code` | string or null | no |
| `auto_pay_enabled` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |