Skip to main content

​
Money flow

Payzor has two sides, and the same dollar can travel both. Your agent buys — it pays APIs, services and other businesses. Your business sells — it charges the agents that show up. In between, money is a row in a ledger; at the edges, it is USDC on a chain. This page is the round trip: where money comes in, what happens on each side, and where it ends up.

​
The round trip

Read the diagram as three phases, not five boxes: money enters as USDC, circulates as ledger entries, and leaves as USDC again. The only steps that touch a blockchain are the deposit, an x402 payment, and a withdrawal.

​
1 · Money comes in

Every agent can hold a chain account, custodied by Payzor through Coinbase CDP.
Send USDC to that address from any wallet or exchange. A watcher polls the account and credits the agent’s ledger balance when the deposit lands. For testing, you can also credit the ledger directly:
The ledger balance is what the policy engine checks and what pays charges. The chain balance is the USDC sitting at the address. A deposit turns the second into the first.

​
2a · Buy side — your agent spends

Your agent pays from its ledger balance. Every payment goes through the policy engine first: per-transaction cap, daily cap, allowed categories, and the human-approval threshold.
  • Within the perimeter → the charge is paid immediately.
  • Over the approval threshold → nothing is debited. The payment waits for you to approve it, and only then completes.
  • Outside a hard limit → it is blocked, and the reason is recorded.
Paying a charge from a wallet is an internal transfer: the agent’s balance goes down, the merchant’s balance goes up, and nothing moves on any chain. That is what makes sub-cent payments viable — there is no gas to pay.

​
2b · Sell side — your business collects

Your business publishes something to be paid: a charge, a payment link, a catalog product, or a PayLink with a pre-authorized budget. Then any agent can settle it, in one of two ways:

From a Payzor wallet

The agent carries a pz_sk_ key. The charge is paid from its ledger balance, under its own policy. No chain movement.

On-chain with x402

The agent has no Payzor account at all. It answers the 402 with a signed payment, the facilitator settles in USDC, and the sale closes in the same request.
Either way your merchant balance (balance_minor, always in USD cents) goes up, the audit chain records it, and a charge.succeeded webhook fires.

​
3 · Money goes out

Both sides can take money out to an address they control. Business payouts follow an explicit state machine — a withdrawal is never a single fire-and-forget call:
The destination address is screened for KYT at withdrawal time, not only when you save it. Every request carries an idempotency key, so a retry can never send the funds twice. Agent withdrawals work the same way from the wallet side:
A withdrawal goes out on the same network as the destination address, and every chain has its own USDC contract. Sending to an address on the wrong chain loses the funds and cannot be undone — check the network before you approve. See supported networks.

​
Where the money physically is

The part that is easy to lose track of. An internal balance is a claim on Payzor; the USDC itself sits somewhere specific.
Payouts are funded from the Payzor treasury, which is where on-chain settlements land. That is why a withdrawal is a real transaction with a hash you can look up, while paying a charge between two Payzor accounts is not.

​
Units, once and for all

  • The merchant API speaks USD cents everywhere: amountUsdCents, amountMinor, balance_minor. 2500 is $25.00.
  • The policy engine speaks dollars. The payment machinery converts before evaluating, so a $25.00 link is checked against the agent’s policy as $25.00 — never as 2500.
When you reconcile, compare cents with cents. Mixing the two units by a factor of 100 is the single most common integration bug.