Introduction
Diool RESTful API gives you a simple and easy access to multiple service providers, directly from your own app (web, mobile or server) using one single account - the one of your choice.
Featuring the current API functionalities, you will be able to :
- collect digital payments from any payer with a legit account (mobile money or payment cards)
through a unique API Request called directly within your own application.
- make direct Topup on any prepaid account for multiple services providers (Airtime, Cable TV and more...).
- check your user account balance anytime you want and follow closely overall float including revenues
We are constantly improving Diool API. A question, a suggestion, mail us : helpdesk@diool.com
Latest Updates
V2.0 : October 29th, 2018
Diool API Sandbox for user integration and functional testing purposes.V1.1 : September 10th, 2018
Introduction of the "referenceOrder" parameter within the API Payment call request.V1.0 : January 31st, 2018
Generation of Tokens (i.e API Keys)
API Access to functions : balance, airtime, payment
Environments
Diool API features 2 environments to embetter the integration process :
- The SANDBOX environment where developers can run tests of the various API calls and get responses from the system.
- The PROD environment where all calls impact real Diool account and beneficiary user accounts as well.
Therefore, to perform tests on our API, we recommend that you connect to our SANDBOX through the corresponding URI common to all API Calls.
Once you are ready to run real operations with our API, you can connect to our PROD through the corresponding URI common to all API Calls.
So, within this documentation, we have introduce an ENVIRONMENT_URL parameter that can take 2 possible values :
- SANDBOX :
http://apisandbox.diool.com/dioolapi/v1/
- PROD :
https://core.diool.com/dioolapi/v1/
Sandbox Tips
The SANBBOX URI is not secure for http calls.
The SANDBOX has no financial impact neither on Diool, nor on beneficiary account.
The SANDBOX has no financial impact neither on Diool, nor on beneficiary account.
Depending on the beneficiary account or provider, the SANDBOX allows you to test some cases and face a couple of response codes within API responses.
For the provider MTN, all API calls are successfull (Response Code : 0) or need confirmation (Responde Code : 27) .
For the provider Orange all API calls are failed with response code 20
For the provider Nexttel all API calls are failed with response code 4
For the time being, these few cases are the only one that you will be able to test.
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl
-H "Accept: application/json"
-H "Content-Type: application/json"
-H "Authorization: Bearer [API-KEY]"
"https://TYPE_YOUR_URL/"
Make sure to replace
[API-KEY]
with your API key.
To get access to Diool API, you will need :
an existing and eligible Diool Cash Point user account. If you haven't got one already, register online and easily open yourself one. Just fill out this form : Diool Cash Point
a valid Diool API token that you will be able to manage (generate, revoke or renew) directly by yourself within your Diool Cash Point web interface.
All calls to the Diool API must be authenticated through a valid API token. The given API token
can be specified within an HTTP request header. If an invalid API token is passed or if the API
token is missing, a 401 Unauthorized
HTTP status will be returned in both the response headers
and the response status field.
A valid API key is passed in the header Authorization: Bearer [API-KEY]
.
Diool expects for the API key to be included in all API requests to the server in a header that looks like the following:
Content-Type: application/json
Authorization: Bearer [API-KEY]
Providers Identifiers
Diool API uses a specific parameter to the identify all its connected providers.
Here below, you will find a list of the already available ones and the corresponding parameter values :
- 62401 MTN
- 62402 Orange
- 62404 Nexttel
API Calls
Payment Request
curl
-d '{"accountIdentifier":237656560711,"amount":100,
providerIdentifier:"62401",referenceOrder:"12236543874" }'
-H "Authorization: Bearer [API-KEY]"
-H "Content-Type: application/json"
-X POST "ENVIRONMENT_URL/payment"
The above command returns JSON structured like this:
{
"code": 0,
"message": "Payment processed successfully",
"developerMessage": "Payment processed successfully",
"moreInfo": "www.diool.com",
"lang": "en",
"result": {
"paymentRef": 723,
"responseCode": "OK",
"responseMessage": null,
"extPaymentRef": "191826232",
"extPaymentTimestamp": null,
"senderAmount": null,
"senderCurrency": null,
"recipientAmount": null,
"recipientCurrency": null,
"timeStamp": "1512128792475",
"userFees": 2.5
}
}
This endpoint is to charge any payer with a legit account (mobile money or payment cards) and collect all validated payments through Diool in one single account.
All what is needed to be provided is the amount, the account holder ID and a reference order. Current available payment methods are ORANGE Money and MTN MoMo. Ongoing integration features YUP (Société Générale), EUMM (Express Union), Payment Cards (Visa, Mastercard), Bank wire, etc...
Note
The Error code 27 might occur after a Payment Request call to Diool API. It means the same request has to be sent with exactly the same parameters, adding the string parameter "Confirm" with appropriate value being "true" to confirm or "false" to abort
HTTP Request
POST ENVIRONMENT_URL/payment
JSON Body Parameters
Parameter | Types | Description |
---|---|---|
accountIdentifier required |
String |
is the number of the user to charge prefix by country code 237 |
amount required |
Integer |
The amount to charge to the user |
providerIdentifier required |
String |
is the operator service identifier |
referenceOrder required |
String |
is the payment reference order |
confirmoptionnal |
String |
to confirm the same request. Value "true" |
Get Balance Request
curl
-H "Authorization: Bearer [API-KEY]"
-H "Content-Type: application/json"
-X GET "ENVIRONMENT_URL/balance"
The above command returns JSON structured like this:
{
"code": 0,
"message": "Balance retrieved successfully",
"developerMessage": null,
"moreInfo": "www.diool.com",
"lang": "en",
"result": {
"responseCode": "OK",
"responseMessage": "Action succeeded",
"depositAccountBalance": 0.0,
"revenueAccountBalance": 0.0,
"timeStamp": "1511860316473"
}
}
This endpoint is to get details about the current balance which is twofold.
Indeed, Diool balance features a deposit account for the float that you have direct access to, and a revenue account where you collect both your commissions and all validated payments from the payers.
HTTP Request
GET ENVIRONMENT_URL/balance
Query Parameters
No parameters
Send Airtime Request
curl
-d '{"accountIdentifier":237656560711,"amount":100,
providerIdentifier:"62401"}'
-H "Authorization: Bearer [API-KEY]"
-H "Content-Type: application/json"
-X POST "ENVIRONMENT_URL/airtime_credit"
The above command returns JSON structured like this:
{
"code": 0,
"message": "Transfer processed successfully",
"developerMessage": "Transfer processed successfully",
"moreInfo": "www.diool.com",
"lang": "en",
"result": {
"transferRef": 1524014,
"responseCode": "OK",
"responseMessage": null,
"userFees": 0.0,
"userRevenue": 5.0,
"userLoyaltyPoints": null,
"currencyExchangeRate": 1.0,
"extSenderTransactionRef": null,
"extSenderTransactionTimestamp": null,
"extRecipientTransactionRef": "1468066753",
"extRecipientTransactionTimestamp": null,
"senderAmount": null,
"senderCurrency": null,
"recipientAmount": 100.0,
"recipientCurrency": "XAF",
"timeStamp": "1512137304951"
}
}
This endpoint is to topup any beneficiary account for Airtime or any other Prepaid Services.
All what is needed to be provided is the amount and the account holder ID.
The Prepaid Service Provider is optional. For Airtime, the API will even find automatically the Service Provider.
Current available Service Providers are MTN, Orange, Nexttel. Ongoing integration features CANAL+, Yoomee, Camtel, etc...
Note
The Error code 27 might occur after a Airtime Request call to Diool API. It means the same request has to be sent with exactly the same parameters, adding the string parameter "Confirm" with appropriate value being "true" to confirm or "false" to abort
HTTP Request
POST ENVIRONMENT_URL/airtime_credit
JSON Body Parameters
Parameter | Types | Description |
---|---|---|
accountIdentifier required |
Integer |
is the number of the user to charge prefix by country code 237 |
amount required |
Integer |
The amount to charge to the user |
providerIdentifier required |
String |
is the operator service identifier |
confirmoptionnal |
String |
to confirm the same request. Value "true" |
Response Codes
The Diool API uses the following error codes:
Response Code | Meaning |
---|---|
0 | Operation Successful. |
1 | An unexpected error occurred in the system |
2 | The sender does not have a registered internal account. |
3 | Connection failure occurred while requesting external operator system. |
4 | Service type is unavailable. |
6 | Sender Provider is Unknown. |
7 | Recipient Provider is Unknown. |
8 | The external operator system returned an error. |
9 | The transfer issuer can only perform a transfer from its own account! |
11 | The sender does not have enough credit to perform this transfer. |
20 | The external operator system is busy. Please try again. |
27 | Already existing request with the same parameters |
31 | Insufficient Account Credit |
43 | This user does not have any shop assigned |
53 | Unable to lookup. |