Cote d’Ivoire

The 54Pay Collections API enables merchants to accept mobile money payments in Côte d’Ivoire. Each mobile network operator follows a distinct payment completion workflow, as outlined below.

Supported Operators

Operator	Code	Payment Flow
Wave	CIWAV	Payment link redirect
Moov Money	CIMOO	STK Push
Orange Money	CIORA	OTP verification + API completion
MTN	CIMTN	STK Push

Payment Completion Methods

Each operator uses a distinct payment completion mechanism. Understanding these flows is critical for successful integration.

WAVE - Payment Link

After initiating a collection, WAVE returns a payment URL (either paymentCompletionUrl or redirectionUrl). Direct the customer to this link where they'll complete payment through WAVE's interface.

Flow: API Request → Receive Payment Link → Customer Completes Payment via Link

MTN AND MOOV MONEY - STK Push

An STK push notification is sent directly to the customer's device for payment authorization, after the customer authorizes the payment on their device the transaction is completed.

Flow: API Request → STK Push to Customer → Customer Authorizes

ORANGE MONEY - OTP Verification

ORANGE MONEY sends an OTP to the customer's mobile number. Collect this OTP from the customer and include it in the /complete-payin request to complete the transaction.

Flow: API Request → OTP Sent to Customer → Collect OTP → Call /complete-payin with OTP

Authentication

Header	Type	Description
X-module	string	Base64(amount+transactionReference+customerNumber)
X-business	string	Base64-encoded Merchant Public Key: {Base64(Merchant Public Key)}
Content-Type	string	Must be application/json
x-app	string	Must be api

Initiate Collection

Creates a payment collection request.

Endpoint: POST /collection/v1/payin

curl --location 'https://subsidiary.dev.mypaygate.co/collection/v1/payin' --header 'Accept: application/json' --header 'X-module: {Base64(amount+transactionReference+customerNumber)}' --header 'X-business: {Base64(Merchant Public Key)}' --header 'Content-Type: application/json' --header 'X-app: api' --data-raw '{
  "requestHeader": {
      "clientId": "",
      "requestType": "Collections"
  },
  "customerName": "Seydou Traoré",
  "customerEmail": "a@a.com",
  "customerNumber": "225765210000",
  "transactionReference": "TXN10273646",
  "transactionDescription": "Test",
  "transactionAmount": 200,
  "transactionCurrency": "XOF",
  "transactionCountry": "CI",
  "successUrl": "", 
  "errorUrl": "", 
  "cancelUrl": "", 
  "operatorCode": "CIWAV", 
  "webhookUrl": ""
}'

note

Please note amount passed in the request MUST be a multiple of five(5) or one hundred (100). E.g 200, 250, 300…

Sample Response

{
  "responseDetails": {
      "responseCode": "09",
      "responseMessage": "PENDING"
  },
  "transactionReference": "TXN61043784",
  "otpIsRequired": false,
  "lengthOfOtp": 0,
  "paymentCompletionRequired": true,
  "paymentCompletionUrl": "https://pay.wave.com/mocked-payment-url",
  "redirectionRequired": true
}

Initiate Collection - ORANGE MONEY

curl --location 'https://subsidiary.dev.mypaygate.co/collection/v1/payin' --header 'Accept: application/json' --header 'X-module: {Base64(amount+transactionReference+customerNumber)}' --header 'X-business: {Base64(Merchant Public Key)}' --header 'Content-Type: application/json' --header 'X-app: api' --data-raw '{
  "requestHeader": {
      "clientId": "",
      "requestType": "Collections"
  },
  "customerName": "Seydou Traoré",
  "customerEmail": "a@a.com",
  "customerNumber": "225765210000",
  "transactionReference": "TXN10273646",
  "transactionDescription": "Test",
  "transactionAmount": 200,
  "transactionCurrency": "XOF",
  "transactionCountry": "CI",
  "successUrl": "", 
  "errorUrl": "", 
  "cancelUrl": "", 
  "operatorCode": "CIWAV", 
  "webhookUrl": ""
}'

Sample Response

{
  "responseDetails": {
      "responseCode": "09",
      "responseMessage": "PENDING"
  },
  "transactionReference": "TXN23764646",
  "otpIsRequired": true,
  "lengthOfOtp": 4,
  "paymentCompletionRequired": true,
  "paymentCompletionUrl": "/collection/v1/complete-payin",
  "redirectionRequired": false
}

Complete Payment - ORANGE MONEY

ORANGE MONEY sends a 4-digit OTP to the customer's mobile number. Collect this OTP and include it in the complete-payin request.

Endpoint: POST /collection/v1/complete-payin

Additional Parameter: otpCode(OTP received by customer)

'https://subsidiary.dev.mypaygate.co/collection/v1/complete-payin' --header 'Accept: application/json' --header 'X-module: {Base64(amount+transactionReference+customerNumber)}' --header 'X-business: {Base64(Merchant Public Key)}' --header 'Content-Type: application/json' --header 'X-app: api' --data-raw '{
  "requestHeader": {
      "clientId": "",
      "requestType": "Collections"
  },
  "customerName": "Seydou Traoré",
  "customerEmail": "a@a.com",
  "customerNumber": "225765210000",
  "transactionReference": "TXN10273646",
  "transactionDescription": "Test",
  "transactionAmount": 200,
  "otpCode": "1234",
  "transactionCurrency": "XOF",
  "transactionCountry": "CI",
  "successUrl": "", 
  "errorUrl": "", 
  "cancelUrl": "", 
  "operatorCode": "CIORA", 
  "webhookUrl": ""
}'

Webhooks

Payment Status Webhook

The API sends POST requests to your webhookUrl when payment status changes.

Sample Webhook

{
"transaction_reference": "176414160871313",
"transaction_status": "Funds Received",
"transaction_fee": 0,
"amount_received": 10,
"initiated_date": "2025-11-26 08:20:08",
"current_status_date": "2025-11-26 08:29:21",
"received_from": {},
"merchant_reference": "QATXN64936072",
"status": "COMPLETED",
"channel": "MOBILE_MONEY",
"currency_code": "CIV"
}

Webhook Status Values

Status	Description
COMPLETED	Payment successfully received
FAILED	Payment failed or expired

Webhook Implementation

Your webhook endpoint must:

1. Accept POST requests: Listen for incoming webhook notifications
2. Validate payload: Verify merchant_reference matches your records
3. Return 200 OK
4. Process asynchronously: Handle business logic after responding
5. Handle duplicates: Implement idempotency using transaction_reference

Webhook Security

• Verify requests originate from 54Pay IP addresses
• Validate the merchant_reference exists in your system
• Store webhook payloads for audit trail