HayBTech

Appearance

Référence API HayBTech (Cash-In & Cash-Out) ​

Bienvenue dans la documentation technique unifiée de HayBTech. Cette API vous permet d'intégrer les paiements (encaissements) et les payouts (virements) via une interface unique.

Authentification & Configuration ​

Toutes les requêtes doivent inclure les headers suivants :

| Authorization | Bearer sk_live_... (ou sk_test_...) | | Idempotency-Key | Un UUID unique (obligatoire pour les payouts). | | Content-Type | application/json |

SÉCURITÉ CRITIQUE

Les clés secrètes (sk_...) ne doivent JAMAIS être exposées côté client (navigateur, mobile). Elles doivent rester exclusivement sur votre serveur backend.

1. Paiements (Cash-In) ​

Utilisez cet endpoint pour encaisser de l'argent auprès de vos clients.

POST /v1/payments

Paramètres de paiement ​

json
{
  "merchant_ref": "ORDER-123",
  "amount": 5000,
  "currency": "XOF",
  "provider": "wave",
  "phone": "+221770000123",
  "name": "Awa Diop",
  "success_url": "https://votre-site.sn/success",
  "failed_url": "https://votre-site.sn/cancel",
  "callback_url": "https://votre-site.sn/webhooks/haybtech"
}

FLEXIBILITÉ DES CHAMPS

Pour faciliter l'intégration, vous pouvez envoyer les informations du payer de trois façons :

  1. Imbriqué (recommandé) : "payer": {"phone": "...", "name": "..."}
  2. À plat : "phone": "...", "name": "..."
  3. Préfixé : "payer_phone": "...", "payer_name": "..."
ChampTypeRequisDescription
merchant_refstringouiVotre référence de commande unique.
amountnumericouiMontant à payer (ex: 5000).
providerstringouiwave, orange_money, free_money.
success_urlurlouiRedirection après succès.
failed_urlurlouiRedirection après annulation.
callback_urlurlnonWebhook spécifique à cette transaction.
metadataobjectnonDonnées libres renvoyées dans les webhooks.

2. Virements (Cash-Out) ​

Utilisez cet endpoint pour envoyer de l'argent vers un compte Mobile Money.

POST /v1/payouts

Paramètres de virement ​

json
{
  "merchant_ref": "PYO-456",
  "amount": 10000,
  "currency": "XOF",
  "provider": "wave",
  "recipient": {
    "phone": "+221770000000",
    "name": "Jean Dupont"
  },
  "description": "Règlement facture #123",
  "callback_url": "https://votre-site.sn/webhooks/payouts"
}
ChampTypeRequisDescription
merchant_refstringouiVotre référence unique pour ce virement.
amountnumericouiMontant brut à envoyer.
providerstringouiwave, orange_money, free_money.
recipient.phonestringouiNuméro au format E.164.
recipient.namestringnonNom du bénéficiaire.
callback_urlurlnonWebhook spécifique à cette transaction.

IDEMPOTENCE

Pour les virements, utilisez toujours une Idempotency-Key unique par transaction logique. Si vous recevez une erreur réseau, renvoyez la même clé. HayBTech garantit qu'un virement avec la même clé ne sera exécuté qu'une seule fois.

Lister les virements ​

GET /v1/payouts?status=success&from=2026-01-01&to=2026-12-31

Filtres : status, provider, from, to, merchant_ref. Scope requis : can_read_transactions.

Détailler un virement ​

GET /v1/payouts/{id} (accepte aussi votre merchant_ref).

3. États & Cycle de vie ​

Toutes les transactions (paiements et virements) suivent un cycle de vie précis.

Statuts Communs ​

  • initiated : Transaction créée, en attente de traitement.
  • pending : En attente d'action du client (pour les paiements).
  • success : Terminée avec succès.
  • failed : Échec (solde insuffisant, rejet provider, etc).

Cycle de vie des fonds (Payouts) ​

  1. Lors de la création (initiated), le montant est réservés sur votre solde HayBTech.
  2. En cas de success, le débit devient définitif.
  3. En cas de failed ou cancelled, la réservation est levée et les fonds redeviennent disponibles immédiatement.

4. Consultation & Statuts ​

Vérification de statut unifiée ​

Utilisez cet endpoint pour vérifier l'état de n'importe quelle transaction (paiement ou virement) via une référence unique.

GET /v1/status/{reference}

Le paramètre {reference} peut être l'ID HayBTech (TXN-...) ou votre merchant_ref.

