NAV Navbar
php python javascript
  • Introduction
  • Latest Updates
  • Environments
  • Sandbox Tips
  • Authentication
  • Providers Identifiers
  • API Calls
  • Response Codes
  • 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 :

    We are constantly improving Diool API. A question, a suggestion, mail us : helpdesk@diool.com

    Latest Updates

    Environments

    Diool API features 2 environments to embetter the integration process :

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

    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 :

    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.