Client API: Payments
Payment methods, checkout sessions, and available gateways.
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.
Operations
Section titled Operations| Method | Path | Summary |
|---|---|---|
| GET | /api/v1/payments/attempts |
List payment attempts |
| GET | /api/v1/payments/countries |
Countries a customer can bill from, with the one we think they are in |
| GET | /api/v1/payments/currencies |
Payment currencies a customer can actually be charged in |
| GET | /api/v1/payments/disputes |
List disputes tied to the caller's payment attempts / invoices only |
| GET | /api/v1/payments/gateways |
List live gateway accounts, optionally filtered by pay currency |
| GET | /api/v1/payments/geo-currency |
Unauthenticated country → suggested pay currency (clamped to enabled) |
| 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 |
Create invoice checkout |
| 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 |
List invoice gateways |
| 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 |
Create an in-page Stripe Payment Element intent for an invoice |
| POST | /api/v1/payments/invoices/{invoice_id}/paypal-capture |
Capture an approved PayPal order for a platform invoice |
| GET | /api/v1/payments/methods |
List payment methods |
| POST | /api/v1/payments/methods/confirm |
Confirm payment method |
| POST | /api/v1/payments/methods/setup |
Setup payment method |
| DELETE | /api/v1/payments/methods/{method_id} |
Remove payment method |
| PUT | /api/v1/payments/methods/{method_id}/default |
Set default payment method |
| GET | /api/v1/payments/payment-config |
Eligible gateway accounts + non-secret public config for embedded UIs |
| GET | /api/v1/payments/preference |
Get payment preference |
| PATCH | /api/v1/payments/preference |
Update payment preference |
List payment attempts
Section titled List payment attemptsGET /api/v1/payments/attempts
Authentication: an access token, sent as Authorization: Bearer <token>.
Responses
Section titled 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
Section titled Countries a customer can bill from, with the one we think they are inGET /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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
Payment currencies a customer can actually be charged in
Section titled Payment currencies a customer can actually be charged inGET /api/v1/payments/currencies
Payment currencies a customer can actually be charged in.
Authentication: an access token, sent as Authorization: Bearer <token>.
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
List disputes tied to the caller's payment attempts / invoices only
Section titled List disputes tied to the caller's payment attempts / invoices onlyGET /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
Section titled Parameters| Name | In | Type | Required | Description |
|---|---|---|---|---|
limit |
query | integer | no | Default: 50. |
offset |
query | integer | no | Default: 0. |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
List live gateway accounts, optionally filtered by pay currency
Section titled List live gateway accounts, optionally filtered by pay currencyGET /api/v1/payments/gateways
List live gateway accounts, optionally filtered by pay currency.
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
currency |
query | string or null | no |
country |
query | string or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Unauthenticated country → suggested pay currency (clamped to enabled)
Section titled Unauthenticated country → suggested pay currency (clamped to enabled)GET /api/v1/payments/geo-currency
Unauthenticated country → suggested pay currency (clamped to enabled).
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
Canonical saved-method charge for an invoice (alias of /pay)
Section titled Canonical saved-method charge for an invoice (alias of /pay)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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
invoice_id |
path | integer | yes |
Idempotency-Key |
header | string or null | no |
Request body
Section titled Request bodyapplication/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
Section titled 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
Section titled Create invoice checkoutPOST /api/v1/payments/invoices/{invoice_id}/checkout
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
invoice_id |
path | integer | yes |
Request body
Section titled Request bodyapplication/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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Finalize a platform invoice charge after customer completes SCA
Section titled Finalize a platform invoice charge after customer completes SCAPOST /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
Section titled 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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
List invoice gateways
Section titled List invoice gatewaysGET /api/v1/payments/invoices/{invoice_id}/gateways
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
invoice_id |
path | integer | yes |
currency |
query | string or null | no |
country |
query | string or null | no |
Responses
Section titled 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)
Section titled Charge a saved payment method for an invoice (legacy path; prefer /charge)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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
invoice_id |
path | integer | yes |
Idempotency-Key |
header | string or null | no |
Request body
Section titled Request bodyapplication/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
Section titled 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
Section titled Create an in-page Stripe Payment Element intent for an invoicePOST /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
invoice_id |
path | integer | yes |
Request body
Section titled Request bodyapplication/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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Capture an approved PayPal order for a platform invoice
Section titled Capture an approved PayPal order for a platform invoicePOST /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
Section titled 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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
List payment methods
Section titled List payment methodsGET /api/v1/payments/methods
Authentication: an access token, sent as Authorization: Bearer <token>.
Responses
Section titled 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
Section titled Confirm payment methodPOST /api/v1/payments/methods/confirm
Authentication: an access token, sent as Authorization: Bearer <token>.
Request body
Section titled Request bodyapplication/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
Section titled 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
Section titled Setup payment methodPOST /api/v1/payments/methods/setup
Authentication: an access token, sent as Authorization: Bearer <token>.
Request body
Section titled Request bodyapplication/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
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Remove payment method
Section titled Remove payment methodDELETE /api/v1/payments/methods/{method_id}
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
method_id |
path | integer | yes |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Set default payment method
Section titled Set default payment methodPUT /api/v1/payments/methods/{method_id}/default
Authentication: an access token, sent as Authorization: Bearer <token>.
Parameters
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
method_id |
path | integer | yes |
Responses
Section titled 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
Section titled Eligible gateway accounts + non-secret public config for embedded UIsGET /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
Section titled Parameters| Name | In | Type | Required |
|---|---|---|---|
currency |
query | string or null | no |
country |
query | string or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |
Get payment preference
Section titled Get payment preferenceGET /api/v1/payments/preference
Authentication: an access token, sent as Authorization: Bearer <token>.
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
Update payment preference
Section titled Update payment preferencePATCH /api/v1/payments/preference
Authentication: an access token, sent as Authorization: Bearer <token>.
Request body
Section titled Request bodyapplication/json (required)
| Field | Type | Required |
|---|---|---|
currency |
string or null | no |
country_code |
string or null | no |
auto_pay_enabled |
boolean or null | no |
Responses
Section titled Responses| Status | Meaning |
|---|---|
200 |
Success. |
422 |
The request is not valid. detail lists each problem. |