Payment Links API — Create and Manage Checkout Pages

The Payment Links API lets you create reusable, shareable checkout pages with a fixed fiat price. Each link gets a permanent URL at /l/{slug} that you can embed in emails, on your site, or share anywhere. You can deactivate or update a link at any time without breaking existing integrations.

All mutating requests (POST, PATCH, DELETE) accept an optional Idempotency-Key header. Supplying the same key within 24 hours returns the cached response instead of creating a duplicate.

The PaymentLink object

string

Unique identifier for the payment link. Format: UUID.

object

string

Always "payment_link".

slug

string

URL-friendly identifier used in the hosted checkout URL: /l/{slug}.

title

string

Display name shown to customers on the checkout page.

description

string | null

Optional longer description displayed below the title. null if not set.

fiatAmount

string

The price of the item as a decimal string, e.g. "99.00". The equivalent crypto amount is calculated at session creation time using a live ETH price feed.

fiatCurrency

string

ISO 4217 three-letter currency code, e.g. "USD". Defaults to "USD" when not specified.

successUrl

string | null

URL to redirect the customer to after a successful payment. null if not set.

cancelUrl

string | null

URL to redirect the customer to if they cancel the checkout. null if not set.

active

boolean

When false, the hosted checkout page returns an error and new sessions cannot be created from this link.

checkoutUrl

string

The fully-qualified URL you share with customers, e.g. https://your-domain.com/l/pro-plan-abc123.

createdAt

string

ISO 8601 timestamp of when the link was created.

updatedAt

string

ISO 8601 timestamp of the most recent update.

POST /payment_links

Creates a new payment link. Returns the link object with a 201 status on success. Required scope: links:write

Request body

title

string

required

The display name shown to customers on the checkout page, e.g. "Pro Plan". Must be at least one character.

fiatAmount

string

required

The price as a decimal string with up to two decimal places, e.g. "99.00" or "9". Do not include currency symbols.

fiatCurrency

string

ISO 4217 three-letter currency code. Defaults to "USD" when omitted. Example: "EUR", "GBP".

description

string

Optional longer description displayed below the title on the checkout page.

successUrl

string

A valid HTTPS URL to redirect the customer to after payment is confirmed.

cancelUrl

string

A valid HTTPS URL to redirect the customer to if they abandon the checkout.

Example request

curl -X POST https://your-domain.com/api/v1/payment_links \
  -H "Authorization: Bearer ck_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-link-v1" \
  -d '{
    "title": "Pro Plan",
    "fiatAmount": "99.00",
    "fiatCurrency": "USD",
    "successUrl": "https://example.com/thanks"
  }'

const link = await client.paymentLinks.create({
  title: "Pro Plan",
  fiatAmount: "99.00",
  fiatCurrency: "USD",
  successUrl: "https://example.com/thanks",
}, { idempotencyKey: "create-link-v1" });

Example response `201`

{
  "id": "pl_01HXYZ",
  "object": "payment_link",
  "slug": "pro-plan-abc123",
  "title": "Pro Plan",
  "description": null,
  "fiatAmount": "99.00",
  "fiatCurrency": "USD",
  "successUrl": "https://example.com/thanks",
  "cancelUrl": null,
  "active": true,
  "checkoutUrl": "https://your-domain.com/l/pro-plan-abc123",
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}

GET /payment_links

Returns a cursor-paginated list of your payment links ordered by creation time, most recent first. Required scope: links:read

Query parameters

limit

integer

Number of results to return. Must be between 1 and 100. Defaults to 25.

starting_after

string

A payment link id to use as a pagination cursor. The response will include links created before this one.

Example request

curl "https://your-domain.com/api/v1/payment_links?limit=10" \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

const { data, hasMore, nextCursor } = await client.paymentLinks.list({ limit: 10 });

Example response `200`

{
  "data": [
    {
      "id": "pl_01HXYZ",
      "object": "payment_link",
      "slug": "pro-plan-abc123",
      "title": "Pro Plan",
      "description": null,
      "fiatAmount": "99.00",
      "fiatCurrency": "USD",
      "successUrl": "https://example.com/thanks",
      "cancelUrl": null,
      "active": true,
      "checkoutUrl": "https://your-domain.com/l/pro-plan-abc123",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "updatedAt": "2024-01-15T10:00:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

GET /payment_links/{id}

Retrieves a single payment link by its ID. Required scope: links:read

Path parameters

string

required

The ID of the payment link to retrieve.

Example request

curl https://your-domain.com/api/v1/payment_links/pl_01HXYZ \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

const link = await client.paymentLinks.retrieve("pl_01HXYZ");

PATCH /payment_links/{id}

Updates an existing payment link. All body fields are optional — only the fields you include are changed. Required scope: links:write

Path parameters

string

required

The ID of the payment link to update.

Request body

title

string

New display name for the link.

description

string

New description. Pass null to clear an existing description.

fiatAmount

string

New decimal price string. Affects only sessions created after the update.

fiatCurrency

string

New ISO 4217 currency code.

successUrl

string

New success redirect URL. Pass null to clear.

cancelUrl

string

New cancel redirect URL. Pass null to clear.

active

boolean

Set to false to deactivate the link and prevent new sessions from being created.

Example request — deactivate a link

curl -X PATCH https://your-domain.com/api/v1/payment_links/pl_01HXYZ \
  -H "Authorization: Bearer ck_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

const updated = await client.paymentLinks.update("pl_01HXYZ", { active: false });

DELETE /payment_links/{id}

Archives and permanently deletes a payment link. The hosted checkout URL will stop working immediately. This action cannot be undone. Required scope: links:write

Path parameters

string

required

The ID of the payment link to delete.

Example request

curl -X DELETE https://your-domain.com/api/v1/payment_links/pl_01HXYZ \
  -H "Authorization: Bearer ck_test_YOUR_KEY"

const deleted = await client.paymentLinks.del("pl_01HXYZ");

Deleting a payment link does not cancel in-progress checkout sessions that were created from it. Those sessions remain valid until they expire or are paid.

​The PaymentLink object

​POST /payment_links

​Request body

​Example request

​Example response 201

​GET /payment_links

​Query parameters

​Example request

​Example response 200

​GET /payment_links/{id}

​Path parameters

​Example request

​PATCH /payment_links/{id}

​Path parameters

​Request body

​Example request — deactivate a link

​DELETE /payment_links/{id}

​Path parameters

​Example request

The PaymentLink object

POST /payment_links

Request body

Example request

Example response `201`

GET /payment_links

Query parameters

Example request

Example response `200`

GET /payment_links/{id}

Path parameters

Example request

PATCH /payment_links/{id}

Path parameters

Request body

Example request — deactivate a link

DELETE /payment_links/{id}

Path parameters

Example request