payzum docs
payzum.comAPI referenceSign in

UTXO mass payouts

Mass payouts for BTC, LTC, and DOGE.

UTXO mass payouts support Bitcoin, Litecoin, and Dogecoin. payzum derives a unique HD deposit address per order, waits for your funding transaction, then signs and broadcasts batched payout transactions on your behalf.

See Mass payouts overview for the CSV format and quote field reference.

Order lifecycle

pending_quote → pending_deposit → underfunded | funded → executing
  → completed | partial_failed | expired | cancelled | refunded

| Status | Description | |--------|-------------| | pending_quote | Order created; quote computed. Call confirm to proceed. | | pending_deposit | Quote acknowledged; waiting for on-chain deposit. | | underfunded | Expiry elapsed with a partial deposit received. No payout made. | | funded | Full deposit confirmed by the chain watcher. | | executing | Batches being broadcast. | | completed | All batches confirmed. Settlement CSV available. | | partial_failed | Some batches failed permanently. Operator retry required. | | expired | Expiry elapsed with no deposit received. | | cancelled | Cancelled by merchant before funding. | | refunded | Partial funds returned after an underfunded or failed order. |

Endpoints

All endpoints require the X-Api-Key header with your merchant API key.

| Method | Path | Description | |--------|------|-------------| | POST | /v1/mass-payout | Create order (multipart form; optional Idempotency-Key header) | | GET | /v1/mass-payout | List orders (paginated; filter by status, chain) | | GET | /v1/mass-payout/:id | Fetch order with batch detail | | GET | /v1/mass-payout/:id/recipients | Paginated recipient rows | | GET | /v1/mass-payout/:id/report.csv | Settlement CSV (available at terminal state) | | POST | /v1/mass-payout/:id/confirm | Confirm quote; advance to pending_deposit | | POST | /v1/mass-payout/:id/cancel | Cancel order (idempotent) | | POST | /v1/mass-payout/:id/refresh-quote | Recompute network fee and extend expiry |

Create order — request fields

POST /v1/mass-payout accepts multipart/form-data.

| Field | Type | Required | Description | |-------|------|----------|-------------| | chain | string | yes | bitcoin | litecoin | dogecoin | | mode | string | yes | mainnet | testnet | | csv | file | yes | CSV file with header row; columns address, amount, optional label |

Refresh quote

POST /v1/mass-payout/:id/refresh-quote recomputes the network fee estimate and extends the order expiry. Only valid while status is pending_quote or pending_deposit and the deposit has not yet been received. Use this when fee rates have changed since order creation.

Error catalog

Errors returned on create (POST /v1/mass-payout):

| Error kind | HTTP | Description | |------------|------|-------------| | invalid_csv | 400 | Malformed form data, missing field, or CSV parse failure | | invalid_address | 400 | A recipient address failed chain-specific validation (rowIndex and address in the error body) | | over_max_decimals | 400 | Amount precision exceeds chain maximum | | dust_below_threshold | 400 | A recipient amount is below the chain dust limit | | order_too_small | 400 | Total payout sum below the chain minimum order size | | chain_disabled | 400 | Chain is disabled via the operator kill-switch | | idempotency_conflict | 409 | Duplicate Idempotency-Key |

Create order — cURL example

curl -X POST "$PAYZUM_BASE/v1/mass-payout" \
  -H "X-Api-Key: $PAYZUM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "chain=bitcoin" \
  -F "mode=mainnet" \
  -F "csv=@payouts.csv"

The response includes the order object with depositAddress and quote.totalToSendRaw. Fund the deposit address with exactly totalToSendRaw satoshis (or litoshis / koinus for LTC / DOGE) to advance the order.

Confirm order — cURL example

curl -X POST "$PAYZUM_BASE/v1/mass-payout/pzmpo_abc123/confirm" \
  -H "X-Api-Key: $PAYZUM_API_KEY"

Returns the updated order with status: "pending_deposit".

Poll for completion

curl "$PAYZUM_BASE/v1/mass-payout/pzmpo_abc123" \
  -H "X-Api-Key: $PAYZUM_API_KEY" | jq '.order.status'

Poll until status is completed, partial_failed, expired, or cancelled. Subscribe to Mass-payout webhooks to avoid polling.

Download settlement report

curl -o settlement.csv \
  -H "X-Api-Key: $PAYZUM_API_KEY" \
  "$PAYZUM_BASE/v1/mass-payout/pzmpo_abc123/report.csv"

The report is available once the order reaches completed or partial_failed. It includes per-recipient status, batch index, and transaction IDs.

← Mass payouts overviewEVM mass payouts →