# Marchands
Source: https://docs.lomi.africa/build/platform/merchants

L’API Merchants permet d’accéder aux informations des comptes marchands, métriques de revenus récurrents et soldes.

***

title: Marchands
description: L’API Merchants permet d’accéder aux informations des comptes marchands, métriques de revenus récurrents et soldes.
--------------------------------------------------------------------------------------------------------------------------------

## Authentification

Les requêtes s’authentifient avec la clé API dans l’en-tête `` `X-API-Key` ``. Voir [Authentification](/start/api-keys).

Pour réglages, tarification et indicateurs au niveau organisation, privilégiez l’API [Organisations](/build/platform/organizations) 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 :**

| Paramètre  | Type           | Obligatoire | Description                     |
| ---------- | -------------- | ----------- | ------------------------------- |
| `` `id` `` | `` `string` `` | Oui         | Identifiant unique du marchand. |

**Exemple de réponse (200 OK) :**

```json filename="Exemple de réponse pour GET /merchants/{id}"
{
  "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](/api/data-models#merchant-object) pour la description des propriétés.)*

**Erreurs possibles :**

| Code HTTP   | Code d’erreur              | Description                               |
| ----------- | -------------------------- | ----------------------------------------- |
| `` `401` `` | `` `UNAUTHORIZED` ``       | Authentification échouée ou clé invalide. |
| `` `404` `` | `` `MERCHANT_NOT_FOUND` `` | Aucun marchand pour cet identifiant.      |
| `` `500` `` | `` `DATABASE_ERROR` ``     | Erreur lors de la lecture du marchand.    |
| `` `500` `` | `` `INTERNAL_ERROR` ``     | Erreur serveur interne.                   |

### MRR mensuel du marchand

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

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

**Paramètres de chemin :**

| Paramètre  | Type           | Obligatoire | Description                     |
| ---------- | -------------- | ----------- | ------------------------------- |
| `` `id` `` | `` `string` `` | Oui         | Identifiant unique du marchand. |

**Exemple de réponse (200 OK) :**

```json filename="Exemple de réponse pour GET /merchants/{id}/mrr"
{
  "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 :**

| Code HTTP   | Code d’erreur              | Description                               |
| ----------- | -------------------------- | ----------------------------------------- |
| `` `401` `` | `` `UNAUTHORIZED` ``       | Authentification échouée ou clé invalide. |
| `` `404` `` | `` `MERCHANT_NOT_FOUND` `` | Aucun marchand pour cet identifiant.      |
| `` `404` `` | `` `NOT_FOUND` ``          | Aucune donnée MRR pour ce marchand.       |
| `` `500` `` | `` `DATABASE_ERROR` ``     | Erreur lors de la lecture du MRR.         |
| `` `500` `` | `` `INTERNAL_ERROR` ``     | Erreur serveur interne.                   |

### ARR annuel du marchand

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

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

**Paramètres de chemin :**

| Paramètre  | Type           | Obligatoire | Description                     |
| ---------- | -------------- | ----------- | ------------------------------- |
| `` `id` `` | `` `string` `` | Oui         | Identifiant unique du marchand. |

**Exemple de réponse (200 OK) :**

```json filename="Exemple de réponse pour GET /merchants/{id}/arr"
{
  "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 :**

| Code HTTP   | Code d’erreur              | Description                               |
| ----------- | -------------------------- | ----------------------------------------- |
| `` `401` `` | `` `UNAUTHORIZED` ``       | Authentification échouée ou clé invalide. |
| `` `404` `` | `` `MERCHANT_NOT_FOUND` `` | Aucun marchand pour cet identifiant.      |
| `` `404` `` | `` `NOT_FOUND` ``          | Aucune donnée ARR pour ce marchand.       |
| `` `500` `` | `` `DATABASE_ERROR` ``     | Erreur lors de la lecture de l’ARR.       |
| `` `500` `` | `` `INTERNAL_ERROR` ``     | Erreur serveur interne.                   |

### 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ètre  | Type           | Obligatoire | Description                     |
| ---------- | -------------- | ----------- | ------------------------------- |
| `` `id` `` | `` `string` `` | Oui         | Identifiant unique du marchand. |

**Paramètres de requête :**

| Paramètre             | Type           | Obligatoire | Description                                     |
| --------------------- | -------------- | ----------- | ----------------------------------------------- |
| `` `currency_code` `` | `` `string` `` | Oui         | Devise du solde (ex. `` `XOF` ``, `` `USD` ``). |

**Exemple de réponse (200 OK) :**

```json filename="Exemple de réponse pour GET /merchants/{id}/balance"
{
  "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 :**

| Code HTTP   | Code d’erreur             | Description                               |
| ----------- | ------------------------- | ----------------------------------------- |
| `` `400` `` | `` `MISSING_PARAMETER` `` | Paramètre `` `currency_code` `` absent.   |
| `` `401` `` | `` `UNAUTHORIZED` ``      | Authentification échouée ou clé invalide. |
| `` `500` `` | `` `DATABASE_ERROR` ``    | Erreur lors de la lecture du solde.       |
| `` `500` `` | `` `INTERNAL_ERROR` ``    | Erreur serveur interne.                   |

## 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](/api/errors) pour la gestion d’erreurs générale.