Version: V1.0
Last Updated: August 04th, 2022

Getting started

Diool's RESTful API gives you simple and easy access to multiple service providers, directly from your own app (web, mobile or server) using a single account.

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 create your application using the Diool API you'll need to have an existing and eligible Diool account. If you haven't got one already get started at diool.com

Need Help..?

Already using the API and need a hand?

  1. Self service: Check out the FAQ.
  2. Have a question..? Chat with us instantly through the Live Chat crisp
  3. Totally stuck..? Mail us at : helpdesk@diool.com

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 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/

We’ve put together a helpful guide which shows you How to generate Diool API tokens

API Credentials

We provide sample API calls next to each method. All you need to do is insert your specific parameters, and you can test the calls from the command line.

You can also use Postman which is an easy to use API development environment for making HTTP requests. You can download the Postman API platform to make testing the API easier.

NOTE: If you think your keys may have been compromised (for example, you accidentally committed them to Git), you should immediately generate new ones using the Generate API Token button on the Settings > Developer Options page on your dashboard..

This will invalidate all existing keys and give you a new set, and you can then update your app to use the new ones..

Sandbox Tips

Operations in the SANDBOX environment have no financial impact on actual Diool or beneficiary accounts.

The SANDBOX allows you to test with a number of different providers (MTN, Orange, Nexttel), 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 failed (Response Code : 20).

For the provider Nexttel all API calls respond failed (Response Code : 4).

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

Authentication

To use the Diool API, you will need :

  • an existing and eligible Diool account. If you haven't got one already get started at diool.com

  • a valid Diool API token.

All calls to the Diool API must be authenticated through a valid API token.

The key of the API token must be added to the Request header in a line with the following syntax :

  • Syntax : Authorization: Bearer [API-KEY]
  • Example on Sandbox :
    Authorization: Bearer api_sandbox.kVZc9•••••
  • Example on Prod :
    Authorization: Bearer api_live.kVZc9•••••

If an invalid API token key is passed or if the API token key is missing, a 401 Unauthorized HTTP status will be returned in both the Response headers and the Response Status field.

The API key must be included in each API Request to the server. The header in these Requests will look like the following example:

Content-Type: application/json
Authorization: Bearer [API-KEY]

API Endpoints

Payment Endpoint

# Here is a curl example of a payment request
  curl -d '{ "accountIdentifier": "237xxxxxxxxx", "amount": "100",
  "providerIdentifier": "62401", "referenceOrder": "12236543874" }'
  -H "Authorization: Bearer [API-KEY]"
  -H "Content-Type: application/json"
  -X POST "ENVIRONMENT_URL/payment"

To send a payment request, a POST call, as shown in the example, is made to the following url :
[ENVIRONMENT_URL]/payment

Example:

  • Sandbox : https://sandboxcore.diool.com/core/dioolapi/v1/payment
  • Prod : https://core.diool.com/core/dioolapi/v1/payment



Result example :

{
    "code": 0,
    "message": "Payment processed successfully",
    "developerMessage": "Payment processed successfully",
    "moreInfo": "www.diool.com",
    "lang": "en",
    "result": {
        "paymentRef": 691,
        "responseCode": "OK",
        "responseMessage": "Operation Successfull",
        "extPaymentRef": null,
        "extPaymentTimestamp": "2021-05-10T16:46:33.191Z",
        "senderAmount": null,
        "senderCurrency": null,
        "recipientAmount": null,
        "recipientCurrency": null,
        "timeStamp": "1636562793205",
        "uniqueReference": "HAUNMYVD",
        "userFees": 47.50,
        "additionalInfo": null
    }
}

This endpoint executes a request for payment to a payer identified by a mobile money account number. The completed payment will be deposited in the requestor's Diool account.

The Request includes the payor's account identifier (a mobile money account number), the amount of the request, the code for the mobile money provider, and reference information identifying the payment. Currently available payment methods are ORANGE Money, MTN MoMo and EUMM (Express Union).


NOTE: All incoming payments are deposited in the Revenue account.
 

REQUEST PARAMETERS

Parameter Types Description
accountIdentifier required String is the mobile money number to charge prefixed by country code (e.g, for Cameroon : 237)
amount required Integer The amount requested from the payor. Can be used like a string (e.g, 100 or "100").
providerIdentifier required String is the Provider Identifier code
referenceOrder required String is reference information for the payment


Transfer Endpoint

# Here is a curl example of a transfer request
  curl -d   '{ "accountIdentifier": "237xxxxxxxxx", "amount": "100",
  "providerIdentifier" :"62401"}'
  -H "Authorization: Bearer [API-KEY]"
  -H "Content-Type: application/json"
  -X POST "ENVIRONMENT_URL/transfer"

To send a money transfer request, a POST call, as shown in the example, is made to the following url :
[ENVIRONMENT_URL]/transfer

Example:

  • Sandbox : https://sandboxcore.diool.com/core/dioolapi/v1/transfer
  • Prod : https://core.diool.com/core/dioolapi/v1/transfer



Result example :

