Payout (Mobile Money) API

This endpoint allows you to initiate payouts to recipients via mobile money. This is useful for disbursements, refunds, vendor payments, and marketplace seller settlements.

Endpoint

POST /payments/payout/mobile-money

Headers

Name	Description
`X-API-Key`	Your Zikopay API Key
`X-API-Secret`	Your Zikopay API Secret
`Accept`	Must be `application/json`
`Content-Type`	Must be `application/json`

Request Parameters

Parameter	Type	Required	Description
`amount`	number	Yes	Payout amount in the specified currency
`currency`	string	Yes	Currency code (e.g., XAF, XOF)
`phoneNumber`	string	Yes	Recipient's mobile money phone number with country code
`operator`	string	Yes	Mobile money operator (e.g., `orange_cm`, `mtn_cm`)
`return_url`	string	Yes	URL for status redirection
`cancel_url`	string	Yes	URL for cancellation redirection
`callback_url`	string	Yes	URL where payout status updates will be sent
`description`	string	Yes	Payout description or reason
`payout_details`	object	No	Additional payout metadata
`customer`	object	Yes	Recipient information
`customer.name`	string	Yes	Recipient's full name
`customer.phone`	string	Yes	Recipient's phone number
`customer.email`	string	Yes	Recipient's email address

Example Request

{
  "amount": 100,
  "currency": "XAF",
  "operator": "orange_cm",
  "phoneNumber": "237696447402",
  "return_url": "https://yourwebsite.com/payout/success",
  "cancel_url": "https://yourwebsite.com/payout/cancel",
  "callback_url": "https://yourwebsite.com/api/webhook",
  "description": "Vendor payment for April services",
  "payout_details": {
    "invoice_id": "INV-2025-042",
    "service": "Website development"
  },
  "customer": {
    "name": "John Doe",
    "phone": "696447002",
    "email": "john.doe@example.com"
  }
}

Success Response

{

    "reference": "TXN174506674372585E",
    "amount": 100,
    "currency": "XAF",
    "status": "pending",
    "operator": "orange_cm",
    "message": "Payout initiated."

  }
}

Error Response

{
  "success": false,
  "message": "Failed to initiate payout",
  "errors": {
    "amount": ["Insufficient wallet balance for this payout"],
    "phoneNumber": ["Invalid phone number format for the selected operator"]
  }
}

Response Parameters

Parameter	Type	Description
`reference`	string	Unique transaction reference ID
`amount`	number	Payout amount
`currency`	string	Payout currency
`status`	string	Current payout status: `pending`, `processing`, `completed`, `failed`
`operator`	string	Mobile money operator used
`phoneNumber`	string	Recipient's mobile money number
`fee`	number	Fee charged for the payout
`estimated_delivery`	string	Estimated delivery time for the funds

Transaction Flow

Your application initiates a payout request
Zikopay verifies your wallet has sufficient balance
The payout is queued for processing
Zikopay initiates the transfer to the recipient's mobile money account
Upon completion or failure, Zikopay sends a webhook to your callback_url
The status of the payout is updated in your merchant dashboard

Supported Mobile Money Operators

Operator	Code	Payment Type	Countries	Currencies
MTN Cameroon	`mtn_cm`	MTN Mobile Money	Cameroon	XAF
Orange Cameroon	`orange_cm`	Orange Money	Cameroon	XAF
MTN Côte d'Ivoire	`mtn_ci`	MTN MoMo	Côte d'Ivoire	XOF
Orange Côte d'Ivoire	`orange_ci`	Orange Money	Côte d'Ivoire	XOF
Moov Côte d'Ivoire	`moov_ci`	Moov Money	Côte d'Ivoire	XOF
Wave Côte d'Ivoire	`wave_ci`	Wave Mobile Money	Côte d'Ivoire	XOF
Orange Senegal	`orange_sn`	Orange Money	Senegal	XOF
Free Money Senegal	`free_money_sn`	Free Money	Senegal	XOF
Expresso Senegal	`expresso_sn`	Expresso Money	Senegal	XOF
MTN Benin	`mtn_bj`	MTN Mobile Money	Benin	XOF
Moov Benin	`moov_bj`	Moov Money	Benin	XOF
T Money Togo	`t_money_tg`	T Money	Togo	XOF

Testing

In the test environment, you can simulate different payout outcomes:

