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)
masspayouts.asset.received
masspayouts.withdrawal.processing
masspayouts.withdrawal.success
masspayouts.withdrawal.failed
masspayouts.withdrawal.expired
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.
