Documentation API

Bienvenue sur la documentation de l'API Paayit. Notre API vous permet d'intégrer facilement les paiements Mobile Money (MTN, Orange) dans vos applications. Accédez à des encaissements instantanés, des paiements automatisés et un suivi des transactions en temps réel grâce à notre API REST conviviale pour les développeurs.

Authentification

Authentifiez vos requêtes API en incluant votre Clé Publique (Public Key) dans l'en-tête X-API-Key de chaque requête. L'absence d'une clé valide entraînera une erreur 401 Unauthorized.

Exemple d'en-tête

X-API-Key: pk_live_12345678...

Erreurs

Paayit utilise les codes de réponse HTTP standard pour indiquer le succès ou l'échec de vos requêtes API.

200OK

Requête réussie

400Mauvaise Requête

Paramètres invalides ou champs manquants

401Non Autorisé

Clé API invalide ou manquante

403Interdit

Adresse IP non autorisée

404Non Trouvé

La ressource n'existe pas

500Erreur Serveur

Un problème est survenu de notre côté

Collecter de l'argent

Initier une demande de collecte Mobile Money (USSD push) vers un client.

POST/api/v1/deposits

Initier une collecte

Envoyer une demande de paiement vers le portefeuille Mobile Money d'un client.

Parameters

amountnumberrequired

Montant en XAF (Min: 100, Max: 500,000)

Example: 5000

phone_numberstringrequired

Numéro de téléphone du client (format international)

Example: +237670000000

servicestringrequired

Opérateur Mobile Money (MTN ou ORANGE)

Example: MTN

referencestring

Votre référence unique pour cette transaction

Example: COMMANDE-123

Request Body

Le montant numérique, le numéro de téléphone et l'opérateur sont requis.

{
  "amount": 5000,
  "phone_number": "+237670000000",
  "service": "MTN",
  "reference": "COMMANDE-123"
}

Response Example

{
  "id": "txn_123456789",
  "type": "deposit",
  "mode": "live",
  "status": "pending",
  "amount": 5000,
  "fees": 100,
  "net_amount": 4900,
  "phone_number": "+237670000000",
  "service": "MTN",
  "reference": "COMMANDE-123",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Example Request

curl -X POST https://api.mydv.us/api/v1/deposits \
  -H "Content-Type: application/json" \
  -H "X-API-Key: VOTRE_CLE_PUBLIQUE" \
  -d '{
    "amount": 5000,
    "phone_number": "+237670000000",
    "service": "MTN",
    "reference": "COMMANDE-123"
  }'

Retirer des fonds

Envoyer de l'argent depuis votre solde Paayit vers un portefeuille Mobile Money.

POST/api/v1/withdrawals

Initier un retrait

Transférer des fonds vers un bénéficiaire via Mobile Money.

Parameters

amountnumberrequired

Montant en XAF à décaisser

Example: 5000

phone_numberstringrequired

Numéro de téléphone du bénéficiaire

Example: +237670000000

servicestringrequired

Opérateur Mobile Money (MTN ou ORANGE)

Example: MTN

referencestring

Votre référence unique

Example: PAIEMENT-001

Request Body

Requis: montant, téléphone du bénéficiaire, opérateur.

{
  "amount": 5000,
  "phone_number": "+237670000000",
  "service": "MTN",
  "reference": "PAIEMENT-001"
}

Response Example

{
  "id": "txn_987654321",
  "type": "withdrawal",
  "mode": "live",
  "status": "pending",
  "amount": 5000,
  "fees": 100,
  "net_amount": 4900,
  "phone_number": "+237670000000",
  "service": "MTN",
  "reference": "PAIEMENT-001",
  "created_at": "2024-01-15T12:00:00Z"
}

Example Request

curl -X POST https://api.mydv.us/api/v1/withdrawals \
  -H "Content-Type: application/json" \
  -H "X-API-Key: VOTRE_CLE_PUBLIQUE" \
  -d '{
    "amount": 5000,
    "phone_number": "+237670000000",
    "service": "MTN",
    "reference": "PAIEMENT-001"
  }'

Transactions

Récupérer et surveiller l'historique de vos transactions.

GET/api/v1/transactions

Lister les transactions

Obtenir une liste paginée de vos transactions.

Parameters

limitnumber

Nombre de résultats (Défaut: 20)

Example: 20

offsetnumber

Décalage pour la pagination

Example: 0

statusstring

Filtrer par statut (success, pending, failed)

Example: success

Response Example

{
  "transactions": [
    {
      "id": "txn_123456789",
      "type": "deposit",
      "status": "success",
      "amount": 5000,
      "service": "MTN",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 150,
  "limit": 20,
  "offset": 0
}

Example Request

curl -X GET "https://api.mydv.us/api/v1/transactions?limit=20" \
  -H "X-API-Key: VOTRE_CLE_PUBLIQUE"

GET/api/v1/transactions/:id

Obtenir les détails d'une transaction

Récupérer les détails complets d'une seule transaction par ID.

Parameters

idstringrequired

L'ID de la transaction (ex: txn_...)

Example: txn_123456789

Response Example

{
  "id": "txn_123456789",
  "type": "deposit",
  "status": "success",
  "amount": 5000,
  "fees": 100,
  "net_amount": 4900,
  "phone_number": "+237670000000",
  "service": "MTN",
  "reference": "COMMANDE-123",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:05Z"
}

Example Request

curl -X GET https://api.mydv.us/api/v1/transactions/txn_123456789 \
  -H "X-API-Key: VOTRE_CLE_PUBLIQUE"

Webhooks

Recevez des notifications en temps réel pour les événements de transaction (succès, échec).

Vérification des signatures

Paayit signe chaque requête webhook pour vous permettre de vérifier son authenticité. La signature est envoyée dans l'en-tête X-Paayit-Signature.

// Exemple de vérification (Node.js) const crypto = require('crypto'); const secret = 'votre_secret_webhook'; // Disponible dans les paramètres const signature = req.headers['x-paayit-signature']; const payload = JSON.stringify(req.body); const hmac = crypto.createHmac('sha256', secret) .update(payload) .digest('hex'); if (hmac === signature) { // La requête est authentique }

Structure de l'événement

{
  "event": "transaction.updated",
  "transaction_id": "txn_123456789",
  "type": "deposit",
  "status": "success",
  "amount": 5000,
  "net_amount": 4900,
  "phone_number": "+237670000000",
  "service": "MTN",
  "timestamp": "2024-03-20T10:00:00Z"
}