Phone Number	Result
237600000001	Successful payout
237600000002	Failed payout (recipient not found)
237600000003	Delayed payout (will succeed after 30 minutes)
237600000004	Cancelled payout

Notes

Payouts require sufficient balance in your merchant wallet
Processing times vary by operator (typically 5 minutes to 24 hours)
Maximum payout limits apply and vary by country and operator
Name verification may be performed by some operators
Payout fees are deducted from your wallet balance, not the payout amount

Code Examples

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payment.zikopay.com/v1/payments/payout/mobile-money",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 100,
    'currency' => 'XAF',
    'phoneNumber' => '237696447402',
    'operator' => 'orange_cm',
    'return_url' => 'https://yourwebsite.com/payout/success',
    'cancel_url' => 'https://yourwebsite.com/payout/cancel',
    'callback_url' => 'https://yourwebsite.com/api/webhook',
    'description' => 'Vendor payment for April services',
    'payout_details' => [
      'invoice_id' => 'INV-2025-042'
    ],
    'customer' => [
      'name' => 'John Doe',
      'phone' => '696447002',
      'email' => 'john.doe@example.com'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Accept: application/json",
    "Content-Type: application/json",
    "X-API-Key: your_api_key",
    "X-API-Secret: your_api_secret"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  $data = json_decode($response, true);
  if ($data['success']) {
    echo "Payout initiated. Reference: " . $data['data']['reference'];
    echo "Estimated delivery: " . $data['data']['estimated_delivery'];
  } else {
    echo "Error: " . $data['message'];
  }
}
?>

JavaScript

const initiatePayout = async () => {
  try {
    const response = await fetch('https://api.payment.zikopay.com/v1/payments/payout/mobile-money', {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'X-API-Key': 'your_api_key',
        'X-API-Secret': 'your_api_secret'
      },
      body: JSON.stringify({
        amount: 100,
        currency: 'XAF',
        phoneNumber: '237696447402',
        operator: 'orange_cm',
        return_url: 'https://yourwebsite.com/payout/success',
        cancel_url: 'https://yourwebsite.com/payout/cancel',
        callback_url: 'https://yourwebsite.com/api/webhook',
        description: 'Vendor payment for April services',
        payout_details: {
          invoice_id: 'INV-2025-042'
        },
        customer: {
          name: 'John Doe',
          phone: '696447002',
          email: 'john.doe@example.com'
        }
      })
    });

    const data = await response.json();

    if (data.success) {
      console.log(`Payout initiated with reference: ${data.data.reference}`);
      console.log(`Estimated delivery: ${data.data.estimated_delivery}`);
    } else {
      console.error('Payout initiation failed:', data.message);
    }
  } catch (error) {
    console.error('Error:', error);
  }
};

Python

import requests
import json

url = "https://api.payment.zikopay.com/v1/payments/payout/mobile-money"

payload = json.dumps({
  "amount": 100,
  "currency": "XAF",
  "phoneNumber": "237696447402",
  "operator": "orange_cm",
  "return_url": "https://yourwebsite.com/payout/success",
  "cancel_url": "https://yourwebsite.com/payout/cancel",
  "callback_url": "https://yourwebsite.com/api/webhook",
  "description": "Vendor payment for April services",
  "payout_details": {
    "invoice_id": "INV-2025-042"
  },
  "customer": {
    "name": "John Doe",
    "phone": "696447002",
    "email": "john.doe@example.com"
  }
})

headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
  'X-API-Key': 'your_api_key',
  'X-API-Secret': 'your_api_secret'
}

response = requests.post(url, headers=headers, data=payload)

if response.status_code == 200:
    data = response.json()
    if data['success']:
        print(f"Payout initiated. Reference: {data['data']['reference']}")
        print(f"Estimated delivery: {data['data']['estimated_delivery']}")
    else:
        print(f"Error: {data['message']}")
else:
    print(f"HTTP Error: {response.status_code}")

Regional Considerations

Service availability: Different operators have varying service availability and processing times
Verification requirements: Some operators require more stringent recipient verification
Transaction limits: Daily and monthly transaction limits vary by country and operator
Bulk payouts: For multiple payouts, consider using our bulk payout API (separate documentation)

Endpoint​

Headers​

Request Parameters​

Example Request​

Success Response​

Error Response​

Response Parameters​

Transaction Flow​

Supported Mobile Money Operators​

Testing​

Notes​

Code Examples​

PHP​

JavaScript​

Python​

Regional Considerations​