{
    "code": 0,
    "message": "Transfer processed successfully",
    "developerMessage": "Transfer processed successfully",
    "moreInfo": "www.diool.com",
    "lang": "en",
    "result": {
        "transferRef": 1084,
        "responseCode": "OK",
        "responseMessage": "Operation Successfull",
        "userFees": 0.00,
        "userRevenue": 1.80,
        "userLoyaltyPoints": null,
        "currencyExchangeRate": 1,
        "extSenderTransactionRef": null,
        "extSenderTransactionTimestamp": null,
        "extRecipientTransactionRef": null,
        "extRecipientTransactionTimestamp": "2021-05-10T17:01:58.464Z",
        "senderAmount": null,
        "senderCurrency": null,
        "recipientAmount": 1500.00,
        "recipientCurrency": "XAF",
        "timeStamp": "1636563718491",
        "uniqueReference": "HAUNMYVD"
    }
}

This endpoint executes a request for money to be transferred to a beneficiary identified by a mobile money account number. The completed transfer will be taken from the sender's Diool account and will be deposited in the beneficiary's mobile money account.

The Request includes the beneficiary's account identifier (a mobile money account number), the amount to be transferred, and the code for the mobile money provider. Currently available money transfer methods are ORANGE Money, MTN MoMo and EUMM (Express Union).


NOTE: You can only transfer funds from the Balance account. Therefore, first Redeem funds from your Revenue account to move them to the Balance account before transferring.
 

REQUEST PARAMETERS

Parameter Types Description
accountIdentifier required String is the mobile money number of the beneficiary prefixed by country code (e.g, for Cameroon : 237)
amount required Integer The amount to be transferred from the sender to the beneficiary. Can be used like a string (e.g, 100 or "100").
providerIdentifier required String is the Provider Identifier code.


Redeem Endpoint

# Here is a curl example of a redeem request
  curl -d   '{ "amount": "100" }'
  -H "Authorization: Bearer [API-KEY]"
  -H "Content-Type: application/json"
  -X POST "ENVIRONMENT_URL/redeem_revenue"

To redeem money from the revenue balance to the deposit balance, a POST call, as shown in the example, is made to the following url :
[ENVIRONMENT_URL]/redeem_revenue

Example:

  • Sandbox : https://sandboxcore.diool.com/core/dioolapi /v1/redeem_revenue
  • Prod : https://core.diool.com/core/dioolapi/v1/redeem_revenue



Result example :

{
    "code": 0,
    "message": "Redeem processed successfully",
    "developerMessage": null,
    "moreInfo": "www.diool.com",
    "lang": "en",
    "result": {
        "responseCode": "OK",
        "responseMessage": null,
        "userOldBalance": null,
        "userOldRevenue": null,
        "timeStamp": "1648483446317"
    }
}

This endpoint executes a request to redeem an amount from the user's revenue account to the user's deposit account.

REQUEST PARAMETERS

Parameter Types Description
amount required Integer The amount to be redeemed from the revenue account to the deposit account. Can be used like a string (e.g, 100 or "100").




Balance Endpoint

# Here is a curl example of a balance request
  curl 

  -H "Authorization: Bearer [API-KEY]"
  -H "Content-Type: application/json"
  -X GET "ENVIRONMENT_URL/balance"

To obtain the balances in a Diool account, a GET call as shown in the example, is sent to the following url :
[ENVIRONMENT_URL]/balance

Example:

  • Sandbox : https://sandboxcore.diool.com/core/dioolapi/v1/balance
  • Prod : https://core.diool.com/core/dioolapi/v1/balance



Result example :

{
    "code": 0,
    "message": "Balance retrieved successfully",
    "developerMessage": null,
    "moreInfo": "www.diool.com",
    "lang": "en",
    "result": {
        "responseCode": "OK",
        "responseMessage": "Action succeeded",
        "depositAccountBalance": 9997090.85,
        "revenueAccountBalance": 6285.01,
        "realBalance": null,
        "timeStamp": "1636567022578"
    }
}

This endpoint executes a request to retrieve Diool account balances associated with a user account.

REQUEST PARAMETERS

No parameters



Transaction Status Endpoint

# Here is a curl example
  curl -d   '{ "uniqueReference": "HAUNMYVD" }'
  -H "Authorization: Bearer [API-KEY]"
  -H "Content-Type: application/json"
  -X POST "ENVIRONMENT_URL/status"

To obtain the status of a transaction, a POST call as shown in the example, is sent to the following url :
[ENVIRONMENT_URL]/status

Example:

  • Sandbox : https://sandboxcore.diool.com/core/dioolapi/v1/status
  • Prod : https://core.diool.com/core/dioolapi/v1/status



Result example :

{
    "code": 0,
    "message": "Status retrieved successfully",
    "developerMessage": null,
    "moreInfo": "www.diool.com",
    "lang": "en",
    "result": {
        "responseCode": "OK",
        "responseMessage": "Action succeeded",
        "statusCode": 0,
        "statusDescription": "Transaction Sucessfull",
        "timeStamp": "1636567022578"
    }
}

This endpoint executes a request to get the status of a particular transaction (payment, transfer, airtime).

REQUEST PARAMETERS

Parameter Types Description
uniqueReference required String is the unique identifier of the transaction returned by Diool in the transaction response. You can find it in your Transaction History or within a Transaction Receipt the article about


Response Codes

The DIOOL API uses the following response 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 an 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.