Implement batch disbursement logic for mtn b2 b operations

[Aonlike]

Closes #857

📝 Description

Currently, bulk payouts executed via the platform route through a iterative loop that triggers individual HTTP API calls to mobile money providers. This architecture bottlenecks throughput, exposes the system to provider rate-limiting (429 Too Many Requests), and creates complex failure states if a runtime crash or network failure occurs mid-loop.

This PR implements MTN’s native batch disbursement API within the core financial orchestration engine. Bulk payout requests targeting MTN MoMo are now bundled into atomic batches of up to 100 items, dispatched asynchronously to MTN, and tracked safely via a decoupled background worker.

🚀 Changes

Core Platform & Financial Engine

• MTN Provider Extension: Added sendBatchPayout() and getBatchStatus() methods to src/services/mobilemoney/providers/mtn.ts using MTN’s asynchronous batch orchestration endpoints.
• Database Schema Update: Included a new migration creating a batches tracking table and added a nullable batch_id foreign key to the partitioned transactions table.
• Asynchronous Processing Workers: Integrated a brand new BullMQ worker mtnBatchProcessor inside src/jobs/processors/ tasked with safely polling the third-party infrastructure.
• Atomic Double-Entry Alignment: Implemented individual blast-radius protection inside database transactions. Failures within a processed batch are isolated, triggering individual reversals (refunding Stellar Escrow/HTLC assets) while allowing successful iterations to fully settle.

Testing & Infrastructure

• Mock Server Updates: Upgraded the local provider mock server to handle validation schemas for array collections up to 100 items and mock structural async processing states (PENDING, COMPLETED).
• Unit & Integration Coverage: Drafted specialized unit tests focusing on structural edge cases, such as handling partial failures (e.g., Batch succeeds, but 2 out of 50 phone numbers fail compliance checks on MTN's side).

---

🛠️ Technical Implementation Details

Database Migration Details

-- Migration: 048_add_batch_payout_structures.sql
CREATE TYPE batch_status AS ENUM ('PENDING', 'PROCESSING', 'COMPLETED', 'FAILED', 'PARTIAL_SUCCESS');

CREATE TABLE batches (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    provider_batch_id VARCHAR(255) UNIQUE NOT NULL,
    provider VARCHAR(50) NOT NULL,
    status batch_status NOT NULL DEFAULT 'PENDING',
    total_count INT NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

ALTER TABLE transactions ADD COLUMN batch_id UUID REFERENCES batches(id) ON DELETE SET NULL;
CREATE INDEX idx_transactions_batch_id ON transactions(batch_id) WHERE batch_id IS NOT NULL;

[drips-wave]

@Aonlike Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits