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

Have a question? Check out the FAQ. Already using the API and need a hand? 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 : http://sandboxcore.diool.com/dioolapi/v3/
  • PROD :https://core.diool.com/dioolapi/v3/

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 the details of the operation.

For the provider MTN, all API calls respond either as successful (Response Code : 0) or need confirmation (Responde 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
  • YUP : TAGPAY

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 : Authorization: Bearer [API-KEY]. 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":237656560711,"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



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. Current available payment methods are ORANGE Money, MTN MoMo, YUP (Société Générale) and EUMM (Express Union).

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
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":237656560711,"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



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. Current available money transfer methods are ORANGE Money, MTN MoMo, YUP (Société Générale) and EUMM (Express Union).

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
providerIdentifier required String is the Provider Identifier code


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



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



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


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.