Payment Links API

REST API for Payment Links. A Payment Link is a shareable URL where the product IS the payment: an agent reads it and pays over x402/USDC, or a person pays via a Pix QR. One link can advertise more than one settlement method (rail) at once. The gateway verifies the payment before fulfillment and seals a hash-chained receipt. Served at pay_url = https://gw.codespar.dev/pay/<slug>.

Base URL: https://api.codespar.dev

All endpoints require authentication. See Authentication. Endpoints marked admin require a bearer api key OR service auth with an x-codespar-user header for an account admin/owner. Payment Links are project-scoped.

Payment Link object

Accept (settlement rail)

accepts[] carries one entry per rail. A link can offer x402/USDC, Pix/BRL, or both; the payer uses whichever they are provisioned for.

x402 / USDC

{
  "rail": "x402",
  "amount": "0.01",
  "currency": "USDC",
  "pay_to": { "kind": "provisioned", "consumer_id": "your-consumer" }
}

• amount is decimal USDC (up to 6 decimals).
• pay_to.kind: "provisioned" settles to the CodeSpar wallet of consumer_id.
• pay_to.kind: "byo" settles to pay_to.address (a 0x EVM address).

Pix / BRL

{
  "rail": "pix",
  "amount": "5.00",
  "currency": "BRL",
  "pix": { "key": "your-pix-key" }
}

• amount is decimal BRL (up to 2 decimals).
• pix.key (or pix.celcoin_account) is where the Pix payment lands.

Create a payment link

POST /v1/payment-links (admin)

Body

{
  "title": "Coffee",
  "description": "One coffee",
  "accepts": [
    { "rail": "x402", "amount": "0.01", "pay_to": { "kind": "provisioned", "consumer_id": "your-consumer" } },
    { "rail": "pix", "amount": "5.00", "pix": { "key": "your-pix-key" } }
  ],
  "one_time": false,
  "max_uses": 10
}

• slug is optional; a unique one is generated when omitted.
• accepts must have at least one rail.
• one_time, max_uses, expires_at, and redirect_url are all optional.

Response — 201 Created with the Payment Link object.

List payment links

GET /v1/payment-links

Response

{ "payment_links": [/* Payment Link */] }

Get a payment link

GET /v1/payment-links/:id — the Payment Link object, or 404 payment_link_not_found.

Update a payment link

PATCH /v1/payment-links/:id (admin)

Body (at least one field)

{ "title": "...", "description": "...", "active": false, "expires_at": "2026-12-31T00:00:00Z", "redirect_url": "https://..." }

Set active: false to pause the link (it can no longer be paid); true to resume. The accepts rails are fixed at creation and are not editable.

Delete a payment link

DELETE /v1/payment-links/:id (admin) — 204 No Content. Payment Links are config, not audit data; settled receipts are retained independently.

Errors