Payments

Package commerce is selling: checkout, subscriptions, invoices, spend alerts, payment webhooks and the storefront catalog.

payments

GET /v1/payments/{id}

Read one settled payment by its id

Reads one settled payment out of the caller's org ledger.

The org scopes the read by construction — the ledger is namespaced to it — so an id belonging to another tenant is simply not found rather than found and then filtered. A ledger row that is not a payment is likewise not found, so this cannot be used to walk the org's usage debits.

A named handler, not a closure, so zipdoc can lift this prose into the registry.

POST /v1/payments

Take a card payment and credit the org's balance

Takes a payment: charges a single-use card token and credits the caller's org balance, exactly once.

This is the operation behind "collect money from a customer". It runs the SAME core the console's card top-up runs (commerce billing.TakePayment), so the server-side amount bounds, the idempotency guard and the ledger credit are shared rather than reimplemented — a second charge path would eventually double-charge somebody.

The ORG is the caller's, taken from the validated principal and never from the input, so a payment can only ever credit the account of whoever made the call.

Send an idempotencyKey. An agent retries by construction, and the key is what turns a retry into a replay of the first receipt instead of a second charge.

The answer states whether it settled in SANDBOX or live mode (test), and carries the processor's own reference (processorRef) so the charge can be reconciled against the processor rather than taken on trust.

A named handler, not a closure, so zipdoc can lift this prose into the registry.

Request body — application/json (required)

---

All Hanzo APIs · Interactive reference