I-1 Introduction

Bienvenue dans l’API d’envoi d’argent. Cette API permet aux dĂ©veloppeurs d’intĂ©grer facilement des fonctionnalitĂ©s de transfert de fonds dans leurs applications web ou mobiles. Elle prend en charge l’envoi d’argent entre utilisateurs, les paiements vers des comptes bancaires ou des portefeuilles mobiles, et fournit un suivi en temps rĂ©el des transactions.

L’API est sĂ©curisĂ©e, rapide et conçue pour rĂ©pondre aux besoins des plateformes fintech, des services de paiement et des applications de commerce en ligne. Elle s’intĂšgre facilement Ă  votre infrastructure existante grĂące Ă  une architecture RESTful, une authentification basĂ©e sur les tokens, et une documentation claire.

I-2 Restriction d’adresses IP dans l’API

Cette fonctionnalitĂ© permet de limiter l'accĂšs Ă  l’API uniquement Ă  certaines adresses IP autorisĂ©es, renforçant ainsi la sĂ©curitĂ©

I-3 Reponse de l erreur 
{
  "data": {
    "ip": "127.0.0.1"
  },
  "message": "Access denied. Unauthorized IP address."
}

II-1 Webhooks

L’API prend en charge l’envoi automatique de notifications par webhook Ă  chaque mise Ă  jour critique du statut d’une transaction. Cela permet aux systĂšmes partenaires d’ĂȘtre notifiĂ©s en temps rĂ©el, sans avoir Ă  interroger en boucle l’API (polling).

II-2 Quand un webhook est-il déclenché ?

Un webhook est dĂ©clenchĂ© Ă  chaque changement de statut d’une transaction, notamment :

pending → processing
processing → success
processing → failed
success → refunded (le cas Ă©chĂ©ant)

II-3 Format de la requĂȘte webhook

En-tĂȘtes :

Content-Type: application/json
X-Signature: {HMAC-SHA256 du payload signé avec la clé secrÚte}

Payload JSON envoyé :

{
  "transaction_id": "TXN-123456",
  "status": "success",
  "amount": 250.00,
  "currency": "USD",
  "timestamp": "2025-01-09T01:42:54+00:00"
}

II-4 Sécurité

Chaque webhook est signĂ© avec un HMAC SHA256 dans le header X-Signature, gĂ©nĂ©rĂ© Ă  l’aide d’une clĂ© secrĂšte partagĂ©e. Le destinataire doit vĂ©rifier cette signature pour garantir l’intĂ©gritĂ© de la notification.

$expectedSignature = hash_hmac('sha256', $payload, $secret);

III-1 RĂ©cupĂ©ration de la clĂ© API (private_key,secret_key) pour l’environnement Sandbox

Pour interagir avec notre API en mode test (sandbox), chaque dĂ©veloppeur doit disposer d’une clĂ© API dĂ©diĂ©e, gĂ©nĂ©rĂ©e via son compte dĂ©veloppeur. Cette clĂ© permet d’effectuer des appels simulĂ©s sans dĂ©clencher de transactions rĂ©elles.

🧭 Étapes pour obtenir la clĂ© API Sandbox

Créer un compte développeur
Recuperer ses identifiants

Dans le menu "Accounts , copier vos identifiants"

Sandbox

La clé vous sera affichée une seule fois : copiez-la et stockez-la en lieu sûr

Environnement sandbox

III-1 Authentification

L'API utilise un token JWT dans l'en-tĂȘte Authorization.

Authorization: Bearer <votre_access_token>

POST /api/login

III-2🎯 Authentifie un utilisateur avec ses identifiants

Ce endpoint permet Ă  un utilisateur de se connecter en envoyant son email et son mot de passe. En cas de succĂšs, un token d’accĂšs est renvoyĂ© pour les appels API futurs..

Corps JSON attendu :

