> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payzor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout

> Create reusable payment links, embed them in your site, and get paid by any agent that arrives.

# Checkout

The merchant side of Payzor is **one piece**: reusable payment links. Create a
link with an amount and description, embed it in your site (iframe or redirect),
and **every agent that lands on it pays its own charge**. The link accumulates
metrics — visits, payments, amount collected — so you can see each link's
performance at a glance.

## Create a payment link

```bash theme={null}
POST /merchant/checkout
Authorization: Bearer sk_mch_...
Content-Type: application/json

{ "amountUsdCents": 2500, "description": "Pro plan (monthly)", "externalId": "INV-2026-001" }
```

<ParamField body="amountUsdCents" type="integer" required>
  Amount due in USD cents, `> 0`.
</ParamField>

<ParamField body="description" type="string" required>
  What the agent is paying for. Shown on the checkout page.
</ParamField>

<ParamField body="externalId" type="string">
  Your own reference (invoice id, order id).
</ParamField>

```json theme={null}
// 201 Created
{
  "checkoutLinkId": "cl_ef7a0f919147edda",
  "checkoutToken": "9NtWVVCYM8vQtKcJ",
  "checkoutUrl": "/checkout/9NtWVVCYM8vQtKcJ",
  "amountMinor": 2500,
  "currency": "USD",
  "description": "Pro plan (monthly)",
  "visits": 0,
  "paymentsCount": 0,
  "totalPaidMinor": 0
}
```

Embed `checkoutUrl` (or the full URL against your origin) in your site:

```html theme={null}
<iframe src="https://payzor.example/checkout/9NtWVVCYM8vQtKcJ" width="400" height="560" frameBorder="0"></iframe>
```

## List your links (with stats)

Every link with its state and metrics: visits, payments, and amount collected.

```bash theme={null}
GET /merchant/checkout-links?limit=50
Authorization: Bearer sk_mch_...
```

```json theme={null}
{
  "links": [
    {
      "checkoutLinkId": "cl_ef7a0f919147edda",
      "checkoutToken": "9NtWVVCYM8vQtKcJ",
      "checkoutUrl": "/checkout/9NtWVVCYM8vQtKcJ",
      "amountMinor": 2500,
      "currency": "USD",
      "description": "Pro plan (monthly)",
      "visits": 3,
      "paymentsCount": 2,
      "totalPaidMinor": 5000,
      "active": true,
      "createdAt": "2026-08-23T10:00:00.000Z"
    }
  ],
  "total": 1
}
```

### Enable / disable a link

```bash theme={null}
PATCH /merchant/checkout-links/:token
Authorization: Bearer sk_mch_...
Content-Type: application/json

{ "active": false }
```

Disabling hides the link from collection without deleting its history.

## Public checkout (no auth)

What the agent sees before paying. Each visit increments the counter.

```bash theme={null}
GET /checkout/:token
```

```json theme={null}
{
  "checkoutLinkId": "cl_ef7a0f919147edda",
  "amountMinor": 2500,
  "currency": "USD",
  "description": "Pro plan (monthly)",
  "merchantName": "Acme Digital Goods",
  "active": true,
  "status": "active",
  "visits": 4,
  "paymentsCount": 2,
  "totalPaidMinor": 5000
}
```

## Pay with a wallet

An agent that carries a `pz_sk_` key settles the charge from its wallet,
subject to its policy. Each call materializes a new charge against the link, so
**the same link can be paid by many agents**.

```bash theme={null}
POST /checkout/:token/pay
Authorization: Bearer pz_sk_...
```

```json theme={null}
// 200 OK
{ "paid": true, "charge": { "chargeId": "chg_...", "status": "paid", "method": "ledger", "reference": "PAY_..." } }
```

```json theme={null}
// 402 — over the agent's human-approval threshold
{ "pendingApproval": true, "reason": "Monto $1.50 supera umbral de aprobación humana", "approvalId": "apr_..." }
```

## Pay on-chain (x402)

Any agent — no wallet, no Payzor citizenship. `GET` returns `402` with the
requirements; a signed retry with `X-PAYMENT` settles.

```bash theme={null}
curl -X GET  http://localhost:3040/checkout/:token/x402
# 402 + requirements; then:
curl -X POST http://localhost:3040/checkout/:token/x402 \
  -H "X-PAYMENT: $(build your signed + payment header)"
```

<Tip>
  Amounts are USD cents throughout the merchant API. The payment machinery
  converts to dollars before the policy engine, so a $25.00 link is checked
      against the agent's policy as $25.00 — not as 2500.
</Tip>

## Errors

| Status | Meaning                 |
| ------ | ----------------------- |
| `404`  | Unknown checkout token. |
| `409`  | Link is disabled.       |