Marchands

Authentification

Les requêtes s’authentifient avec la clé API dans l’en-tête `X-API-Key`. Voir Authentification.

Pour réglages, tarification et indicateurs au niveau organisation, privilégiez l’API Organisations lorsque votre clé porte sur l’organisation.

Endpoints

Détails d’un marchand

Récupère le détail d’un compte marchand.

URL : `GET /merchants/{id}`

Paramètres de chemin :

Exemple de réponse (200 OK) :

{
  "data": {
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "name": "Test Merchant",
    "email": "merchant@example.com",
    "phone_number": "+123456789",
    "country": "SN",
    "mrr": 50000, // In smallest currency unit
    "arr": 600000, // In smallest currency unit
    "merchant_lifetime_value": 14250, // LTV prédictive par client, devise par défaut de l'org
    "retry_payment_every": 3,
    "total_retries": 5,
    "metadata": {
      "industry": "e-commerce"
    },
    "created_at": "2023-01-15T10:30:00Z",
    "updated_at": "2023-02-20T14:45:00Z"
  }
}

(Voir Modèles de données pour la description des propriétés.)

Erreurs possibles :

MRR mensuel du marchand

Récupère le MRR courant d’un marchand.

URL : `GET /merchants/{id}/mrr`

Paramètres de chemin :

Exemple de réponse (200 OK) :

{
  "data": {
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "mrr": 50000, // In smallest currency unit
    "currency_code": "XOF",
    "as_of_date": "2023-04-01T00:00:00Z"
  }
}

Erreurs possibles :

ARR annuel du marchand

Récupère l’ARR courant d’un marchand.

URL : `GET /merchants/{id}/arr`

Paramètres de chemin :

Exemple de réponse (200 OK) :

{
  "data": {
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "arr": 600000, // In smallest currency unit
    "currency_code": "XOF",
    "as_of_date": "2023-04-01T00:00:00Z"
  }
}

Erreurs possibles :

Solde du compte marchand

Récupère le solde courant d’un marchand pour une devise donnée.

URL : `GET /merchants/{id}/balance`

Paramètres de chemin :

Paramètres de requête :

Exemple de réponse (200 OK) :

{
  "data": {
    "merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
    "currency_code": "XOF",
    "balance": 250000, // In smallest currency unit
    "as_of_date": "2023-04-01T12:30:45Z"
  }
}

Erreurs possibles :

Notes d’implémentation

• Périmètre organisation : les détails marchand, le MRR et l’ARR portent toujours sur l’organisation liée à votre clé API. Si un marchand appartient à plusieurs organisations, vous ne voyez que les métriques de l’org de votre clé — jamais de données cross-org.
• Les métriques en cache (`mrr`, `arr`, `merchant_lifetime_value`, volumes clients/transactions) sont rafraîchies chaque jour à 03:00 UTC en live, et à nouveau lors des changements d’abonnement. `as_of_date` sur les réponses MRR/ARR reflète le dernier rafraîchissement ; pour le solde, c’est le `updated_at` du compte.
• `mrr` / `arr` sont le revenu récurrent mensuel / annuel de l’organisation liée (abonnements actifs), dans la devise par défaut de l’org.
• `merchant_lifetime_value` est une LTV prédictive par client pour l’organisation liée (environnement live) : valeur client (revenu net par client payeur) multipliée par la durée de vie moyenne (dérivée des achats répétés, plafonnée à 5x). Ce n’est pas le profit plateforme tiré du marchand (réservé aux admins).
• Les dates sont au format ISO 8601 (`YYYY-MM-DDTHH:mm:ssZ`).
• Voir Erreurs pour la gestion d’erreurs générale.