{
"private_key":"wtc_private_sandbox25042557g2tpjdwdkt8swj596r7r987jro",
"secret_key":"wtc_secret_sandbox250425571rp0e31y0eqklo2q0uwkfw5plu"
}
RequĂȘte :
POST /api/login
RĂ©ponse :
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ3dGNfYXBpIiwic3ViIjoxLCJpYXQiOjE3NDYxODg2NTIsImV4cCI6MTc0NjE5MjI1Mn0.SIrzfmIwcuI4JDQkjzUoWBJ0-WMOaUQKwVVA5ydaVLLk8ZWF42F90ROSSpDf0w5uT7qQLuk6phpcu7XQSFRDz9_3Jpr-qM9ErW9tiuO7l3evpzjxSmlLt8E4s3HRAS9GrGmVIqkEGDQEyLtAFZqX-3AZQJCkl05lYBkD-YjbF0hX1HC84Enx6iF5E2Bzzjq9Em4xcs1638FJt5R5p9IKnsZr2Ww7MY4iTqdDjn99lfOZpo86uvgOnZvSrPpAoPSnDceJ3ZQkwRU4ohqSALkUW4PZsPS9k-0BqJE1BJiqGXj3XVnNnemHGCmUso72jBEX03AaD2CoZS13g-qXQGPk5w",
  "token_type": "bearer",
  "expires_in": 3600
}

GET /api/countries

permet de rĂ©cupĂ©rer la liste des pays disponibles pour l’envoi ou la rĂ©ception d’argent via la plateforme.

Il est utile pour alimenter des menus déroulants ou valider les destinations autorisées dans votre application

