Using the API

How to generate a token

To use the transfer API, you must 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

Account balance information transfer

Once you have the token, you can insert it in GET to get your transfer balance using this url:

https://client.cinetpay.com/v1/transfer/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": 663,
    "inUsing": 0,
    "available": 663
    }
}

Example of an error response


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

Add one or more contacts on CinetPay

In order to transfer money to 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/transfer/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": "[email protected]"
},{
    "prefix": "225",
    "phone": "01020304",
    "name": "Test C",
    "surname": "Test D",
    "email": "[email protected]"
}]

Example of a successful response

{
    "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 money to 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/transfer/money/send/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
amount: The amount to send (must be a multiple of 5)Attention
notify_url: The notification url to call when the transfer will be done
client_transaction_id: Your transaction ID (optional)
}

Exemple of query


[{
    "prefix": "225",
    "phone": "0102324373",
    "amount": 500,
    "client_transaction_id": "TEST-ID1",
    "notify_url": "http://yourdomain.com/transfer/notify"
}, {
    "prefix": "225",
    "phone": "0102324373",
    "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": "0102324373",
                    "amount": 500,
                    "client_transaction_id": "TEST-ID1",
                    "notify_url": "https://webhook.site/a38f92c3-7304-4540-82af-db48f06d2000",
                    "code": 0,
                    "status": "success",
                    "treatment_status": "NEW",
                    "transaction_id": "EA211005.065802.Z794810",
                    "lot": "0069229938091633417082"
                },

                {
                    "prefix": "225",
                    "phone": "0102324373",
                    "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 money transfers must be confirmed by the merchant. If you want it to be processed without validation. Please write to CinetPay and provide us with a list of IP addresses that will be able to make transfer orders.

Have the information of a money transfer

You can have the information about a money transfer.

https://client.cinetpay.com/v1/transfer/check/money
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_status " 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

Download an example

For a quick integration, please download the json collection that contains all the queries.


Download

Good to know

1) amount : The amount must be a multiple of 5 or the transaction will fail.

Error Status

Code Cause Solution
Code: 709(This IP is not allow to execute this action) The ip address is not allowed to perform this action send an email to [email protected] to have your address whitelisted, the email must contain: the email attached to the account, the ip address, the reason
Code: -1(Undefined index: country) The number entered does not match the operator prefix or the number of digits exceeds the standard You will find the list of operators and the number of digits in the code table
Code: -1(ERROR_PM_AMOUNT) The amount set is below the transfer threshold for country Refer to slice chart amounts per country
Code : -1 ( The prefix "XXX" belongs to a country not taken into account) 1) the prefix entered belongs to a country not taken into account in the money transfer
2) There is a '+' sign before the prefix		 1) You will find the list of prefixes supported by CinetPay in the annexes table
2) vous devez enlever le signe + avant le préfixe
Code : -1 Error in the request you will find the correct syntax in the example above
code:602
"INSUFFICIENT_BALANCE"		 Your account balance for this country is insufficient to complete this transfer Follow these steps to recharge your transfer account