Mobile money

Follow these steps to accept payment using our mobile money API:

• Initiate the Payment

• Validate the OTP (optional)

• Check Status

Coverage

The gateway parameter should be set to anyone of the following currencies.

Country	Country Code	Currency	Network
Democratic Republic of the Congo	COD	CDF	vodacom, airtel, orange
Kenya	KEN	KES	mpesa
Uganda	UGA	UGX	airtel, mtn
Senegal	SEN	XOF	free, orange
Ivory Coast (Côte d'Ivoire)	CIV	XOF	mtn, orange
Cameroon	CMR	XAF	mtn, orange
Rwanda	RWA	RWF	airtel, mtn
Zambia	ZMB	ZMW	airtel, mtn, zamtel
Malawi	MWI	MWK	airtel, tnm
Benin	BEN	XOF	mtn, moov
Sierra Leone	SLE	SLE	orange

Initiate the Payment

POST {{env_url}}/pay/aggregators/{{gateway}}/mobilemoney/v3

You would need to pass, as header the x-auth-token. This can be obtained from your merchant dashboard → Settings → Generate API keys → Merchant public key.

Headers

Name	Value
Content-Type	application/json
x-auth-token	Your merchant public key

Request Body (encrypted)

Encryption algorithm here

{
    "message": "encrypted-body"
}

Request Body (plain)

{
   "fullname": "Francisca Reuben",
   "email": "[e-mail]",
   "phone_number": "260953456700",
   "tx_ref": "de43d7a1-569c-4348-abd8-75246e81d500", // must be UUID generated
   "network": "mtn",
   "description": "payment for airpod",
   "country": "ZMB",
   "amount": "10",
   "currency": "ZMW",
   "rate": 1,
   "paymentType": "woo", // should be left has woo
   "sourceCurrency": "ZMW",
   "sourceAmount": 1,
   "rememberMe": false,
   "option": "mpesa"
}

Response

200

{
    "message": "success",
    "error": null,
    "data": {
        "message": "success",
        "error": null,
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "ZMW",
            "message": "Please enter otp",
            "status": "pending",
            "customer": {
                "country": "ZMB",
                "name": "Francisca Reuben",
                "phone_number": "260763456789",
                "operator": "mtn"
            }
        }
    }
}

200

{
    "message": "success",
    "error": null,
    "data": {
        "message": "success",
        "error": null,
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "ZMW",
            "message": "Transaction in progress",
            "status": "pending",
            "customer": {
                "country": "ZMB",
                "name": "Francisca Reuben",
                "phone_number": "260763456789",
                "operator": "mtn"
            }
        }
    }
}

400

{
    "message": "failed",
    "error": "Bad Request",
    "data": {
        "status": "error",
        "error": "failed",
        "message": "Duplicate reference provided"
    }
}

Validate OTP

POST {{env_url}}/pay/aggregators/{{gateway}}/mobilemoney/v3

The customer will need to enter the OTP sent to their provided phone number when the payment is initiated and the message in the response shows "Please enter otp".

You would need to pass, as header the x-auth-token. This can be obtained from your merchant dashboard → Settings → Generate API keys → Merchant public key.

Headers

Name	Value
Content-Type	application/json
x-auth-token	Your merchant public key

Request Body (encrypted)

{
    "message": "encrypted-body"
}

Request Body (plain)

{
    "tx_ref": "de43d7a1-569c-4348-abd8-75246e81d500",
    "otp": "000000"
}

Response

200

{
    "message": "success",
    "error": null,
    "data": {
        "message": "success",
        "error": null,
        "data": {
            "amount": "10",
            "charged_amount": "10",
            "currency": "ZMW",
            "message": "Transaction in progress",
            "status": "pending",
            "customer": {
                "country": "ZMB",
                "name": "Francisca Reuben",
                "phone_number": "260763456789",
                "operator": "mtn"
            }
        }
    }
}

400

{
    "message": "failed",
    "error": "Bad Request",
    "data": {
        "status": "error",
        "error": "failed",
        "message": "Request not processed. Try again later or contact support",
        "data": {}
    }
}

Check Status

Click the "Transaction status" link below to check the status of the transaction by passing your tnx_ref as request body.

Transaction status