RequĂȘte :
GET /api/countries
RĂ©ponse :
{
  "message": "senders get successful",
  "status": "success",
  "data": [
    {
      "name": "Cameroun",
      "code_iso": "CM",
      "currency": "XAF"
    },
    {
      "name": "Congo",
      "code_iso": "CG",
      "currency": "XAF"
    },
    {
      "name": "Congo RDC",
      "code_iso": "CD",
      "currency": "XAF"
    },
    {
      "name": "Senegal",
      "code_iso": "SN",
      "currency": "XOF"
    },
     ...           }

GET /api/cities

permet d’obtenir la liste des villes disponibles pour un pays donnĂ©, identifiĂ© par son code ISO Ă  deux lettres.

Il est gĂ©nĂ©ralement utilisĂ© pour filtrer les zones de destination lors de l’envoi d’argent.

ParamĂštres de requĂȘte :

RequĂȘte :

Champs :

  • name : Nom de la ville (string)
  • country : Pays auquel appartient la ville (string)
GET /api/cities?codeiso=CM
RĂ©ponse :
                {
  "message": "cities get successful",
  "status": "success",
  "data": [
    {
      "name": "Douala",
      "country": "Cameroun"
    },
    {
      "name": "Yaoundé",
      "country": "Cameroun"
    },
    {
      "name": "Bamenda",
      "country": "Cameroun"
    },
    {
      "name": "Bafoussam",
      "country": "Cameroun"
    },
     ... }

Code de réponse HTTP :

  • 200 OK : Liste des villes retournĂ©e avec succĂšs
  • 400 Bad Request : ParamĂštre codeiso manquant ou invalide
  • 404 Not Found : Aucun pays ou aucune ville trouvĂ©e pour ce code ISO

GET /api/origin_fonds

permet d’obtenir la liste des origines des fonds disponibles pour un type de transfert donnĂ©, identifiĂ© par le type de sender et de beneficiare Ă  deux lettres.

ParamĂštres de requĂȘte :

RequĂȘte :

Champs :

  • type_transaction : type de la transaction (string)
GET /api/origin_fonds?type_transaction=B2P
RĂ©ponse :
{
  "message": "Request successful",
  "status": "success",
  "data": ["Brother",
    "Mother",
    "Sister",
    "Self",
    "Father",
    "Spouse",
                ]
}

Code de réponse HTTP :

  • 200 OK : Liste des villes retournĂ©e avec succĂšs
  • 400 Bad Request : ParamĂštre type_transaction manquant ou invalide

GET /api/motifs

permet d’obtenir la liste des motifs disponibles pour un type de transfert donnĂ©, identifiĂ© par le type de sender et de beneficiare Ă  deux lettres.

ParamĂštres de requĂȘte :

RequĂȘte :

Champs :

  • type_transaction : type de la transaction (string)
GET /api/motifs?type_transaction=B2P
RĂ©ponse :
{
  "message": "Request successful",
  "status": "success",
  "data": ["Brother",
    "Mother",
    "Sister",
    "Self",
    "Father",
    "Spouse",
                ]
}

Code de réponse HTTP :

  • 200 OK : Liste des villes retournĂ©e avec succĂšs
  • 400 Bad Request : ParamĂštre type_transaction manquant ou invalide

GET /api/relations

permet d’obtenir la liste des relations entre expediteurs et beneficiares disponibles pour un type de transfert donnĂ©, identifiĂ© par le type de sender et de beneficiare Ă  deux lettres.

ParamĂštres de requĂȘte :

RequĂȘte :

Champs :

  • type_transaction : type de la transaction (string)
GET /api/relations?type_transaction=B2P
RĂ©ponse :
{
  "message": "Request successful",
  "status": "success",
  "data": ["Brother",
    "Mother",
    "Sister",
    "Self",
    "Father",
    "Spouse",
                ]
}

Code de réponse HTTP :

  • 200 OK : Liste des villes retournĂ©e avec succĂšs
  • 400 Bad Request : ParamĂštre type_transaction manquant ou invalide

GET /api/banks

Ce endpoint permet d’obtenir la liste des banques disponibles dans un pays donnĂ©, identifiĂ© par son code ISO.

Il est essentiel pour que l’utilisateur sĂ©lectionne la banque du bĂ©nĂ©ficiaire lors d’un transfert d’argent vers un compte bancaire.

RequĂȘte :
GET /api/banks?codeiso=CM
RĂ©ponse :
                {
  "message": "cities get successful",
  "status": "success",
  "data": [
    {
     "name": "BICEC",
      "country": "Cameroun"
    },
    {
      "name": "Société Générale Cameroun",
      "country": "Cameroun"
    },
    {
     "name": "UBA Cameroun",
      "country": "Cameroun"
    },
     ... }

Codes de réponse HTTP :

  • 200 OK : Liste des banques retournĂ©e avec succĂšs
  • 400 Bad Request : ParamĂštre codeiso manquant ou invalide
  • 404 Not Found : Aucune banque trouvĂ©e pour ce pays

GET /api/networks

Ce endpoint permet d’obtenir la liste des operateurs MOMO disponibles dans un pays donnĂ©, identifiĂ© par son code ISO.

Il est essentiel pour que l’utilisateur sĂ©lectionne l'operateur du bĂ©nĂ©ficiaire lors d’un transfert d’argent vers un compte MOMO.

RequĂȘte :
GET /api/networks?codeiso=CM
RĂ©ponse :
 {
  "message": "networks get successful",
  "status": "success",
  "data": [
   {
      "name": "ORANGE MONEY",
      "country": "Cameroun"
    },
    {
      "name": "MTN MOBILE MONEY",
      "country": "Cameroun"
    }
  ]
}

Codes de réponse HTTP :

  • 200 OK : Liste des operateurs retournĂ© avec succĂšs
  • 400 Bad Request : ParamĂštre codeiso manquant ou invalide
  • 404 Not Found : Aucune operateur trouvĂ©e pour ce pays

GET /api/senders

Ce endpoint permet de récupérer la liste des expéditeurs enregistrés sur la plateforme.

Il est utilisĂ© pour afficher les informations des clients initiant des transferts d’argent, ou pour effectuer des opĂ©rations liĂ©es Ă  la gestion de leurs transactions..

RequĂȘte :
GET /api/senders
RĂ©ponse :
{
  "message": "senders get successful",
  "status": "success",
  "data": [
    {
      "first_name": "kouamo",
      "last_name": "Dieudonne",
      "email": "info@agensic.com",
      "phone": "237675066919",
      "code": "25042521022068963666512",
      "occupation": "mecanicien",
      "civility": "Maried",
      "gender": "M",
      "document_type": "PP",
      "document_expired": "2025-05-10",
      "document_number": "5879454555"
    },
    {
      "first_name": "reine edith",
      "last_name": "jeanne d arc",
      "email": "contact@agensic.com",
      "phone": "687958",
      "code": "25042816714400768238381",
      "occupation": "mecanicien",
      "civility": "Single",
      "gender": "F",
      "document_type": "CNI",
      "document_expired": "2025-05-11",
      "document_number": "5879454555"
    },
    {
      "first_name": "John most",
      "last_name": "Yves",
      "email": "johm@gmail.com",
      "phone": "675066919",
      "code": "25050209346105716102273",
      "occupation": "Mecanicien",
      "civility": "Single",
      "gender": "M",
      "document_type": "PP",
      "document_expired": "2025-02-18",
      "document_number": "8957452144"
    },]}

Codes HTTP possibles :

  • 200 OK : Liste des expĂ©diteurs retournĂ©e avec succĂšs
  • 204 No Content : Aucun expĂ©diteur ne correspond aux critĂšres
  • 400 Bad Request : ParamĂštre invalide dans la requĂȘte
  • 401 Unauthorized : Jeton d’accĂšs manquant ou invalide

POST /api/senders

Ce endpoint permet d’enregistrer un nouvel expĂ©diteur sur la plateforme.

Les informations fournies sont utilisées pour authentifier l'utilisateur, l'associer à des transactions, et garantir la conformité réglementaire (KYC).

Corps JSON attendu :
{
  "account_type": "B",
  "business_name": "TechCorp SAS",
  "business_type": "SARL",
  "business_register_date": "2015-06-01",
  "email": "contact@techcorp.com",
  "date_birth": "1985-07-22",
  "num_document": "B987654321",
  "type_document": "id_card",
  "occupation": "CEO",
  "civility": "M",
  "gender": "M",
  "expired_document": "2031-05-30",
  "address": "45 avenue des Champs-ÉlysĂ©es",
  "country_code": "FR",
  "city": "Paris",
  "phone": "+33698765432"
}
RĂ©ponse :
{
  "message": "Sender created successfully",
  "status": "success",
  "data": {
    "account_type": "B",
    "business_name": "TechCorp SAS",
    "business_register_date": null,
    "business_type": "SARL",
    "first_name": null,
    "last_name": null,
    "email": "contact@techcorp.com",
    "phone": "+33698765432",
    "code": "25070908591851673500887",
    "occupation": "CEO",
    "civility": "M",
    "gender": "M",
    "document_type": "id_card",
    "document_expired": "2031-05-30",
    "document_number": "B987654321"
  }
}

Codes de réponse possibles :

  • 201 Created : ExpĂ©diteur crĂ©Ă© avec succĂšs
  • 400 Bad Request : DonnĂ©es invalides ou manquantes
  • 409 Conflict : ExpĂ©diteur avec ce numĂ©ro/email dĂ©jĂ  existant
  • 500 Internal Server Error : Erreur serveur lors de l’enregistrement

GET /api/beneficiaries

Ce endpoint permet de récupérer la liste des bénéficiaires enregistrés pour un expéditeur spécifique.

Il est couramment utilisĂ© pour prĂ©remplir les informations lors d’un envoi d’argent ou gĂ©rer les contacts favoris d’un utilisateur.

RequĂȘte :
GET /api/beneficiaries
RĂ©ponse :
{
  "message": "senders get successful",
  "status": "success",
  "data": [
    {
      "first_name": "emanuel kamao",
      "last_name": "fumba",
      "email": "contact@guens-education.com",
      "phone": "23796854415",
      "code": "25042553551393640666986",
      "occupation": "",
      "civility": "Maried",
      "gender": "M",
      "document_type": "PP",
      "document_expired": "2025-05-11",
      "document_number": "5879454555"
    },..
  ]
}

Codes de réponse HTTP :

  • 200 OK : Liste retournĂ©e avec succĂšs
  • 204 No Content : Aucun bĂ©nĂ©ficiaire trouvĂ©
  • 400 Bad Request : ParamĂštre manquant ou invalide
  • 404 Not Found : Endpoint non trouvĂ©

POST /api/beneficiaries

Ce endpoint permet d’enregistrer un nouveau bĂ©nĂ©ficiaire vers lequel un expĂ©diteur pourra envoyer de l’argent.

Le bĂ©nĂ©ficiaire peut ĂȘtre liĂ© Ă  un compte bancaire, un portefeuille mobile ou un point de retrait..

Corps JSON attendu :
{
  "account_type": "P",
  "first_name": "Alice",
  "last_name": "Kouassi",
  "email": "alice.kouassiu@example.com",
  "date_birth": "1992-08-25",
  "num_document": "CI123456789",
  "type_document": "passport",
  "occupation": "Comptable",
  "civility": "Single",
  "gender": "F",
  "expired_document": "2032-08-25",
  "address": "Boulevard ValĂ©ry Giscard d’Estaing",
  "country_code": "CI",
  "city": "Abidjan",
  "phone": "+2250700123456"
}
RĂ©ponse :
{
  "message": "Beneficiary created successfully",
  "status": "success",
  "data": {
    "account_type": "P",
    "business_name": null,
    "business_type": null,
    "first_name": "Alice",
    "last_name": "Kouassi",
    "email": "alice.kouassiu@example.com",
    "phone": "+2250700123456",
    "code": "25070932393437450612644",
    "occupation": "Comptable",
    "civility": "F",
    "gender": "F",
    "document_type": "passport",
    "document_expired": "2032-08-25",
    "document_number": "CI123456789"
  }
}

Codes de réponse HTTP :

  • 201 Created : BĂ©nĂ©ficiaire crĂ©Ă© avec succĂšs
  • 400 Bad Request : DonnĂ©es manquantes ou format invalide
  • 404 Not Found : ExpĂ©diteur non trouvĂ©
  • 409 Conflict : BĂ©nĂ©ficiaire dĂ©jĂ  existant pour ce numĂ©ro ou ce compte
  • 500 Internal Server Error : Erreur serveur

GET /api/transactions

Ce endpoint permet de récupérer la liste des transactions effectuées par un expéditeur.

Il prend en charge des filtres pour rechercher par statut, type, date ou bĂ©nĂ©ficiaire, facilitant ainsi le suivi des envois d’argent.

ParamĂštres de requĂȘte (query) :

        | ParamĂštre        | Type   | Description                                                                    |
        | ---------------- | ------ | ------------------------------------------------------------------------------ |
        | `sender_id`      | string | (obligatoire) Identifiant de l’expĂ©diteur                                      |
        | `status`         | string | (optionnel) Filtrer par statut (`pending`, `completed`, `failed`, `cancelled`) |
        | `type`           | string | (optionnel) Type de transaction (`bank`, `mobile_money`, `cash_pickup`)        |
        | `start_date`     | string | (optionnel) Date de début au format `YYYY-MM-DD`                               |
        | `end_date`       | string | (optionnel) Date de fin au format `YYYY-MM-DD`                                 |
        | `beneficiary_id` | string | (optionnel) Filtrer les transactions envoyées à un bénéficiaire spécifique     |
RequĂȘte :
GET /api/transactions
RĂ©ponse :
{
  "message": "senders get successful",
  "status": "success",
  "data": [
    {
      "first_name": "emanuel kamao",
      "last_name": "fumba",
      "email": "contact@guens-education.com",
      "phone": "23796854415",
      "code": "25042553551393640666986",
      "occupation": "",
      "civility": "Maried",
      "gender": "M",
      "document_type": "PP",
      "document_expired": "2025-05-11",
      "document_number": "5879454555"
    },..
  ]
}

POST /api/transactions/bank

Ce endpoint permet de crĂ©er une transaction bancaire en transfĂ©rant des fonds d’un expĂ©diteur vers un bĂ©nĂ©ficiaire disposant d’un compte bancaire.

Il vérifie les informations du client, le solde, applique les frais, et génÚre une référence de transaction.

Corps JSON attendu :
{
  "country_code": "CI",
  "gateway": "BankGatewayCI",
  "bank": "ECOBANK",
  "sender_code": "25070908591851673500887",
  "beneficiary_code": "25070943938506074307835",
  "city": "Abidjan",
  "amount": 100000,
  "raison_transaction": "Advanced Goods Payments",
  "origin_fond": "Salary",
  "relation": "Mother",
  "accountNumber": "CI11001234567890123456",
  "swift_code": "CEPAFRPP",
  "comment": "BANKS DEPOSIT",
  "callback_url": "https://votre-api.com/retour/transaction"
}

Remplacer swift_code par :

RĂ©ponse :
{
  "message": "Transaction created successfully",
  "status": "success",
  "data": {
    "transaction_status": "Pending",
    "transaction_id": "25070934967500637436125",
    "fees": 12000,
    "amount": 141.8
  }
}

Champs de réponse :

Codes de réponse HTTP :

POST /api/transactions/mobil

Ce endpoint permet de crĂ©er une transaction Mobile en transfĂ©rant des fonds d’un expĂ©diteur vers un bĂ©nĂ©ficiaire disposant d’un compte mobil money.

Il vérifie les informations du client, le solde, applique les frais, et génÚre une référence de transaction.

Corps JSON attendu :
{"country_code":"CM",
"gateway":"OM",
"sender_code":"25042521022068963666512",
"beneficiary_code":"25042553551393640666986",
"city":"Paris",
"amount":"80000",
"raison_transaction":"Business Profits to Parents",
"origin_fond":"Donation",
"relation":"Brother",
"accountNumber":"237675066919",
 "comment": "MOMO DEPOSIT",
"callback_url":"https://xxxx/webhook"
}
RĂ©ponse :
{
  "message": "transaction created successful",
  "status": "success",
  "data": {
    "transaction_id": "25050816264901015287708",
    "fees": 3600,
    "amount": 1000
  }
}

Champs de réponse :

Codes de réponse HTTP :

GET /api/transactions/status/:transaction_id

Ce endpoint permet de rĂ©cupĂ©rer le statut actuel d’une transaction donnĂ©e Ă  l’aide de son identifiant unique.

Il est utile pour les utilisateurs finaux ou les agents afin de suivre l’évolution d’un envoi (bancaire, mobile ou en espĂšces).

ParamĂštres de requĂȘte (query) :

*transaction_id (obligatoire) : L’identifiant unique de la transaction à suivre.
RequĂȘte :
GET /api/transactions/status/25050816264901015287708
RĂ©ponse :
{
  "message": "transaction successful",
  "status": "success",
  "data": {
    "transaction_id": "25050816264901015287708",
    "status": "success",
    "relation": "Brother",
    "origin_fond": "Donation",
    "motif_send": "Business Profits to Parents",
    "amount_send": 1000,
    "country": "FRANCE",
    "currency": "EUR",
    "amount_debit": 83600,
    "bank": "BANQUE POPULAIRE VAL DE FRANCE",
    "accountNumber": "011623852957",
    "sender": {
      "first_name": "kouamo",
      "last_name": "Dieudonne",
      "email": "info@agensic.com",
      "phone": "237675066919",
      "code": "25042521022068963666512",
      "occupation": "mecanicien",
      "civility": "Maried",
      "gender": "M",
      "document_type": "PP",
      "document_expired": "2025-05-10",
      "document_number": "5879454555"
    },
    "beneficiary": {
      "first_name": "emanuel kamao",
      "last_name": "fumba",
      "email": "contact@guens-education.com",
      "phone": "23796854415",
      "code": "25042553551393640666986",
      "occupation": "",
      "civility": "Maried",
      "gender": "M",
      "document_type": "PP",
      "document_expired": "2025-05-11",
      "document_number": "5879454555"
    }
  }
}

Codes de réponse HTTP :

  • 200 OK : Statut retournĂ© avec succĂšs
  • 404 Not Found : Aucune transaction trouvĂ©e avec cet identifiant
  • 400 Bad Request : Identifiant mal formĂ© ou invalide
  • 500 Internal Server Error : Erreur inattendue du serveur