Quickstart

In this guide you will:

Create a merchant account and get an API key.
Create a charge for $2.00.
Have an agent pay it from its Payzor wallet.
Watch the money land in your merchant balance.

All you need: a running Payzor API (local or remote) and curl.

Before you start: ask the Payzor operator (or your own console) for:

the base URL, e.g. http://localhost:3040

a console session so you can register your business, and

an agent API key (pz_sk_...) to simulate your customer’s agent.

1. Register your business

Merchant registration happens from a logged-in console session. Log in via the console UI (or your existing JWT flow) and call:

curl -X POST https://your-payzor-host/merchants \
  -H "Authorization: Bearer <CONSOLE_JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Digital Goods"}'

Response: save the API key now, it is shown only once:

{
  "merchantId": "mch_c8fdac10d39c0c4d",
  "apiKey": "sk_mch_3dc34f4326fa081f02b1e552a91b4696bb541572cbe89b23"
}

The sk_mch_... key is stored hashed. If you lose it, issue a new merchant. Treat it like a password.

2. Create a charge

A charge is an intention to collect: “this customer owes me $2.00”. Amounts are integer USD cents.

curl -X POST https://your-payzor-host/merchant/charges \
  -H "Authorization: Bearer sk_mch_..." \
  -H "Content-Type: application/json" \
  -d '{"amountUsdCents": 200, "description": "API credits pack"}'

Response:

{
  "chargeId": "chg_834e692669a3f8ad",
  "merchantId": "mch_c8fdac10d39c0c4d",
  "amountMinor": 200,
  "currency": "USD",
  "description": "API credits pack",
  "status": "pending",
  ...
}

Keep the chargeId; that is what gets paid.

3. Let the agent pay

Your customer’s agent pays from its Payzor wallet using its key. The request goes through the agent’s Policy Engine automatically:

curl -X POST https://your-payzor-host/charges/chg_834e692669a3f8ad/pay \
  -H "Authorization: Bearer pz_sk_agent_key..."

Three possible outcomes:

success

Money moved instantly. You get the settled charge back with a reference.

warning

The amount exceeded the agent’s human-approval threshold. Nothing has been charged yet; a human must approve. Your webhook approval.required fires at the same time.

error

The policy blocked it (limit, category not allowed, insufficient balance). The agent spent nothing.

4. Confirm the money arrived

curl https://your-payzor-host/merchant/me \
  -H "Authorization: Bearer sk_mch_..."

{
  "merchant": {
    "id": "mch_c8fdac10d39c0c4d",
    "name": "Acme Digital Goods",
    "balanceMinor": 200,
    "currency": "USD",
    "payoutAddress": null
  }
}

That’s it: an autonomous agent just paid you, within rules a human defined.

What happened behind the scenes

Every step above emitted events. If you had registered a webhook endpoint first (one POST), you would have received charge.created, payment.succeeded, and charge.succeeded, each signed with HMAC-SHA256. See Webhooks.

Get Started

Core Concepts

Guides

Quickstart

Quickstart

1. Register your business

2. Create a charge

3. Let the agent pay

4. Confirm the money arrived

What happened behind the scenes

Where to go next

Get paid repeatedly

Full API reference

​Quickstart

​1. Register your business

​2. Create a charge

​3. Let the agent pay

​4. Confirm the money arrived

​What happened behind the scenes

​Where to go next

Get paid repeatedly

Full API reference

Quickstart

1. Register your business

2. Create a charge

3. Let the agent pay

4. Confirm the money arrived

What happened behind the scenes

Where to go next