API de Transfert CinetPay

Ce tutoriel s’adresse à tous les marchands CinetPay qui veulent effectuer des transferts d’argent sur des comptes mobiles money via des processus automatiques (Site internet, App mobiles etc...).

Etape 1

Pré-requis

Vous devez avoir un compte sur CinetPay
Sinon, Veuillez Créer votre compte.
Une fois cela fait, vous devez configurer le mot de passe d'API ici

Vous êtes prêts ? c'est parti !

Etape 2

Page de notification

Le lien de notification est celui qui est appelé par la plateforme pour vous notifier de l’état de votre transfert d'argent. Cette URL doit être disponible pour accueillir des requêtes HTTP de type GET et POST.

Le serveur exécute une requête de type POST contenant:

  • transaction_id: l’identifiant du transfertCinetPay
  • client_transaction_id: l’identifiant du transfertMarchand (Votre Identifiant)
  • lot: le lot de la transaction
  • amount: Le montant du transfert d'argent
  • receiver: le numéro de téléphone du recepteur
  • operator: L’opérateur de transfert
  • treatment_status: Le statutdu transfert


Il faut toujours demander les vraies valeurs du transfert en interrogeant CinetPay avec la transaction_id

Etape 3

Utilisation de l'API

Authentification
Description Pour utiliser l'API, il vous faut générer un token.Données en POST :
apikey : Votre apiKey
password : Le mot de passe API que vous aviez configuré
URL https://client.cinetpay.com/v1/auth/login
Méthode POST
Paramètres POST apikey(votre apikey)
password(le mot de passe API que vous avez defini)
Paramètres GET lang(en ou fr)
Exemple Réponse: Succès 

{
    "code": 0,
    "message":
    "OPERATION_SUCCES",
    "data": {
        "token":
        "YOUR_TOKEN_HERE"
    }
}
Exemple Réponse: Erreur 

{
    "code": "701",
    "message": "INVALID_CREDENTIALS",
    "description": "Identifiant de connexion incorrect",
    "data": []
}
  • Le token obtenu par cette requête HTTP sera utilisé pour tout autre requête de l’API
  • Sa durée de vie est de 5 min
Information solde du compte transfert
Description Une fois que vous avez le token, vous pouvez l'insérer en GET pour avoir votre solde transfert
Données en GET :
token : Le token généré lors de l'authentification
URL https://client.cinetpay.com/v1/transfer/check/balance
Méthode GET
Paramètres GET token(un token valide)
lang(fr ou en)
Paramètres POST ...
Exemple Réponse: Succès 

{
    "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
            }
        }
    }
}
Exemple Réponse: Erreur 

{
    "code": "706",
    "message": "INVALID_TOKEN",
    "description": "Votre token est invalide",
    "data": []
}
Ajouter un ou plusieurs contacts sur CinetPay
Description Pour effectuer un transfert d'argent sur un numéro de téléphone, il doit figurer au préalable dans votre liste de contact. Utilisez ce lien pour ajouter un ou plusieurs contacts;
Données en POST:
data: la liste des contacts à ajouter
URL https://client.cinetpay.com/v1/transfer/contact
Méthode POST
Paramètres GET token(un token valide)
lang(fr ou en)
Paramètres POST data:[json] contenant
  • prefix: le préfix du pays
  • phone: Le numéro de téléphone du contact
  • name: Le nom du contact
  • surname: Le prénom du contact
  • email: L’email du contact
Exemple Réponse: Succès 

{
    "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"
            }
        ]
    ]
}
Envoyer de l'argent à un ou plusieurs de vos contacts CinetPay
Description Vous pouvez initier un ordre de transfert d’argent vers un numéro de téléphone de vos contacts. Vous devez confirmer le transfert par mail.
URL https://client.cinetpay.com/v1/transfer/money/send/contact
Méthode POST
Paramètres GET token(un token valide)
lang(fr ou en)
transaction_id ou client_transaction_id ou lot
Paramètres POST data:[json] contenant
  • prefix: le préfix du pays
  • phone: Le numéro de téléphone du contact
  • amount: Le montant à envoyer [en FCFA (XOF)]
  • notify_url: Le montant à envoyer [en FCFA (XOF)]
  • client_transaction_id: votre ID de transaction(facultatif)
Exemple Réponse: Succès 

{
    "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"
            }
        ]
    ]
}
Exemple Réponse: Erreur 

{
    "code": 602,
    "message": "INSUFFICIENT_BALANCE",
    "description": "Fonds Insuffisant :disponible 4 233,00, Total de l'operation à effectuer : 32 000,00",
    "data": []
}
  • Tous les transferts d'argent doivent être confirmer par le marchand. Si vous voulez que cela soit prise en compte sans validation. Veuillez écrire à CinetPay et nous fournir une liste d’adresses IP qui pourront effectuer des ordres de transfert.
Avoir les informations d’un transfert d'argent
Description Ceci vous permet d’avoir les informations sur un transfert d'argent.
URL https://client.cinetpay.com/v1/transfer/check/money
Méthode GET
Paramètres GET token(un token valide)
lang(fr ou en)
Paramètres POST ...
Exemple Réponse: Succès 

{
    "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"
        }
    ]
}
Exemple Réponse: Erreur 

{
    "code": 723,
    "message": "NOT_FOUND",
    "description": "Aucun element trouvé",
    "data": []
}
  • Vous devez observer particulièrement la valeur de «treatment_status», car c’est cette variable qui donne le statut(nouveau, en cours, valider, rejeté...)de traitement d’un transfert d'argent
  • La variable «sending_confirm» sert à préciser si vous avez confirmé le transfert par mail :
    CONFIRM: vous avez confirmé le transfert
    PENDING: vous n’avez pas encore confirmé le transfert

Etape 4

Différents statuts d’un transfert d'argent.

Il est important de prendre en compte les différents statuts que peut prendre un transfert d'argent.

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