5. Finance & Solde ​

Consultation du solde ​

Récupérez votre solde disponible en temps réel.

GET /v1/balance

Réponse :

json
{
  "object": "balance",
  "currency": "XOF",
  "available": 150000,
  "pending": 25000,
  "reserved": 10000,
  "last_updated": "2026-05-07T21:00:00Z"
}

Liste des reversements (Settlements) ​

Suivez les fonds qui vous ont été reversés par HayBTech.

GET /v1/settlements

6. Outils Développeurs ​

Test de Webhook ​

Déclenchez un événement de test pour valider votre intégration serveur.

POST /v1/webhooks/test

6. Remboursements (Refunds) ​

Si vous devez rembourser un client après un paiement réussi. Le montant doit être inférieur ou égal au montant original de la transaction.

POST /v1/refunds

json
{
  "transaction_id": "TXN-T3A79YRJ",
  "amount": 500,
  "reason": "Retour produit"
}

7. Configuration & Providers ​

Liste des providers ​

Récupérez la liste des opérateurs supportés pour votre compte selon votre pays.

GET /v1/providers

8. Appels de fonds (Payout Requests) ​

Demandez un retrait de votre solde marchand. HayBTech ops valide ou rejette la demande, puis exécute le settlement vers votre RIB / numéro Mobile Money.

Créer une demande ​

POST /v1/payout-requests

Scope requis : can_payout. Idempotency-Key obligatoire. Throttle : 10 req/min.

json
{
  "amount": 250000,
  "currency": "XOF",
  "destination_phone": "+221770000000",
  "destination_iban": null,
  "destination_bank": null,
  "merchant_note": "Retrait hebdomadaire"
}

Réponse 201 :

json
{
  "data": {
    "id": "uuid",
    "object": "payout_request",
    "reference": "PR-...",
    "status": "submitted",
    "amount": "250000.00",
    "fee_amount": "0.00",
    "net_amount": "250000.00",
    "currency": "XOF",
    "destination": { "phone": "+221770000000", "iban": null, "bank": null },
    "submitted_at": "2026-05-09T10:00:00Z"
  }
}

Le montant est réservé sur votre solde dès la soumission ; il est libéré en cas de rejet, ou consommé à la complétion du settlement.

Lister vos demandes ​

GET /v1/payout-requests → 50 dernières demandes, ordre antéchronologique.

Détailler une demande ​

GET /v1/payout-requests/{id}

Statuts possibles : submitted → approved → completed, ou submitted → rejected (avec rejection_reason), ou approved → failed.

9. Litiges (Disputes) ​

Lorsqu'un payeur conteste une transaction auprès de son provider (chargeback, contestation Mobile Money), HayBTech ouvre un dispute associé à votre transaction. Vous disposez d'une fenêtre limitée pour répondre avec des preuves.

Lister vos litiges ​

GET /v1/disputes?status=needs_response&per_page=25

Scope requis : can_read_transactions. Pagination via pagination.{total,per_page,current_page,last_page}.

Détailler un litige ​

GET /v1/disputes/{id} (accepte aussi votre reference).

Répondre avec preuves ​

POST /v1/disputes/{id}/respond

Scope requis : can_initiate_payment. Idempotency-Key obligatoire.

json
{
  "evidence": [
    "https://shop.sn/uploads/invoice-CMD-42.pdf",
    "https://shop.sn/uploads/proof-delivery.png"
  ],
  "merchant_response": "Produit livré le 2026-05-02, signature confirmée."
}

Maximum 20 URLs de preuves, chacune ≤ 500 caractères ; commentaire libre ≤ 2000 caractères. Une réponse n'est acceptée que si le litige est encore ouvert (needs_response).

10. Webhooks ​

Il est fortement recommandé de configurer un webhook pour recevoir les confirmations en temps réel.

  • Paiements : événements payment.success, payment.failed, payment.cancelled, payment.expired.
  • Virements : événements payout.success, payout.failed.
  • Appels de fonds : événements payout_request.submitted, payout_request.approved, payout_request.rejected, payout_request.completed, payout_request.failed.
  • Remboursements : événement refund.success.
  • Litiges : événements dispute.opened, dispute.responded, dispute.won, dispute.lost.

Chaque webhook est signé avec un secret HMAC pour garantir l'intégrité des données. Voir Webhooks pour le détail de la vérification.

Documentation de l'API de paiement HayBTech.

Copyright © HayBTech SARL.