Send money API CinetPay

This tutoriel is for merchants willing to send money 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 money 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 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
Transfer account balance
Description Once you have created the token, you can use it in GET to consult your account balance.
GET settings:
token: the token generated in the previous steps
URL https://client.cinetpay.com/v1/transfer/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": 11885,
        "inUsing": 200,
        "available": 11685,
        "countryBalance": {
            "CI": {
                "available": 1195
            },
            "SN": {
                "available": 0
            },
            "CM": {
                "available": 5000
            },
            "ML": {
                "available": 5490
            }
        }
    }
}
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 money 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 money to one or more contacts
Description You can initiate an money 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/transfer/money/send/contact
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": [] 
}
  • Money 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 money transfer.
URL https://client.cinetpay.com/v1/transfer/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 a money transfer

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

Status api cinetpay
Codes API
code Message Description
0 OPERATION_SUCCES API call is successful
-1 OPERATION_ERROR Failure in processing the requests’ data
701 INVALID_CREDENTIALS Authentication settings incorrect
702 COULD_NOT_CREATE_TOKEN Unable to generate token
703 INVALID_USER Merchant account is invalid
704 INVALID_PARAM Settings sent are incorrect
705 EXPIRED_TOKEN Expired token
706 INVALID_TOKEN Invalid token
707 CANT_REFRESH_TOKEN You need to create a new token
708 NOT_ALLOWED Not allowed to consult link
709 EXECUTION_ERROR Failure in executing the request’ data
710 EXECUTION_ERROR Failure in executing the request’ data
715 UNEXPECTED_ERROR Unexpected error
0 SUCCES Successful payment
600 PAYMENT_FAILED Payment failure
602 INSUFFICIENT_BALANCE Insufficient balance on the mobile money wallet to debit
603 SERVICE_UNAVAILABLE Service is unavailable
604 OTP_CODE_ERROR Incorrect OTP code
605 TRANSACTION_CLOSED Transaction is closed
606 INCORRECT_SETTINGS Incorrect settings
607 PENDING Pending transaction
608 MINIMUM_REQUIRED_FIELDS Some requested fields are blank
609 AUTH_NOT_FOUND Incorrect service settings
610 ERROR_PAYMETHOD_NOTFOUND Unavailable payment method
611 ERROR_AMOUNT_TYPE Amount must be a numeric
612 ERROR_CURRENCY_NOTVALID Invalid currency
613 ERROR_SITE_ID_NOTVALID Invalid service
614 ERROR_FORMAT_TRANSACTION_DATE Invalid date format
615 ERROR_LANGUAGE_NOTVALID Invalid language
616 ERROR_PAGE_ACTION_NOTVALID Invalid page_action value
617 ERROR_PAYMENT_CONFIG_NOTVALID Invalid payment_config value
618 ERROR_API_VERSION_NOTVALID Invalid API version
619 ERROR_SIGNATURE_DONT_MATCHED Signature does not match data sent
620 ERROR_DOUBLE_PAYEMNT Payment duplication
621 ERROR_OMPAY_UNAVAILABLE Orange Money is unavailable
622 ERROR_MOMOPAY_UNAVAILABLE MTN Money is unavailable
623 WAITING_CUSTOMER_TO_VALIDATE Payment confirmation pending
624 UNKNOWN_ERROR Unidentified error
626 ERROR_FLOOZPAY_UNAVAILABLE Moov Money is unavailable
627 TRANSACTION_CANCEL Payment cancelled
628 ERROR_AMOUNT_FORMAT Amount must be a whole number
635 ERROR_PHONE_NUMBER_NOT_FOUND Impossible to reach phone number
636 ERROR_PHONE_NUMBER_NOT_SUPPORTED Phone number is not supported
638 SECURE_PAYMENT_WAITING_CONFIRMATION Payment confirmation pending
640 ERROR_OPERATOR_UNAVAILABLE Unavailable payment method
641 ERROR_AMOUNT_TOO_LOW Minimum amount is 100 XOF
642 ERROR_AMOUNT_TOO_HIGH Maximum amount is 3 000 000 XOF
800 ACCESS_RESTRICTED The customer is not allow to do operation
801 INVALID_AMOUNT
802 INVALID_PHONE
803 ERROR_PM_UNDEFINED
804 OPERATOR_UNAVAILABLE Operator is unavailable
805 CLIENT_TRANSACTION_ID_EXIST Client transaction ID is already exist
806 PHONE_MUST_DO_PAYIN Phone number must do a payin before
807 DAILY_MAX_NUMBER_TRANSACTION_REACHED Phone number reach the number of transaction this day
808 DAILY_MAX_AMOUNT_TRANSACTION_REACHED Phone number reach the max amount of transaction this day
809 MONTHLY_MAX_AMOUNT_TRANSACTION_REACHED Merchant reach the max amount of transaction this month