# payzum

> Multi-chain crypto payment processor for merchants. Accept stablecoin/crypto
> payments through a REST API designed so existing shopping-cart plugins drop in
> with minimal changes, plus a legacy form-encoded adapter for older carts,
> signed IPN webhooks, a hosted checkout page, and an embeddable JS widget.
> Also sends multi-chain mass payouts (UTXO + EVM) from a single funded deposit,
> and accepts machine-to-machine payments from AI agents via x402.

payzum has three surfaces an integrator may use:
- **Accept payments** (merchant): create invoices and collect crypto.
- **Mass payouts** (treasury): pay many recipients from one deposit.
- **Payzum for Agents (x402)**: accept pay-per-request payments from AI agents (beta).

Base URLs: production `https://merchant.payzum.com`,
staging/sandbox `https://staging.payzum.com`.
All API paths live under the same host: `/v1/*`, `/legacy/*`, `/health`.
Authentication: send your merchant API key in the `x-api-key` header (min 32
chars). Full reference with copy-paste examples: `/llms-full.txt`.

## Official SDKs — use these first
If you are writing PHP or JavaScript/TypeScript, install the official SDK
instead of hand-rolling HTTP and HMAC. The SDKs own the webhook header names
(the single most common integration bug), verify signatures in constant time,
keep decimal amounts exact, and never auto-retry an invoice creation unsafely.
- PHP: `composer require payzum/payzum-php` — https://github.com/payzum-dev/payzum-php
- Node.js / TypeScript: `npm install payzum` — https://github.com/payzum-dev/payzum-node
- Python: the `payzum` name on PyPI is reserved by us; the SDK is not released
  yet — integrate via the REST API below for now.
- Quickstarts in both languages: see `/llms-full.txt` §0.

## Getting started
- Quick start (create your first invoice): https://merchant.payzum.com/docs/getting-started/quick-start
- Authentication & base URLs: see `/llms-full.txt` §1–§2

## Accept payments
- REST API reference: https://merchant.payzum.com/docs/accept-payments/api-reference
- Minimum payment per network: GET /v1/min-amount (below-min invoices are rejected with AMOUNT_BELOW_MINIMUM). The legacy adapter's cmd=rates also returns min_amount/min_amount_usd per currency.
- Hosted checkout (redirect the buyer to `/pay/:invoiceId`): https://merchant.payzum.com/docs/accept-payments/hosted-checkout
- Embeddable JS widget (`window.Payzum`, `data-payzum-link`): https://merchant.payzum.com/docs/accept-payments/embeddable-widget
- Payment links (reusable buttons / shareable links): https://merchant.payzum.com/docs/accept-payments/payment-links
- Reading invoices (`GET /v1/payment(/:id)`, statuses & lifecycle): https://merchant.payzum.com/docs/accept-payments/reading-invoices
- Legacy form-encoded adapter for older shopping-cart plugins (`POST /legacy/api.php`): https://merchant.payzum.com/docs/adapters/legacy-form-adapter

## Webhooks & signature verification
- Overview & verification: https://merchant.payzum.com/docs/webhooks/overview
- Payment IPN — fixed header `x-nowpayments-sig`, HMAC-SHA-512 over the raw body: https://merchant.payzum.com/docs/webhooks/payment-ipn
- Payment IPN, CoinPayments-compatible merchants — merchants who were issued CoinPayments keys receive the CP shape instead: header `HMAC`, HMAC-SHA-512 over the form-encoded body: https://merchant.payzum.com/docs/adapters/coinpayments
- Mass-payout webhooks — header `X-Payzum-Signature`, HMAC-SHA-256 over the raw body: https://merchant.payzum.com/docs/webhooks/mass-payout-webhooks
- Retries & DLQ (replay failed deliveries): https://merchant.payzum.com/docs/webhooks/retries-dlq
- Always verify against the raw request bytes, before JSON parsing.
- Header names are case-insensitive per RFC 9110 — look them up case-insensitively. Do NOT make the header name configurable: each webhook family has exactly one, listed above.

## Mass payouts
- Overview (CSV, quotes, fees): https://merchant.payzum.com/docs/payouts/overview
- UTXO (BTC/LTC/DOGE) — one CSV in, batched outputs from one deposit: https://merchant.payzum.com/docs/payouts/utxo-mass-payouts
- EVM (Polygon and more) — token transfers from a funded operator wallet: https://merchant.payzum.com/docs/payouts/evm-mass-payouts

## Payzum for Agents (x402)
- Overview — accept pay-per-request payments from AI agents (beta): https://merchant.payzum.com/docs/agents/x402-overview
- Integration — protect routes and accept agent payments: https://merchant.payzum.com/docs/agents/x402-integration

## Reference
- Supported chains & tokens — source of truth is `GET /v1/currencies`: https://merchant.payzum.com/docs/getting-started/supported-chains
- Errors, rate limits, invoice lifecycle: https://merchant.payzum.com/docs/reference/errors
- Interactive API explorer (OpenAPI): https://merchant.payzum.com/api/docs
- Full machine-readable reference for agents: https://merchant.payzum.com/llms-full.txt