Payout Payment (MTC)

Send payments or transfer money to customers via mobile money or bank accounts. This is ideal for money transfers, payouts, withdrawals, refunds, and any scenario where you need to send money to customers.

Overview

Payout payments (MTC - Merchant to Customer) allow you to send money from your account to customers' mobile money accounts or bank accounts. This is perfect for refunds, payouts, rewards, and any customer disbursements.

Endpoint

POST https://api.bridgeagw.com/make_payment

Request Headers

Authorization: Basic <base64_encoded_credentials>
Content-Type: application/json

Request Body

{
  "service_id": 1,
  "reference": "Refund for Order #123",
  "customer_number": "0541234567",
  "transaction_id": "PAYOUT_001",
  "trans_type": "MTC",
  "amount": 25.50,
  "nw": "MTN",
  "nickname": "John Doe",
  "payment_option": "MOM",
  "currency_code": "GHS",
  "currency_val": "1",
  "callback_url": "https://your-site.com/webhook/payout-status",
  "request_time": "2025-01-15 14:30:00"
}

Parameters

Parameter	Type	Required	Description
`service_id`	integer	Yes	Your service identifier
`reference`	string	Yes	Payout reference/description
`customer_number`	string	Yes	Customer's phone number or bank account number or card number
`transaction_id`	string	Yes	Unique transaction identifier
`trans_type`	string	Yes	Must be "MTC" for payouts
`amount`	number	Yes	Payout amount
`nw`	string	Yes	Network provider or bank code (MTN, VOD, AIR, MAS, VIS, FNB, UBA, etc.)
`nickname`	string	Yes	Customer's display name
`payment_option`	string	Yes	Must be "MOM" for mobile money or "CRD" for card payment or "BNK" for bank transfer
`currency_code`	string	No	Currency code (e.g., "GHS")
`currency_val`	string	No	Currency value
`callback_url`	string	Yes	URL to receive payout notifications
`request_time`	string	Yes	Request timestamp

Supported Networks

The payout API supports mobile money networks, card payments, and bank transfers. Use the appropriate network code (nw parameter) and payment option (payment_option parameter) based on your payout method.

Mobile Money Networks

Network	Code	Description
MTN Mobile Money	`MTN`	MTN Mobile Money
Vodafone Cash	`VOD`	Telecel Cash
AirtelTigo Money	`AIR`	AirtelTigo Money
G-Money	`GMO`	G-Money

Card Networks

Network	Code	Description
Mastercard	`MAS`	Mastercard
Visa	`VIS`	Visa Card

Bank Networks

Bank	Code	Description
Access Bank	`ACB`	Access Bank
ABSA Bank	`ABS`	ABSA Bank
ADB	`ADB`	ADB
Apex Bank	`ARB`	Apex Bank
Bank of Ghana	`BOG`	Bank of Ghana
BOA	`BOA`	BOA
CAL Bank	`CAL`	CAL Bank
CBG	`CBG`	CBG
Ecobank Ghana	`ECO`	Ecobank Ghana
FAB	`FAB`	FAB
FBN Bank	`FBN`	FBN Bank
Fidelity Bank	`FIB`	Fidelity Bank
FNB	`FNB`	FNB
GCB Bank	`GCB`	GCB Bank
GHL Bank	`GHL`	GHL Bank
GT Bank	`GTB`	GT Bank
NIB	`NIB`	NIB
Omni Bank	`OMN`	Omni Bank
PBL	`PRB`	PBL
Republic Bank	`RPB`	Republic Bank
SG	`SGB`	SG
Services Integrity Savings & Loans	`SIS`	Services Integrity Savings & Loans
Standard Chartered	`SCB`	Standard Chartered
Stanbic Bank	`STB`	Stanbic Bank
UBA	`UBA`	UBA
UMB	`UMB`	UMB
Zeepay Ghana	`ZEE`	Zeepay Ghana
Zenith Bank	`ZEB`	Zenith Bank

Response

Success Response (202)

{
  "response_message": "Request successfully received for processing",
  "response_code": "202"
}

Error Response (401)

{
  "response_message": "You are not allowed to use this service",
  "response_code": "100"
}

Example Usage

cURL

