payzum docs
payzum.comAPI referenceSign in

Mass payouts overview

Pay many recipients from a single funded deposit.

Mass payouts let you pay many recipients from a single funded deposit. Upload a CSV, payzum splits it into batches, broadcasts each batch as a separate on-chain transaction, and webhooks you throughout.

How it works

  1. Upload a CSV — POST the file to the create endpoint for your chain family (UTXO or EVM). payzum parses every row, validates each address, and computes a fee quote.
  2. Review and confirm the quote — The response includes the full quote breakdown. Call confirm when you are ready to fund. This advances the order to pending_deposit.
  3. Fund the deposit address — Send exactly totalToSendRaw base units to the depositAddress returned in the order. payzum detects the deposit on-chain.
  4. Batches broadcast automatically — Once the deposit is confirmed payzum splits recipients into batches and broadcasts each as a separate transaction. You receive a webhook for each batch event.
  5. Terminal state and settlement report — When all batches settle the order transitions to completed (or partial_failed if some batches failed). A settlement CSV is generated and linked in the mass_payout.completed webhook.

CSV format

The same CSV format applies to both UTXO and EVM mass payouts. A header row is required.

| Column | Required | Description | |--------|----------|-------------| | address | yes | Chain-native recipient address | | amount | yes | Decimal string in whole coins or tokens (e.g. 0.001 for BTC, 10.00 for USDC) | | label | no | Optional label for audit trail |

Example CSV:

address,amount,label
bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh,0.001,invoice-1234
bc1q9h6yzs4h88e5tdfud6flrugv0tphq0fgfwytdr,0.0005,invoice-5678

All addresses in a single CSV must belong to the same chain. payzum validates each address against the chain specified in the request and rejects rows with mismatched formats.

Quote fields

The quote object appears in the order response immediately after creation. All *Raw fields are integer strings in the chain's smallest unit (satoshi / koinu / duff for UTXO; token base units for EVM).

| Field | Description | |-------|-------------| | sumRecipientsRaw | Sum of all output amounts in base units | | networkFeeRaw | Estimated miner or gas fee across all batches | | payzumFeeRaw | Service fee (payzumFeeBps basis points of sumRecipientsRaw) | | totalToSendRaw | Total deposit required: sumRecipientsRaw + networkFeeRaw + payzumFeeRaw | | payzumFeeBps | Fee rate in basis points (100 = 1%) |

Fund the deposit address with exactly totalToSendRaw. Sending less causes the order to transition to underfunded after the expiry window; sending more is accepted and the overage is handled per chain policy.

Idempotency

The create endpoint accepts an optional Idempotency-Key request header. Pass a UUID or other unique token per logical operation. If a successful order was already created with the same key the server returns 409 with kind: idempotency_conflict and no duplicate order is created.

Webhooks

payzum emits signed webhook events throughout the order lifecycle. See Mass-payout webhooks for the full event catalog and signature verification.

Key events:

  • mass_payout.created — order confirmed, ready for funding
  • mass_payout.deposit_detected — deposit seen on-chain
  • mass_payout.batch_broadcasted / mass_payout.batch_confirmed — per-batch progress
  • mass_payout.completed — all batches settled; settlement CSV linked
  • mass_payout.partial_failed — some batches failed; operator action may be needed

Chain families

  • UTXO (BTC, LTC, DOGE) — HD-derived deposit address; Payzum holds the signing key. See UTXO mass payouts.
  • EVM (Polygon and more) — on-chain escrow contract; merchant deposits into the contract and Payzum's operator wallet pays gas to distribute. See EVM mass payouts.
← Retries & DLQUTXO mass payouts →