Using the API

How to generate a token

To use the rechargement API, you need to generate a token by sending the following information in X-WWW-URLENCODED format. Using this url:

https://client.cinetpay.com/v1/auth/login
Code Valeur
METHODES GET & POST
Content-type application/x-www-form-urlencoded
Parameter GET lang (en ou fr)
Parameter POST apikey : (votre apikey)
password :(the API password you have defined)

Example of a successful response


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

Example of an error response


{
    "code": "701",
    "message": "INVALID_CREDENTIALS",
    "description": "Identifiant de connexion incorrect",
    "data": []
}
  • The token obtained by this HTTP request will be used for any other request of the API
  • Its lifetime is 5min

AirTime account balance information

Once you have the token, you can insert it in GET to have your Airtime balance

Using this url:

https://client.cinetpay.com/v1/airtime/check/balance
Code Valeur
METHODE GET
Parameter GET token (a valid token)
lang (en ou fr)

Example of a successful response


{

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

Example of an error response


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

Add one or more contacts on CinetPay

To top up a phone number, it must first appear in your contact list. Use this link to add one or more contacts:

https://client.cinetpay.com/v1/airtime/contact
Code Valeur
METHODES GET & POST
Content-type application/x-www-form-urlencoded
Parameter GET token (a valid token)
lang (en or fr)
parameter POST data : (json) containing
{
prefix: the country prefix
phone: The phone number of the contact
name: The name of the contact
surname: The contact's first name
email: The email of the contact
}

Example of query


[{
    "prefix": "225",
    "phone": "01020304",
    "name": "Test A",
    "surname": "Test B",
    "email": "testa@exemple.com"
},{
    "prefix": "225",
    "phone": "01020304",
    "name": "Test C",
    "surname": "Test D",
    "email": "testb@exemple.com"
}]

Example of a successful response

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

Top up one or more of your CinetPay contacts

you can initiate a money transfer order to a phone number of your contacts. You must confirm the transfer by email.

Use this link:

https://client.cinetpay.com/v1/airtime/money/send/contact
Code Valeur
METHODES GET & POST
Content-type application/x-www-form-urlencoded
Paramètre GET token (un token valide)
lang (en ou fr)
parameter POST data : (json) containing
{
prefix: the country prefix
phone: The phone number of the contact
amount: The amount to send [in FCFA (XOF)] (Warning)
notify_url: The notification url to call when the transfer will be done
client_transaction_id: Your transaction ID (optional)
}

Example of query


[{
    "prefix": "225",
    "phone": "07895086",
    "amount": 500,
    "client_transaction_id": "MYMERCHANTID1",
    "notify_url": "http://yourdomain.com/transfer/notify"
}, {
    "prefix": "225",
    "phone": "03798593",
    "amount": 2000,
    "client_transaction_id": "MYMERCHANTID2",
    "notify_url": "http://yourdomain.com/transfer/notify"
}]

Example of a successful response


{
    "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",
    "treatment_status": "NEW",
    "transaction_id": "EA180627.122753.M279245", "lot": "0044557641201530102473"
    }, {
            "lot": "0044557641201530102473"
        }
    ]
    "prefix": "225",
    "phone": "07895086",
    "amount": 350,
    "client_transaction_id": "MYMERCHANTID2", "notify_url": "http://93fd59a2.ngrok.io", "code": 0,
    "status": "success",
    "treatment_status": "NEW"
    "transaction_id": "EA180627.122754.Y707825",
    ] 
}

Example of an error response

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

{info.fa-info}All reloads must be confirmed by the merchant. If you want this to be taken into account without validation. Please write to CinetPay and provide us with a list of IP addresses that can perform transfer orders.

Have the information of a Top up

You can have the information about a Top up. Using this url: 

https://client.cinetpay.com/v1/airtime/check/send
Code Valeur
METHODE GET
Parameter GET token (a valid token)
lang (en or fr)
transaction_id (CinetPay transaction ID) OR client_transaction_id (Your transaction ID) OR lot (The CinetPay batch number)

Example of a successful response

{
    "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 an error response

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

  • You must particularly observe the value of " treatment_status ", because it is this variable that gives the status (new, in progress, validate, rejected...) of a money transfer processing

  • The variable " sending_confirm " is used to specify if you have confirmed the transfer by email

    • CONFIRM : you have confirmed the transfer
    • PENDING : you have not yet confirmed the transfer

Good to know

1) amount :

  • If the transaction involves the Orange operator, the amount must be a multiple of fifty(50) otherwise the transaction will fail.
  • If the transaction involves the Moov or MTN operators, the amount must be a multiple of five(5)or the transaction will fail