curl -X POST "https://api.bridgeagw.com/make_payment" \
  -H "Authorization: Basic <your_credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": 1,
    "reference": "Refund for Order #123",
    "customer_number": "0541234567 or 104321234567 or 012345678901",
    "transaction_id": "PAYOUT_001",
    "trans_type": "MTC",
    "amount": 25.50,
    "nw": "MTN",
    "nickname": "John Doe",
    "payment_option": "MOM",  # Use "BNK" for bank transfers, "CRD" for card payments
    "currency_code": "GHS",
    "currency_val": "1",
    "callback_url": "https://your-site.com/webhook/payout-status",
    "request_time": "2025-01-15 14:30:00"
  }'

JavaScript

const sendPayout = async (customerPhone, amount, network, reference) => {
  const response = await fetch('https://api.bridgeagw.com/make_payment', {
    method: 'POST',
    headers: {
      'Authorization': 'Basic <your_credentials>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      service_id: 1,
      reference: reference,
      customer_number: customerPhone,
      transaction_id: `PAYOUT_${Date.now()}`,
      trans_type: "MTC",
      amount: amount,
      nw: network,
      nickname: "Customer",
      payment_option: "MOM", // Use "BNK" for bank transfers, "CRD" for card payments
      currency_code: "GHS",
      currency_val: "1",
      callback_url: "https://your-site.com/webhook/payout-status",
      request_time: new Date().toISOString()
    })
  });

  const result = await response.json();
  return result;
};

// Usage
sendPayout("0541234567", 25.50, "MTN", "Refund for Order #123")
  .then(result => {
    if (result.response_code === "202") {
      console.log("Payout initiated successfully");
    } else {
      console.error("Payout failed:", result.response_message);
    }
  });

Python

import requests
from datetime import datetime

def send_payout(customer_phone, amount, network, reference):
    url = "https://api.bridgeagw.com/make_payment"
    headers = {
        "Authorization": "Basic <your_credentials>",
        "Content-Type": "application/json"
    }
    data = {
        "service_id": 1,
        "reference": reference,
        "customer_number": customer_phone,
        "transaction_id": f"PAYOUT_{int(datetime.now().timestamp())}",
        "trans_type": "MTC",
        "amount": amount,
        "nw": network,
        "nickname": "Customer",
        "payment_option": "MOM",  # Use "BNK" for bank transfers, "CRD" for card payments
        "currency_code": "GHS",
        "currency_val": "1",
        "callback_url": "https://your-site.com/webhook/payout-status",
        "request_time": datetime.now().isoformat()
    }
    
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Usage
result = send_payout("0541234567", 25.50, "MTN", "Refund for Order #123")
if result['response_code'] == '202':
    print("Payout initiated successfully")
else:
    print(f"Payout failed: {result['response_message']}")

Payout Flow

Initiate Payout: Send payout request with customer details (phone number for mobile money, account number for bank transfer, or card number for card payment)
Funds Verification: System checks your account balance
Payout Processing: Money is transferred to customer's mobile money account, bank account, or card
Customer Notification: Customer receives notification (mobile money notification, bank transfer confirmation, or card payment receipt)
Callback Notification: You receive confirmation via webhook

Use Cases

E-commerce & Marketplaces

Refunds: Return money to customers for cancelled orders
Seller Payouts: Pay marketplace sellers for completed sales
Rewards: Send cashback and loyalty rewards
Commission Payments: Pay affiliates and partners

Financial Services

Loan Disbursements: Send approved loans to borrowers
Insurance Claims: Process insurance claim payments
Investment Returns: Distribute investment profits
Salary Payments: Pay employees and contractors

Gig Economy

Worker Payments: Pay gig workers for completed tasks
Driver Payouts: Pay ride-sharing or delivery drivers
Freelancer Payments: Pay freelancers for completed work
Task Rewards: Reward users for completing tasks

Account Balance Requirements

Before sending payouts, ensure you have sufficient balance:

Check Payout Balance

const checkPayoutBalance = async () => {
  const response = await fetch('https://api.bridgeagw.com/get_account_balance', {
    method: 'POST',
    headers: {
      'Authorization': 'Basic <your_credentials>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      service_id: 1,
      request_time: new Date().toISOString()
    })
  });
  
  const result = await response.json();
  const payoutBalance = result.response_data.payout_balance;
  
  if (payoutBalance < requiredAmount) {
    console.log('Insufficient payout balance. Please fund your wallet.');
  }
};

