Monetbil Payment API v1

www.monetbil.com
 Monetbil API (Mobile Money) is based on HTTP methods that make it easier to write
applications. You can use any HTTP client in a programming language or even your browser to
interact with the API.

Base URL
Default base URL is:

https://api.monetbil.com/payment/{version}/

Note: For security reasons, all Monetbil APIs are served via HTTPS

only. API currently supports the following functions:

FONCTION DESCRIPTION

placePayment This function starts a payment request, and returns a paymentId.

This function returns the status of a payment after calling the

checkPayment
placePayment
function.

1 Start a Payment Request

The following API allows you to start a Mobile Money payment request.

POST https://api.monetbil.com/payment/v1/placePayment

The payload must be in the JSON format, as described below.

Example

curl -X POST -H "Content-Type: application/json" -d '{

"service": "YOUR_SERVICE_KEY",

"phonenumber": "BUYER_PHONENUMBER",

"amount": "AMOUNT_TO_BE_PAY",

"notify_url": "https://your.server.com/monetbil/notifications",

}' " https://api.monetbil.com/payment/v1/placePayment"

Parameters

PARAMETER DESCRIPTION

Amount you want to charge the consumer for the

amount Mandatory
item ordered.

phonenumber Mandatory Predefined phone number of the user.

service Mandatory Unique key generated by Monetbil for each service.

operator Operator’s code to pre-select by default.

Optional
( see table: Operators list)

currency Currency to be used (XAF)

Optional
( see table: Operators list)

item_ref Optional Unique reference of the article in your system.

payment_ref Optional The unique reference of the command in your system.

Two-letter country code defined in ISO 3166-1 of the

country Optional International Standard. For example, Cameroon is
represented by CM.

user Optional The user who makes the purchase in your system.

first_name Optional First name of the user.

last_name Optional Last name of the user.

email E-mail address of the user. To send the successful payment

Optional
receipt

notify_url Optional Payment result notification

The response contains a paymentId.

Example with MTN Mobile Money

{
"status": REQUEST_ACCEPTED,
"message": payment pending, "channel_ussd":
*126#,
"channel_name": MTN Mobile Money,
"channel": CM_MTNMOBILEMONEY,
"paymentId": 17759286369594791363
}

PARAMETER DESCRIPTION

Status of request:
● REQUEST_ACCEPTED - Everything OK, request queued for processing
● INVALID_REQUEST
● INVALID_SERVICE;
● MISSING_SERVICE
● INVALID_MSISDN
status ● MISSING_MSISDN
● INVALID_COUNTRY
● INVALID_AMOUNT
● SERVICE_DISABLED_BY_ADMIN
● SERVICE_DISABLED_BY_OWNER
● SERVICE_NOT_FOUND
PARAMETER DESCRIPTION

● SERVICE_NOT_APPROVED
● SERVER_ERROR

Message generated by the system:

● payment pending
● service not found
● service not approved
● service disable by admin
● service disable by owner
message
● amount invalid
● invalid country
● invalid phonenumber
● unknow error
● etc.

Channel used to make payment.

● CM_MTNMOBILEMONEY
channel ● CM_ORANGEMONEY
● CM_EUMM
● Etc…

Mobile Operator USSD code

channel_ussd ● *126*1# for MTN Mobile Money
● #150# for Orange Money

channel_name Mobile Operator name

paymentId Transaction ID

payment_url Payment URL if available

 2 Check the status of payment

The following API allows you to check the status of a Mobile Money payment.

POST https://api.monetbil.com/payment/v1/checkPayment

Parameters
You must post the following parameters:

PARAMETRE DESCRIPTION

paymentId Mandatory Payment ID generated after a call to placePayment

Response in JSON format:

HTTP Status Code: 200

PARAMETER DESCRIPTION

paymentId Mandatory Unique pending payment ID.

Message generated by the system:

message Mandatory ● payment pending
● payment finish

Payment data. Present when payment is complete:

● transaction_UUID
● created_date
● start_time
● end_time
● msisdn
● mobile_operator_name_short
transaction Optional ● mobile_operator_namemobile_network_code
● mobile_operator_code
● mobile_country_code
● country_name
● country_code
● country_iso
● user
● amount
PARAMETER DESCRIPTION

