Overview

The Modem Pay Payouts API allows you to send funds from your business account to users, vendors, or other accounts. Payouts can be made via mobile money, internal (Modem Pay) transfers, or bank transfers (coming soon).

Use cases include:

• User withdrawals
• Vendor payouts
• Payroll and salary disbursements

Payout Parameters

Here’s the general shape of a transfer request:

type TransferParams = {
  amount: number;
  currency: string;
  narration?: string;
  network: string;
  beneficiary_name: string;
  account_number: string;
  metadata?: object;
  callback_url?: string;
};

• amount – The amount to send.
• currency – Currency code (e.g., GMD, USD).
• network – Mobile money provider or transfer channel.
• account_number – Destination account (phone or bank account).
• beneficiary_name – Name of the recipient.
• metadata – Optional key-value pairs for internal tracking.
• callback_url – The endpoint where Modem Pay will send a webhook notification after the payout has been processed.

Payout Object

Once initiated, a transfer is represented as:

type Transfer = {
  id: string;
  business_id: string;
  account_id: string;
  amount: number;
  currency: string;
  type: "self" | "modem-pay" | "mobile-money" | "bank";
  status: "pending" | "completed" | "failed" | "cancelled";
  fee: number;
  balance_before: number;
  balance_after: number;
  transfer_reference: string;
  metadata: object;
  // Optional fields based on type
  network?: string;
  account_number?: string;
  mobile_number?: string;
  bank?: string;
  amount_received?: number;
  otp?: string;
  test_mode: boolean;
  events: object;
  note?: string;
  callback_url?: string;
};

This object is returned on creation and is also sent to your webhook endpoint when status updates occur.

Webhooks

Payouts are asynchronous and may trigger the following webhook events:

• transfer.succeeded
• transfer.failed
• transfer.reversed
• transfer.flagged