const processBatchPayouts = async (payouts) => {
  const results = [];
  
  for (const payout of payouts) {
    try {
      const result = await sendPayout(
        payout.phone,
        payout.amount,
        payout.network,
        payout.reference
      );
      results.push({ ...payout, result });
    } catch (error) {
      results.push({ ...payout, error: error.message });
    }
  }
  
  return results;
};

// Usage
const payouts = [
  { phone: "0541234567", amount: 25.50, network: "MTN", reference: "Refund #1" },
  { phone: "0201234567", amount: 15.00, network: "VOD", reference: "Refund #2" },
  { phone: "104321234567", amount: 30.00, network: "UBA", reference: "Bank Payout #1" }
];

processBatchPayouts(payouts).then(results => {
  console.log('Batch payout results:', results);
});

Integration Examples

React Component for Payouts

import React, { useState } from 'react';

const PayoutForm = () => {
  const [formData, setFormData] = useState({
    phone: '',
    amount: '',
    network: 'MTN',
    reference: ''
  });
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);
    
    try {
      const result = await sendPayout(
        formData.phone,
        parseFloat(formData.amount),
        formData.network,
        formData.reference
      );
      
      if (result.response_code === "202") {
        alert('Payout initiated successfully!');
        setFormData({ phone: '', amount: '', network: 'MTN', reference: '' });
      } else {
        alert(`Payout failed: ${result.response_message}`);
      }
    } catch (error) {
      alert(`Error: ${error.message}`);
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        placeholder="Customer Phone/Account/Card Number"
        value={formData.phone}
        onChange={(e) => setFormData({...formData, phone: e.target.value})}
        required
      />
      <input
        type="number"
        placeholder="Amount"
        value={formData.amount}
        onChange={(e) => setFormData({...formData, amount: e.target.value})}
        required
      />
      <select
        value={formData.network}
        onChange={(e) => setFormData({...formData, network: e.target.value})}
      >
        <optgroup label="Mobile Money">
          <option value="MTN">MTN Mobile Money</option>
          <option value="VOD">Vodafone Cash</option>
          <option value="AIR">AirtelTigo Money</option>
          <option value="GMO">G-Money</option>
        </optgroup>
        <optgroup label="Banks">
          <option value="ACB">Access Bank</option>
          <option value="ABS">ABSA Bank</option>
          <option value="UBA">UBA</option>
          <option value="GCB">GCB Bank</option>
          <option value="STB">Stanbic Bank</option>
          <option value="SCB">Standard Chartered</option>
          <option value="ZEB">Zenith Bank</option>
          <option value="ECO">Ecobank Ghana</option>
          <option value="GTB">GT Bank</option>
          <option value="FNB">FNB</option>
        </optgroup>
        <optgroup label="Cards">
          <option value="MAS">Mastercard</option>
          <option value="VIS">Visa</option>
        </optgroup>
      </select>
      <input
        type="text"
        placeholder="Reference"
        value={formData.reference}
        onChange={(e) => setFormData({...formData, reference: e.target.value})}
        required
      />
      <button type="submit" disabled={loading}>
        {loading ? 'Processing...' : 'Send Payout'}
      </button>
    </form>
  );
};

Best Practices

Sufficient Balance: Always check payout balance before sending
Valid Account Details: Ensure phone numbers (for mobile money), bank account numbers (for bank transfers), or card numbers (for card payments) are correct and active
Correct Network Codes: Use the appropriate network code from the Supported Networks table above
Payment Option Matching: Ensure payment_option matches your network type (MOM for mobile money, BNK for bank transfer, CRD for card payment)
Transaction References: Use clear, unique references for tracking
Error Handling: Implement proper error handling for failed payouts
Batch Processing: Process multiple payouts efficiently
Monitoring: Monitor payout success rates and failures

Common Use Cases

E-commerce Refunds: Return money to customers
Marketplace Payouts: Pay sellers and partners
Gig Economy: Pay workers and contractors
Financial Services: Disburse loans and claims
Rewards & Loyalty: Send cashback and bonuses
Emergency Payments: Send urgent payments to customers

Notes

Payouts are processed in real-time
Sufficient payout balance is required
Customer account details must be valid and active:
- Phone numbers for mobile money payouts
- Bank account numbers for bank transfer payouts
- Card numbers for card payment payouts
Use the correct network code (nw) from the Supported Networks table
Ensure payment_option matches your payout method (MOM, BNK, or CRD)
Transaction limits may apply based on network or bank
Always monitor payout success rates
Use appropriate transaction references for easy tracking

Transfer Money / Payout Payment (MTC)