● fee
● revenue
● currency
● status (Payment result)
o 1 – Success
o 0 – Failed
o -1 – Cancelled
o -2 - Refunded
● message
● http_user_agent
● device
● device_constructor
● device_model
● os
● os_version
● browser
● browser_version
● ip_address
● isp
● isp_org
● region_code
● region_name
● localisation_string
● query_string
● notify
● item_ref
● payment_ref
● first_name
● last_name
● email
● receipt_sent
● api_call
 Example PHP-cUrl

- PlacePayment
<?php

$data = array(
'service' => 'j9XjZzkFqjeL5fk34e1RNq98thRRwvYf',
'phonenumber' => '237654…….',
'amount' => 100
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.monetbil.com/payment/v1/placePayment');

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_TIMEOUT, 30);

$json = curl_exec($ch);

$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

$jsonArry = json_decode($json, true);

print_r($jsonArry);

Result:

Array (
[status] => REQUEST_ACCEPTED
[message] => payment pending
[channel_ussd] => *126*1#
[channel_name] => MTN Mobile Money
[channel] => CM_MTNMOBILEMONEY
[paymentId] => 61347672161751969872
)
 - CheckPayment
<?php
$data = array(
'paymentId' => '21929552347272263345'
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.monetbil.com/payment/v1/checkPayment');

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HEADER, 0);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data, '', '&'));
curl_setopt($ch, CURLOPT_TIMEOUT, 30);

$json = curl_exec($ch);

$jsonArry = json_decode($json, true);

if (is_array($jsonArry) and array_key_exists('transaction', $jsonArry))
{
$transaction = $jsonArry['transaction'];
$status = $transaction['status'];
if ($status == 1)
{

// Successful payment
}
elseif ($status == - 1)
{

// Transaction cancelled
}
else
{

// Payment failed
}
}
 Operators list

Pays Country Operator Code Preffix Min Max Currency

67,650,651,652,653,654
MTN CM_MTNMOBILEMONEY 1 1 000 000 XAF
,68
CAMEROON [CM] ORANGE CM_ORANGEMONEY 69,655,656,657,658,659 1 1 000 000 XAF
67,650,651,652,653,654
EXPRESS
CM_EUMM ,68,69,655,656,657,658, 100 500 000 XAF
UNION
659
SENEGAL [SN] ORANGE SN_ORANGEMONEY 77,78 1 500 000 XOF
CONGO-KINSHASA ORANGE CD_ORANGEMONEY 80,84,85,89 10 1 000 000 CDF
[CD] AIRTEL CD_AIRTELMONEY 97,99 1 000 1 000 000 CDF
AFRICELL CD_AFRICELL 90,91,054,056,058,058 1 000 1 000 000 CDF

LIBERIA [LR] MTN LR_MTNMOBILEMONEY 88,55 1 170 000 LRD

060,061,062,063,064,06
MTN CG_MTNMOBILEMONEY 1 1 000 000 XAF
5,066,067,068,069
CONGO- 050,051,052,053,055,05
BRAZZAVILLE [CG] 7,059,054,056,058,040,
AIRTEL CG_AIRTELMONEY 1 1 000 000 XAF
041,042,043,044,045,04
6,047,048,049
AIRTEL UG_AIRTELMONEY 70,71,72,73,74,75 500 2 000 000 UGX
UGANDA [UG]
MTN UG_MTNMOBILEMONEY 76,77,78 500 2 000 000 UGX
50,51,52,53,54,56,57,59
MTN BJ_MTNMOBILEMONEY ,61,62,66,67,69,90,91,9 1 2 000 000 XOF
BENIN [BJ] 6,97
55,58,60,63,64,65,68,87
MOOV BJ_MOOVMONEY 1 2 000 000 XOF
,89,92,93,94,95,98,99

GUINEA-CONAKRY MTN GN_MTNMOBILEMONEY 66 GNF

[GN]
ORANGE GN_ORANGEMONEY 62,610,611,612 GNF

INFORMATION
For any information, contact us at [email protected]