Mass Payouts Overview

Abstract

Mass Payouts allow platforms to send multiple payouts in a single API request, streamlining disbursements to many recipients efficiently, reliably, and cost-effectively.

Rather than making individual API calls for each payout, Mass Payouts consolidate:

Operational load (one submission, multiple disbursements)

Network fees (optimized per batch where applicable)

Monitoring (batch-level tracking and reporting)

Liquidity planning (aggregate funding needs, not piecemeal).

Mass Payouts are essential for:

Payroll for remote teams

Merchant settlements

Bulk freelancer payments

Aid disbursements

Platform revenue sharing

Incentive payouts in loyalty programs.

Why Mass Payouts Matter

area	benefit
Operational Efficiency	Submit hundreds or thousands of payouts in one API call.
Reduced Fees	Batch blockchain fees and transaction processing overheads.
Treasury Predictability	Aggregate funding amounts simplifies liquidity forecasting.
Error Handling Efficiency	Bulk-level monitoring with per-payout result tracking.
SLA Management	Align multiple payouts under consistent batch-level monitoring SLAs
B2B Scalability	Serve larger corporate clients with high-volume needs.

Key Design Principles for Mass Payouts

principle	description
Atomic Funding	Batch funding covers all payouts submitted in the batch. No partial underfunding.
Per-Payout Visibility	Each individual payout inside the batch must have a trackable status and Trip lifecycle.
Funding Window Enforcement	Entire batch funding must occur within the quote validity window to lock rates.
Error Isolation	Failure of one payout inside a batch must not block successful payouts unless critical funding issues exist.
Webhook-Based Notification	Webhooks are sent per payout inside the batch, not just at the batch level.
Retry Capabilities	Individual failed payouts can be retried manually or programmatically without affecting the rest of the batch.

Supported Asset Types for Mass Payouts

Bitcoin (BTC)

Stablecoins (USDT, USDC) — specify chain (TRC20, ERC20, etc.)

Fiat currency targets — NGN, GHS, KES, ZAR, VND, etc.

Funding Asset: Must be consistent per batch for simplicity (e.g., all payouts funded via USDT TRC20).

Supported Settlement Targets

Bank accounts (e.g., NIP Nigeria, SEPA Europe)

Mobile money wallets (e.g., MTN Ghana, M-Pesa Kenya)

Crypto wallet addresses (for direct crypto payouts)

High-Level API Flow for Mass Payouts

1. Request a Mass Payout Quote:

Provide list of beneficiaries, amounts, destination currencies.

Bitnob returns total funding amount required, funding address, and batch quote expiry.

2. Initiate Mass Payout:

Submit final structured list tied to the approved quote ID.

3. Fund the Mass Payout:

Pay the funding address or invoice for the full batch amount before expiry.

4. Monitor Mass Payout Processing:

Track each payout individually via webhook events.

Aggregate batch-level status for reporting.

Key Webhook Events (Per Payout in Batch)

payout.transfer.success

payout.transfer.failed

Each payout in a batch emits these two terminal webhooks. Intermediate states (funding received, processing) and expiry are observed by polling GET /api/payouts/:id, not via webhooks.

Each payout inside the batch still generates its own full Trip timeline.

Key Operational Limits and Guidelines

parameter	guideline
Max Payouts Per Batch	5,000 (scalable based on enterprise needs)
Max Batch Funding Window	15 minutes (quote expiry)
Max Funding Confirmation Time	60 minutes from first detection (blockchain funding scenarios)
Partial Batch Failures	Handled per payout — batch does not fail globally if a few payouts encounter issues.
Duplicate Detection	Batches and payouts must include idempotency keys to prevent reprocessing.

Quick Diagram

Closing Note

Mass payouts are not simply "many single payouts."

They require:

Careful batch-level liquidity planning

Funding timing discipline

Per-payout traceability and error isolation

Real-time operational transparency.