API AirTime CinetPay

Ce tutoriel s’adresse à tous les marchands CinetPay qui veulent effectuer des transferts unités sur des numéros de téléphone 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’unité. 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’unité
  • receiver: le numéro de téléphone du recepteur
  • operator: L’opérateur AirTime
  • 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 lang(en ou fr)
Paramètres GET apikey(votre apikey)
password(le mot de passe API que vous avez defini)
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 AirTime
Description Une fois que vous avez le token, vous pouvez l'insérer en GET pour avoir votre solde AirTime
Données en GET :
token : Le token généré lors de l'authentification
URL https://client.cinetpay.com/v1/airtime/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": 2000,
        "inUsing": 0,
        "available": 2000
    } 
}

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’unité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 airTime à un ou plusieurs de vos contacts CinetPay
Description Vous pouvez initier un ordre de transfert d’unitévers un numéro de téléphone de vos contacts. Vous devez confirmer le transfert par mail.
URL https://client.cinetpay.com/v1/airtime/credit/send
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’unités 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’unité
Description Ceci vous permet d’avoir les informations sur un transfert d’unité.
URL https://client.cinetpay.com/v1/airtime/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’unité
  • 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’unité.

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

Status api cinetpay
Codes API
Code API AirTime