API FATHPAY v1

REST · JSON · TLS · Bearer token · idempotence native · rate-limit 60 rpm.

Base URL

https://fathpay.app/api/public/v1

Deux environnements selon votre clé : fp_test_… = Sandbox, fp_live_… = Live.

Authentification

Toutes les requêtes (sauf /health) requièrent un header :

Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Générez vos clés depuis votre tableau de bord. La clé n'est affichée qu'une seule fois — elle est stockée hashée (SHA-256) côté serveur.

Sécurité

TLS 1.2+ obligatoire.
Clés hashées (SHA-256) — impossibles à récupérer en clair.
Révocation immédiate depuis le dashboard.
Rate-limit : 60 requêtes/minute par clé (30 sur les écritures).
Idempotence : header Idempotency-Key sur les POST sensibles.
Webhooks signés HMAC-SHA256.
Logs d'accès horodatés et IP traçable.

GET /health

Vérifie l'état du service. Pas d'auth.

curl https://fathpay.app/api/public/v1/health

{ "ok": true, "service": "fathpay-api", "version": "v1", "time": "..." }

GET /me

Retourne le profil associé à la clé API.

curl https://fathpay.app/api/public/v1/me \
  -H "Authorization: Bearer fp_live_..."

{
  "ok": true,
  "environment": "live",
  "profile": {
    "id": "uuid", "username": "string", "email": "string",
    "first_name": "string", "last_name": "string",
    "country": "SN", "kyc_status": "approved"
  }
}

GET /wallets

Liste vos wallets multi-devises (XOF, EUR, USD).

curl https://fathpay.app/api/public/v1/wallets -H "Authorization: Bearer fp_live_..."

{
  "ok": true,
  "wallets": [
    { "id": "uuid", "currency": "XOF", "balance": 125000.00 },
    { "id": "uuid", "currency": "EUR", "balance": 42.50 },
    { "id": "uuid", "currency": "USD", "balance": 0.00 }
  ]
}

GET /transactions

Historique paginé. Paramètres : limit (1-100, def 25), cursor (ISO date), type.

curl "https://fathpay.app/api/public/v1/transactions?limit=20&type=deposit" \
  -H "Authorization: Bearer fp_live_..."

{
  "ok": true,
  "transactions": [
    {
      "id": "uuid", "type": "deposit", "status": "completed",
      "currency": "EUR", "amount": 50.00, "fee": 1.00,
      "net_amount": 49.00, "reference": "LEEK-...",
      "created_at": "2026-05-09T01:23:00Z"
    }
  ],
  "next_cursor": "2026-05-09T01:23:00Z"
}

POST /transfers

Envoie de l'argent vers un utilisateur FATHPAY (par username). En sandbox, la requête est simulée et ne déplace aucun fonds.

curl -X POST https://fathpay.app/api/public/v1/transfers \
  -H "Authorization: Bearer fp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tx-2026-05-09-001" \
  -d '{
    "to_username": "amadou",
    "currency": "XOF",
    "amount": 5000
  }'

{ "ok": true, "reference": "API-TRF-..." }

Erreurs : insufficient_funds (402), recipient_not_found (404), rate_limited (429).

Webhooks de paiement (entrants)

FATHPAY reçoit les notifications de paiement de sa passerelle sur un endpoint privé sécurisé. La signature est vérifiée via HMAC-SHA256 du body. Tout événement non signé est rejeté en 401 et journalisé.

Codes d'erreur

unauthorized 401 — clé manquante/invalide/révoquée
invalid_request 422 — corps mal formé (Zod)
insufficient_funds 402 — solde insuffisant
recipient_not_found 404
rate_limited 429 — trop de requêtes
invalid_json 400

SDK & Support

Support développeur : dev@fathpay.app · WhatsApp +221 78 454 88 46.

SDK officiels (JS, Node, PHP, Python) en cours — l'API REST reste la source de vérité.