AirTime API CinetPay

This tutoriel is for merchants willing to send Airtime to phone numbers through automatized processes (websites, mobile apps etc...).

Step 1

Prerequisites

You need an account on CinetPay
Otherwise, please Open an account.
Once registered, you need to set up your API password here

Are you ready? Let's integrate!

Step 2

Notification page

The notification link is called by the platform in order to provide you with the status of your Airtime transfer. This URL must be able to collect GET and POST HTTP requests.

The server process a TYPE request including:

  • transaction_id: CinetPay transfer ID
  • client_transaction_id: merchant transfer ID (your ID)
  • lot: the transaction batch
  • amount: the amount of AirTime transferred
  • receiver: the beneficiary's phone number
  • operator: the AirTime operator
  • treatment_status: transfer status


In order to consult the transfer true data, you need to call CinetPay with the provided transaction_id

Step 3

API Manual

Authentication
Description To use the API, you need to create an authentication token. POST settings:
apikey: your apiKey
password: the API password you previously defined
URL https://client.cinetpay.com/v1/auth/login
Method POST
POST Settings lang(en or fr)
GET Settings apikey(your apikey)
password(the API password you previously defined)
Example of response: Success

{ 
    "code": 0,
    "message": 
    "OPERATION_SUCCES",
    "data": {
        "token": 
        "YOUR_TOKEN_HERE"
    } 
}

Example of response: Error

{ 
    "code": "701",
    "message": "INVALID_CREDENTIALS",
    "description": "Identifiant de connexion incorrect",
    "data": [] 
}

  • The authentication token generated by this HTTP request will be used for every other API request.
  • It will remain valid for 5 minutes
Account AirTime balance
Description Once you have created the token, you can use it in GET to consult your AirTime balance.
GET settings:
token: the token generated in the previous steps
URL https://client.cinetpay.com/v1/airtime/check/balance
Method GET
GET Settings token(un token valide)
lang(fr ou en)
POST Settings ...
Example of response: Success

{ 
    "code": 0,
    "message": "OPERATION_SUCCES",
    "data": {
        "amount": 2000,
        "inUsing": 0,
        "available": 2000
    } 
}

Example of response: Error

{ 
    "code": "706",
    "message": "INVALID_TOKEN",
    "description": "Votre token est invalide",
    "data": [] 
}

Add one or more contacts to CinetPay
Description In order to transfer Airtime to a phone number, it needs to be registered in your database. Use this link to add one or more contactss;
POST settings:
data: contacts data to be uploaded
URL https://client.cinetpay.com/v1/transfer/contact
Method POST
GET Settings token(un token valide)
lang(fr ou en)
POST Settings data:[json] contenant
  • prefix: country prefix
  • phone: contact phone number
  • name: contact last name
  • surname: contact first name
  • email: contact email
Example of response: Success

{ 
    "code": 0,
    "message": 
    "OPERATION_SUCCES",
    "data": [
        [
            {
                "prefix": "225",
                "phone": "53798590",
                "name": "Test A",
                "surname": "Test B",
                "email": "[email protected]",
                "code": 0,
                "status": "success",
                "lot": "0044557641201530021279"
            },
            {
                "prefix": "225",
                "phone": "77895086",
                "name": "Test C",
                "surname": "Test D",
                "email": "[email protected]",
                "code": 0,
                "status": "success",
                "lot": "0044557641201530021279"
            }
        ]
    ] 
}

Send AirTime to one or more contacts
Description You can initiate an Airtime transfer request to a phone number registered within your contact database. You will need to confirm the transfer by email.
URL https://client.cinetpay.com/v1/airtime/credit/send
Method POST
GET Settings token(un token valide)
lang(fr ou en)
transaction_id ou client_transaction_id ou lot
POST Settings data:[json] contenant
  • prefix: country prefix
  • phone: contact phone number
  • amount: amount to be sent [in XOF]
  • notify_url: amount to be sent [in XOF]
  • client_transaction_id: your transaction ID (optional)
Example of response: Success

{ 
    "code": 0,
    "message": "OPERATION_SUCCES",
    "data": [
        [
            {
                "prefix": "225",
                "phone": "07895086",
                "amount": 500,
                "client_transaction_id": "MYMERCHANTID1",
                "notify_url": "http://93fd59a2.ngrok.io",
                "code": 0,
                "status": "success",
                "transaction_id": "EA180627.122753.M279245",
                "lot": "0044557641201530102473"
            },
            {
                "prefix": "225",
                "phone": "07895086",
                "amount": 350,
                "client_transaction_id": "MYMERCHANTID2",
                "notify_url": "http://93fd59a2.ngrok.io",
                "code": 0,
                "status": "success",
                "transaction_id": "EA180627.122754.Y707825",
                "lot": "0044557641201530102473"
            }
        ]
    ]
}

Example of response: Error

{ 
    "code": 602,
    "message": "INSUFFICIENT_BALANCE",
    "description": "Fonds Insuffisant :disponible 4 233,00, Total de l'operation à effectuer : 32 000,00",
    "data": [] 
}

  • Airtime transfers must be confirmed by the merchant. If you want to automatise the transfers and bypass validation, please provide CinetPay with IP addresses to whitelist.
Access transfer data
Description This enables you to access the data related to your Airtime transfer.
URL https://client.cinetpay.com/v1/airtime/check/money
Method GET
GET Settings token(un token valide)
lang(fr ou en)
POST Settings ...
Example of response: Success

{ 
    "code": 0,
    "message": "OPERATION_SUCCES",
    "data": [
        {
            "transaction_id": "EA180627.122753.M279245",
            "client_transaction_id": "MYMERCHANTID1",
            "lot": "0044557641201530102473",
            "amount": "500",
            "receiver": "07895086",
            "receiver_e164": "+22507895086",
            "operator": "OM",
            "sending_status": "CONFIRM",
            "transfer_valid": "Y",
            "treatment_status": "VAL",
            "comment": "Transfert effectué avec succès",
            "validated_at": "2018-06-27 12:53:26"
        }
    ] 
}

Example of response: Error

{ 
    "code": 723,
    "message": "NOT_FOUND",
    "description": "Aucun element trouvé",
    "data": [] 
}

  • You need to pay specific attention to the field «treatment_status» value, since it provides you with the transfer status (new, ongoing, cleared, rejected...)
  • The field «sending_confirm» indicates whether you confirmed the transfer by email or not.
    CONFIRM: you confirmed the transfer
    PENDING: you still have to confirm the transfer

Step 4

Status applicable to an Airtime transfer

Please consider the following status and their meaning to understand the state of your transfer.

Status api cinetpay
Codes API
Code API AirTime