Payment links
Reusable, shareable links that create one invoice per payer
GET /v1/payment_links
List payment links, newest first.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
limit | query | integer (int32) | 1 to 100, default 10
|
cursor | query | string |
|
active | query | boolean | Only active ( |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | PaymentLinkList application/json | |
| 400 | ErrorResponse application/json |
POST /v1/payment_links
Create a payment link.
A reusable URL that creates one invoice per payer: a fixed price, or an amount the payer chooses
(optionally between min_amount and max_amount). Share url together with your publishable key
({url}&key=cp_…_pk_…). Requires an Idempotency-Key.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
Idempotency-Keyrequired | header | string | Unique per logical operation; retries with the same key are safe. |
Request body
application/json
| Field | Type | Description |
|---|---|---|
amount_type | AmountType or null | |
currencyrequired | string | ISO 4217 code.
|
amount | string or null | The price (
|
min_amount | string or null | Lower bound for |
max_amount | string or null | Upper bound for |
description | string or null | Shown to the payer. At most 500 characters. |
assets | array of string or null | Accepted assets. Omit to use the merchant's defaults at the time each invoice is created. |
quantity_limit | integer (int32) or null | 1 to 1,000,000 payments; omit for unlimited.
|
expires_at | string (date-time) or null | RFC 3339; must be in the future. |
metadata | map of string or null | Up to 20 pairs; keys at most 40 characters, values at most 500. Copied to every invoice. |
active | boolean or null | Default |
Responses
| Status | Description | Body |
|---|---|---|
| 201 | Created | PaymentLink application/json |
| 400 | Invalid request | ErrorResponse application/json |
| 409 | Idempotency-Key reused or in flight | ErrorResponse application/json |
GET /v1/payment_links/{id}
Retrieve a payment link.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | Payment link id (plink_…) |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | PaymentLink application/json | |
| 404 | ErrorResponse application/json |
POST /v1/payment_links/{id}
Update a payment link.
Omitted fields are unchanged; null clears an optional one. active: false deactivates the link:
payers can no longer create invoices from it, and invoices already created are unaffected. Changes
apply to invoices created afterwards. Requires an Idempotency-Key.
Authentication: Secret key
Parameters
| Parameter | In | Type | Description |
|---|---|---|---|
idrequired | path | string | Payment link id (plink_…) |
Idempotency-Keyrequired | header | string | Unique per request |
Request body
application/json
| Field | Type | Description |
|---|---|---|
active | boolean or null |
|
amount_type | AmountType or null | |
currency | string or null | |
amount | string or null | |
min_amount | string or null | |
max_amount | string or null | |
description | string or null | |
assets | array of string or null |
|
quantity_limit | integer (int32) or null |
|
expires_at | string (date-time) or null |
|
metadata | map of string or null | Replaces the metadata. |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | PaymentLink application/json | |
| 400 | ErrorResponse application/json | |
| 404 | ErrorResponse application/json |