Charges

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

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

Creating a charge

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

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

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

See x402 Payments.

Charge object

{
  "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.

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

⌘I