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.

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]

You must replace [API-KEY] with your personal 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
confirm`optionnal`	`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
confirm`optionnal`	`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.