> ## 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.

# Charges

> The basic unit of demand: a business says 'this customer owes $X', and an agent settles it from its wallet.

# Charges

A **charge** is an intention to collect money. It starts `pending` and becomes `paid` when someone settles it.

```text theme={null}
┌──────────┐   1. create    ┌─────────────┐   2. pay      ┌────────┐
│ Merchant │ ─────────────▶ │ Charge      │ ◀──────────── │ Agent  │
│ (sk_mch_)│                │ (pending)   │               │(pz_sk_)│
└──────────┘                └─────────────┘               └────────┘
                                   │  3. webhooks: charge.succeeded
                                   ▼
                            Merchant balance ↑
```

## Creating a charge

```bash theme={null}
curl -X POST https://your-payzor-host/merchant/charges \
  -H "Authorization: Bearer sk_mch_..." \
  -d '{"amountUsdCents": 200, "description": "API credits pack", "externalId": "order_991"}'
```

* `amountUsdCents`: integer, always cents. `200` = **\$2.00**.
* `externalId`: your own order/invoice id, echoed back so you can reconcile.
* A `charge.created` webhook fires immediately.

## Paying a charge

### From an agent wallet

```bash theme={null}
curl -X POST https://your-payzor-host/charges/chg_xxx/pay \
  -H "Authorization: Bearer pz_sk_..."
```

The payment passes through that agent's [Policy Engine](/concepts/policy-engine). Outcomes: paid instantly, pending human approval, or blocked. The charge is marked with the paying agent's id, method `ledger`, and a payment reference.

### Via x402 (on-chain USDC)

Anyone (even an agent without a Payzor wallet) can settle on-chain:

1. `GET /charges/:id/x402` → `402 Payment Required` with exact terms (amount in USDC, treasury address, network).
2. Sign the payment and retry the same request with header `X-PAYMENT`.
3. Payzor verifies and settles against the facilitator, marks the charge paid with method `x402`, returns the settlement receipt.

See [x402 Payments](/concepts/x402).

## Charge object

```json theme={null}
{
  "chargeId": "chg_834e692669a3f8ad",
  "merchantId": "mch_c8fdac10d39c0c4d",
  "agentId": "agent_6b75c0e895ba9c3d",
  "amountMinor": 200,
  "currency": "USD",
  "description": "API credits pack",
  "status": "paid",
  "method": "ledger",
  "reference": "PAY_63FC9EDD0FAD129D",
  "createdAt": "2026-08-23T04:47:15.162Z",
  "paidAt": "2026-08-23T05:00:57.321Z"
}
```

| Field       | Notes                                                                                                |
| ----------- | ---------------------------------------------------------------------------------------------------- |
| `status`    | `pending` → `paid`. Failed/expired states are on the roadmap; today charges stay pending until paid. |
| `method`    | How it was settled: `ledger` (agent wallet), `paylink` (budget draw), or `x402` (on-chain).          |
| `reference` | Payment reference for reconciliation; matches the agent's audit trail.                               |

<Note>
  Charges are idempotent at the state level: paying an already-paid charge returns the existing paid charge instead of double-charging.
</Note>