payzum docs
payzum.comAPI referenceSign in

Introduction

What payzum is and the core concepts.

payzum is a multi-chain crypto payment processor for merchants. It gives you a single REST API — plus a hosted checkout, an embeddable widget, and drop-in adapters — to accept cryptocurrency payments, manage invoices, and send mass payouts. It is built to plug into the systems you already run: online stores, top-up and wallet-funding flows, shopping carts, and billing platforms.

What payzum is

payzum is a payment layer you connect to your application. Your customers pay in crypto and you get paid in crypto — without building wallet handling, on-chain monitoring, or settlement logic yourself.

You integrate payzum the same way you would any payment provider, choosing whichever surface fits your stack:

  • REST API — create and read invoices programmatically with POST /v1/payment.
  • Hosted checkout — redirect buyers to a ready-made payment page; no frontend code required.
  • Embeddable widget — drop a script tag into any page to open checkout in place.
  • Drop-in adapters — integrate with existing shopping-cart plugins, often with just a base-URL change.

All merchant-facing endpoints live under your payzum API host (for example merchant.payzum.com) on the /v1/* path. See Authentication and Quick start to make your first call.

The crypto-in / crypto-out model

payzum settles exclusively in cryptocurrency. There is no fiat off-ramp. The flow is always:

  1. Buyer sends crypto to a deposit address generated for the invoice.
  2. payzum confirms the payment on-chain and marks the invoice paid.
  3. Merchant receives crypto — forwarded automatically to a merchant-controlled payout address (or swapped to a stablecoin first if auto-convert is on).

If you want to quote prices in USD (or another fiat reference currency), payzum converts at invoice creation time using live market rates. The buyer still pays in crypto; the fiat amount is informational only.

Core concepts

Merchant

A merchant is the entity that owns an API key and receives payments. One user account can manage multiple merchants. Each merchant has its own settings, wallet configuration, and invoice history.

API key

Every authenticated API call carries an x-api-key header tied to a specific merchant. Keys are SHA-256-hashed on the server; the plaintext is shown once at creation and cannot be recovered. See Authentication for details.

Invoice / payment

An invoice (also called a payment in the API) is the core billing primitive. It holds:

  • the amount and currency the buyer must pay
  • the deposit address they must send funds to
  • the current payment status (waiting, partially_paid, finished, expired, …)
  • optional metadata such as your internal order_id

Invoices are created with POST /v1/payment and are immutable once created (amount, currency, and address are fixed).

Hosted checkout

Every invoice response includes an invoice_url. Redirect the buyer there to show the payzum-hosted payment page — QR code, countdown timer, live status updates — without writing any frontend code. For custom UIs, poll the buyer-facing status endpoint directly.

IPN / webhook

When an invoice status changes, payzum delivers a signed HTTP POST (IPN — Instant Payment Notification) to the ipn_callback_url you supplied at invoice creation (or to the merchant-level webhook URL). The payload is HMAC-SHA-512 signed so your backend can verify authenticity. See Webhooks & IPN for the verification recipe.

Settlement and conversion

Funds received for an invoice are non-custodially settled. payzum never holds your funds — deposit addresses are merchant-owned and derived from your configuration. Once a payment confirms, funds are:

  • Forwarded to the payout address you configure for that chain, or
  • Auto-converted to a stablecoin and forwarded to your stablecoin address if auto-convert is enabled.

Conversion between crypto assets (e.g. receiving USDT-TRC20 but wanting BNB) is handled by the swap layer. The settlement currency is always crypto.

Mass payouts

The mass-payout feature lets you send bulk on-chain transfers from a CSV of recipients. It is independent of the invoice flow and is typically used for affiliate payouts, salary disbursements, or grant distributions.

Next steps

Follow the Quick start guide to issue an API key and create your first invoice in under five minutes.

Quick start →