Pay-in (Mobile Money) API

This endpoint allows you to initiate mobile money payment requests from your customers. Mobile money is a dominant payment method across Central and West Africa, enabling payments via providers like MTN Mobile Money, Orange Money, and others.

Endpoint

POST /payments/payin/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	Transaction amount in the specified currency
`currency`	string	Yes	Currency code (e.g., XAF, NGN, GHS)
`phoneNumber`	string	Yes	Customer'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 where customer will be redirected after payment
`cancel_url`	string	Yes	URL where customer will be redirected if they cancel
`callback_url`	string	Yes	URL where payment status updates will be sent
`description`	string	Yes	Transaction description
`payment_details`	object	No	Additional payment metadata
`customer`	object	Yes	Customer information
`customer.name`	string	Yes	Customer's full name
`customer.phone`	string	Yes	Customer's phone number
`customer.email`	string	Yes	Customer's email address

Example Request

{
  "amount": 200,
  "currency": "XAF",
  "phoneNumber": "237696447402",
  "operator": "orange_cm",
  "return_url": "https://yourwebsite.com/payment/success",
  "cancel_url": "https://yourwebsite.com/payment/cancel",
  "callback_url": "https://yourwebsite.com/api/webhook",
  "description": "Payment for order #12345",
  "payment_details": {
    "order_id": "12345",
    "items": "Premium subscription"
  },
  "customer": {
    "name": "John Doe",
    "phone": "696447002",
    "email": "john.doe@example.com"
  }
}

Success Response

{
    "error": false,
    "reference": "TXN17494045440D1288",
    "status": "success",
    "message": "Vous devez maintenant confirmer votre transaction"
}

Error Response

{
    "error": true,
    "reference": "TXN17494045440D1288",
    "status": "failed",
    "error_message": "Something went wrong"
}

Response Parameters

Parameter	Type	Description
`reference`	string	Unique transaction reference ID
`currency`	string	Transaction currency
`status`	string	Current transaction status: `pending`, `completed`, `failed`

Transaction Flow

Your application initiates a mobile money payment request
Zikopay sends a payment request to the mobile money provider
The customer receives a prompt on their phone to authorize the payment
After the customer approves or rejects, the mobile money provider sends a status update
Zikopay sends a webhook notification to your callback_url with the payment status
The customer is redirected to your return_url or cancel_url depending on the outcome

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 payment outcomes:

Phone Number	Result
237600000001	Successful payment
237600000002	Failed payment (insufficient funds)
237600000003	Timeout (no response)
237600000004	User cancellation

Notes

Phone numbers should include the country code (e.g., 237 for Cameroon)
Mobile money payment requests expire after 15 minutes if not completed
The account holder name on the mobile money account may be verified against the customer name
Fees are applied according to your merchant agreement and may vary by operator

Code Examples

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.payment.zikopay.com/v1/payments/payin/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' => 200,
    'currency' => 'XAF',
    'phoneNumber' => '237696447402',
    'operator' => 'orange_cm',
    'return_url' => 'https://yourwebsite.com/payment/success',
    'cancel_url' => 'https://yourwebsite.com/payment/cancel',
    'callback_url' => 'https://yourwebsite.com/api/webhook',
    'description' => 'Payment for order #12345',
    'payment_details' => [
      'order_id' => '12345'
    ],
    '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']) {
    // Store the reference for tracking
    $_SESSION['payment_reference'] = $data['data']['reference'];
    echo "Please check your phone to approve the payment request";
  } else {
    echo "Error: " . $data['message'];
  }
}
?>

JavaScript

const initiateMobileMoneyPayment = async () => {
    try {
        const response = await fetch('https://api.payment.zikopay.com/v1/payments/payin/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: 200,
                currency: 'XAF',
                phoneNumber: '237696447402',
                operator: 'orange_cm',
                return_url: 'https://yourwebsite.com/payment/success',
                cancel_url: 'https://yourwebsite.com/payment/cancel',
                callback_url: 'https://yourwebsite.com/api/webhook',
                description: 'Payment for order #12345',
                payment_details: {
                    order_id: '12345'
                },
                customer: {
                    name: 'John Doe',
                    phone: '696447002',
                    email: 'john.doe@example.com'
                }
            })
        });

        const data = await response.json();

        if (data.success) {
            // Show instructions to the customer
            console.log(data.data.instructions);

            // You might want to redirect to a waiting page
            window.location.href = '/payment/waiting?reference=' + data.data.reference;
        } else {
            console.error('Payment initiation failed:', data.message);
        }
    } catch (error) {
        console.error('Error:', error);
    }
};

Python

import requests
import json

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

payload = json.dumps({
  "amount": 200,
  "currency": "XAF",
  "phoneNumber": "237696447402",
  "operator": "orange_cm",
  "return_url": "https://yourwebsite.com/payment/success",
  "cancel_url": "https://yourwebsite.com/payment/cancel",
  "callback_url": "https://yourwebsite.com/api/webhook",
  "description": "Payment for order #12345",
  "payment_details": {
    "order_id": "12345"
  },
  "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"Payment initiated. Reference: {data['data']['reference']}")
        print(f"Instructions: {data['data']['instructions']}")
    else:
        print(f"Error: {data['message']}")
else:
    print(f"HTTP Error: {response.status_code}")

Regional Considerations

Different mobile money operators have unique characteristics:

Orange Money: Typically requires a 4-digit PIN to confirm transactions
MTN Mobile Money: May use USSD prompts or app notifications
Ghana: Mobile money interoperability is more advanced
Nigeria: Often requires BVN (Bank Verification Number) for higher amounts

Always ensure your customer is informed about the payment process specific to their mobile money provider.

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​