Getting Started with the Diool API | Introduction
Our RESTful API gives you the possibility to integrate your website or application with the Diool API and begin collecting payments via mobile money in Cameroon.
The Diool API will enable you to:
Collect digital payments from any payer with a valid mobile money account through a unique, one-time API Request called directly from within your own application.
Transfer funds from a Diool account to any beneficiary with a valid mobile money account.
Check your Diool account balance and revenue.
Check the status of a transaction.
To quickly get up and running with the Diool API, you can follow the steps in this guide. We recommend using our sandbox environment to test the API, but the same steps are applicable for our production environment, bearing some changes to the API tokens and environment URL.
Whether you are using the sandbox or production environment, the main steps will be the same as follow:
Create an account with Diool here. A Starter plan allows you to test in a sandbox environment with simulated responses, while a Pro plan or above allows you to use Live API tokens and see your account's transactions history.
Refer to the API documentation to understand how it works and how to test or use the main endpoints.
You can refer to this guide to learn how to generate API tokens.
The Diool API features two environments to allow developers to test and deploy their applications :
The SANDBOX environment where developers can run tests of the various API calls and get simulated responses from the system.
The PROD environment where all calls act on real Diool and beneficiary user accounts.
The environment is selected by setting the ENVIRONMENT_URL parameter to one of two possible values :
SANDBOX: https://sandboxcore.diool.com/core/dioolapi/v1/
PROD: https://core.diool.com/core/dioolapi/v1/
Authorization for the Diool API is done through a Bearer Token. We have put together a helpful guide which shows how to generate Diool API tokens.
If you think your keys may have been compromised (for example, you accidentally committed them to Git), you should immediately revoke them and generate new ones using the Generate API Token button on the Settings > API page on your dashboard.
We provide some testing instructions and sample API calls in our API documentation. In this guide, we are going to provide an additional way to test the endpoints using Postman. Feel free to create a free Postman account to test or use any API testing tool you feel comfortable with.
Operations in the SANDBOX environment have no financial impact on actual Diool or beneficiary accounts.
The SANDBOX environment allows you to test with a number of different providers (MTN, Orange), with each operation giving a fixed response regardless of the details of the operation.
For the provider MTN, all API calls respond either as successful (Response Code : 0) or need confirmation (Response Code : 27).
For the provider Orange, all API calls respond with failed (Response Code : 20).
For the PROD environment, you can find the different response codes and their meanings in the Response Codes section of the API documentation. Also see below.
The Diool API uses a code to identify the Provider in a Request. Here are the Providers currently available and their corresponding codes:
MTN : 62401
Orange : 62402
Nexttel : 62404
Express Union : EUMM
If you are testing with Postman, you should save your Diool API token in the Authorization tab with a Type of Bearer Token as shown below for all your requests. The authorization header will be automatically generated when you send the requests. Learn more about authorization.
If it's not already set, you should set the Content-Type to application/json in the Headers tab as shown below. You can ignore the other header parameters.
For the endpoints where you need to pass some parameters with your requests, you can add them to the Body tab in JSON format (raw > JSON) as shown below.
Now that we have covered some of the common points among all the endpoints, let's look at how to use each of them.
There are four main endpoints we are going to test. Follow the links below for steps to use or test each of the endpoints.
Payment endpoint /payment : This endpoint executes a request for payment to a payer identified by a mobile money account number.
Transfer endpoint /transfer : This endpoint executes a request for money to be transferred to a beneficiary identified by a mobile money account.
Balance endpoint /balance : This endpoint executes a request to retrieve the balance associated with a Diool user account.
Transaction Status endpoint /status : This endpoint executes a request to get the status of a particular transaction (payment, transfer, etc.).
Already using or testing the API and need a hand?
Self service: Check out the FAQ.
Have a question..? Chat with us instantly through the Live Chat on our Help Center.
Totally stuck..? Send us a mail at helpdesk@diool.com and we will get back to you as soon as possible.
The Diool API will enable you to:
Collect digital payments from any payer with a valid mobile money account through a unique, one-time API Request called directly from within your own application.
Transfer funds from a Diool account to any beneficiary with a valid mobile money account.
Check your Diool account balance and revenue.
Check the status of a transaction.
To quickly get up and running with the Diool API, you can follow the steps in this guide. We recommend using our sandbox environment to test the API, but the same steps are applicable for our production environment, bearing some changes to the API tokens and environment URL.
Whether you are using the sandbox or production environment, the main steps will be the same as follow:
Create an account with Diool here. A Starter plan allows you to test in a sandbox environment with simulated responses, while a Pro plan or above allows you to use Live API tokens and see your account's transactions history.
Refer to the API documentation to understand how it works and how to test or use the main endpoints.
You can refer to this guide to learn how to generate API tokens.
Testing and Production Environments
The Diool API features two environments to allow developers to test and deploy their applications :
The SANDBOX environment where developers can run tests of the various API calls and get simulated responses from the system.
The PROD environment where all calls act on real Diool and beneficiary user accounts.
The environment is selected by setting the ENVIRONMENT_URL parameter to one of two possible values :
SANDBOX: https://sandboxcore.diool.com/core/dioolapi/v1/
PROD: https://core.diool.com/core/dioolapi/v1/
Authentication
Authorization for the Diool API is done through a Bearer Token. We have put together a helpful guide which shows how to generate Diool API tokens.
If you think your keys may have been compromised (for example, you accidentally committed them to Git), you should immediately revoke them and generate new ones using the Generate API Token button on the Settings > API page on your dashboard.
Testing the API Endpoints
We provide some testing instructions and sample API calls in our API documentation. In this guide, we are going to provide an additional way to test the endpoints using Postman. Feel free to create a free Postman account to test or use any API testing tool you feel comfortable with.
Operations in the SANDBOX environment have no financial impact on actual Diool or beneficiary accounts.
The SANDBOX environment allows you to test with a number of different providers (MTN, Orange), with each operation giving a fixed response regardless of the details of the operation.
For the provider MTN, all API calls respond either as successful (Response Code : 0) or need confirmation (Response Code : 27).
For the provider Orange, all API calls respond with failed (Response Code : 20).
For the PROD environment, you can find the different response codes and their meanings in the Response Codes section of the API documentation. Also see below.
Provider Identifiers
The Diool API uses a code to identify the Provider in a Request. Here are the Providers currently available and their corresponding codes:
MTN : 62401
Orange : 62402
Nexttel : 62404
Express Union : EUMM
General Settings
If you are testing with Postman, you should save your Diool API token in the Authorization tab with a Type of Bearer Token as shown below for all your requests. The authorization header will be automatically generated when you send the requests. Learn more about authorization.
If it's not already set, you should set the Content-Type to application/json in the Headers tab as shown below. You can ignore the other header parameters.
For the endpoints where you need to pass some parameters with your requests, you can add them to the Body tab in JSON format (raw > JSON) as shown below.
Now that we have covered some of the common points among all the endpoints, let's look at how to use each of them.
API Endpoints
There are four main endpoints we are going to test. Follow the links below for steps to use or test each of the endpoints.
Payment endpoint /payment : This endpoint executes a request for payment to a payer identified by a mobile money account number.
Transfer endpoint /transfer : This endpoint executes a request for money to be transferred to a beneficiary identified by a mobile money account.
Balance endpoint /balance : This endpoint executes a request to retrieve the balance associated with a Diool user account.
Transaction Status endpoint /status : This endpoint executes a request to get the status of a particular transaction (payment, transfer, etc.).
Need Help?
Already using or testing the API and need a hand?
Self service: Check out the FAQ.
Have a question..? Chat with us instantly through the Live Chat on our Help Center.
Totally stuck..? Send us a mail at helpdesk@diool.com and we will get back to you as soon as possible.
Updated on: 23/08/2023
Thank you!