Accept a payment

This is the full integration guide for businesses. At the end you’ll have: charges flowing from your backend, agents paying them, webhooks confirming everything, and your money in a merchant balance.

Prerequisites

A console account on a Payzor deployment.
Your merchant API key (sk_mch_...). If you don’t have one, see Quickstart step 1.

Architecture

Your server never touches agent wallets directly. You create charges; Payzor moves money and tells you what happened via webhooks.

Your backend                Payzor                      Customer's agent
────────────                ──────                      ────────────────
POST /merchant/charges ───▶ charge (pending)
                            ◀────────────────────────── POST /charges/:id/pay
                            policy check → debit wallet
◀── webhook: payment.succeeded / charge.succeeded
GET /merchant/me ─────────▶ balance updated

Step by step

1. Create the charge when it’s time to bill

Wherever you’d normally ask for a card:

curl -X POST https://your-payzor-host/merchant/charges \
  -H "Authorization: Bearer sk_mch_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountUsdCents": 499,
    "description": "Pro plan - August",
    "externalId": "sub_42_invoice_8"
  }'

Store the returned chargeId against externalId in your database.

2. Give the agent something to pay with

The customer’s agent needs to know what to pay. Common patterns:

Your API returns the pay URL. Include "/charges/<id>/pay" in your API response where an agent would look.
Your docs tell agent developers to wire POST /charges/:id/pay into their tool loop.

The agent calls it with its own key; Payzor enforces its policy. You do nothing else.

3. Handle the outcomes

Agent receives	Meaning	What you should do
`{ paid: true, ... }`	Settled	Nothing, webhook will confirm.
`{ pendingApproval: true, approvalId }`	Waiting for the human	Wait; if approved you’ll get `payment.succeeded`.
`{ error: "..." }`	Blocked by policy or balance	Let the agent decide (retry later, downgrade plan…).

4. Verify it landed

Poll GET /merchant/me in dev. In production, rely on webhooks (guide).

Reconciliation

Every settled charge carries:

chargeId: yours to store,
reference: matches the entry in the agent’s audit trail,
agentId: who paid.

For bookkeeping exports, the console user can download GET /export/transactions.csv; every fact with sequence number and chain hash.

Get Started

Core Concepts

Guides

Accept a payment

Accept a payment

Prerequisites

Architecture

Step by step

1. Create the charge when it’s time to bill

2. Give the agent something to pay with

3. Handle the outcomes

4. Verify it landed

Reconciliation

Checklist before going live

​Accept a payment

​Prerequisites

​Architecture

​Step by step

​1. Create the charge when it’s time to bill

​2. Give the agent something to pay with

​3. Handle the outcomes

​4. Verify it landed

​Reconciliation

​Checklist before going live

Accept a payment

Prerequisites

Architecture

Step by step

1. Create the charge when it’s time to bill

2. Give the agent something to pay with

3. Handle the outcomes

4. Verify it landed

Reconciliation

Checklist before going live