# Modèles de données Source: https://docs.lomi.africa/api/data-models Les objets courants renvoyés par l’API publique lomi., avec les champs les plus utiles pour intégrer. *** title: 'Modèles de données' description: 'Les objets courants renvoyés par l’API publique lomi., avec les champs les plus utiles pour intégrer.' -------------------------------------------------------------------------------------------------------------------- Cette page explique les objets que vous croiserez dans l’API marchande publique. Ce n’est pas une liste brute de tous les schémas internes. Les objets réservés à l’administration du tableau de bord, à la configuration des prestataires ou aux opérations lomi. ne sont pas exposés ici. Les pages d’endpoint restent la source de vérité pour les requêtes et réponses exactes. Cette page sert à comprendre les objets que votre intégration va stocker, afficher ou réconcilier. ## Conventions communes | Champ | Signification | | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `id`, `*_id` | Identifiant stable d’un objet. Stockez-le si vous devez retrouver ou réconcilier l’objet plus tard. | | `amount`, `gross_amount`, `net_amount`, `fee_amount` | Montant entier dans la plus petite unité monétaire. Pour `XOF`, `5000` signifie 5 000 XOF. | | `currency_code` | Code devise ISO comme `XOF`, `USD` ou `EUR`. | | `metadata` | Vos propres paires clé-valeur, par exemple un identifiant de commande ou d’utilisateur. | | `environment` | `test` ou `live`. Ne mélangez pas les objets des deux environnements dans un même flux de réconciliation. | | `created_at`, `updated_at` | Horodatages ISO 8601. | ## Client Un client représente l’acheteur ou le payeur lié aux paiements, abonnements et sessions de portail. Renvoyé par les endpoints [Clients](/api/customers) et parfois inclus dans les réponses de paiement ou d’abonnement. ```json filename="Client" { "customer_id": "cus_123", "name": "Awa Diop", "email": "awa@example.com", "phone_number": "+221771234567", "country": "SN", "metadata": { "crm_id": "lead_981" }, "environment": "live", "created_at": "2026-02-14T10:30:00.000Z", "updated_at": "2026-02-14T10:30:00.000Z" } ``` ## Produit et prix Un produit correspond à ce que vous vendez. Un prix définit le montant et le comportement de facturation associé. Renvoyé par les endpoints [Produits](/api/products), checkout et abonnements. ```json filename="Produit avec prix" { "product_id": "prod_123", "name": "Forfait Pro", "description": "Accès mensuel à l’espace Pro", "product_type": "recurring", "is_active": true, "metadata": { "plan_code": "pro" }, "prices": [ { "price_id": "price_123", "amount": 15000, "currency_code": "XOF", "billing_interval": "month", "pricing_model": "standard", "is_default": true } ], "environment": "live" } ``` ## Session checkout Une session checkout crée une page de paiement hébergée. Votre application redirige le client vers `checkout_url`, puis suit le statut via les redirections et les webhooks. Le statut est `open`, `completed` ou `expired`. Renvoyée par [Sessions checkout](/api/checkout-sessions). ```json filename="Session checkout" { "checkout_session_id": "123e4567-e89b-12d3-a456-426614174000", "status": "open", "amount": 15000, "currency_code": "XOF", "checkout_url": "https://checkout.lomi.africa/checkout/123e4567-e89b-12d3-a456-426614174000", "success_url": "https://example.com/success", "cancel_url": "https://example.com/cancel", "expires_at": "2026-02-14T11:30:00.000Z", "metadata": { "order_id": "order_481" } } ``` ## Lien de paiement Un lien de paiement est une URL hébergée durable que vous pouvez partager. Le champ `url` est sur `pay.lomi.africa`. L’ouvrir crée une session checkout. Renvoyé par [Liens de paiement](/api/payment-links). ```json filename="Lien de paiement" { "link_id": "plink_123", "title": "Forfait Pro", "amount": 15000, "currency_code": "XOF", "url": "https://pay.lomi.africa/ABCDEFGHJKLMNP", "is_active": true, "environment": "live" } ``` ## Encaissement direct Un encaissement direct lance un paiement spécifique à un prestataire sans checkout hébergé. Utilisez-le seulement si vous devez contrôler vous-même l’expérience de paiement. `POST /charge/wave`, `POST /charge/mtn` et `POST /charge/card` sont les rails actifs. `POST /charge/switch` renvoie `503 service_unavailable`. Renvoyé par [Encaissements directs avancés](/api/charge). ```json filename="Encaissement Wave ou MTN" { "success": true, "transaction_id": "123e4567-e89b-12d3-a456-426614174000", "status": "pending", "next_action": { "type": "redirect", "url": "https://pay.wave.com/c/abc123" } } ``` Wave peut aussi renvoyer `wave_launch_url` ou `checkout_url`. MTN enveloppe la transaction dans `data` (`data.transaction_id`, `data.status`). Suivez toujours `next_action` lorsqu’il est présent. ## Abonnement Un abonnement représente un accès récurrent pour un client. Le statut est `pending`, `active`, `past_due`, `cancelled`, `trial`, `paused` ou `expired`. Renvoyé par [Abonnements](/api/subscriptions). ```json filename="Abonnement" { "subscription_id": "sub_123", "customer_id": "cus_123", "product_id": "prod_123", "price_id": "price_123", "status": "active", "start_date": "2026-02-01", "end_date": null, "next_billing_date": "2026-03-01", "metadata": { "workspace_id": "wk_42" } } ``` ## Transaction Une transaction est l’enregistrement comptable d’un mouvement d’argent. Utilisez-la pour la réconciliation, le reporting et le support. Le statut est `pending`, `completed`, `failed`, `refunded`, `expired` ou `held`. Voir [Cycle de vie des paiements](/build/reliability/payment-lifecycle). Renvoyée par [Transactions](/api/transactions). ```json filename="Transaction" { "transaction_id": "123e4567-e89b-12d3-a456-426614174000", "gross_amount": 5000, "fee_amount": 125, "net_amount": 4875, "currency_code": "XOF", "transaction_type": "payment", "status": "completed", "provider_code": "WAVE", "payment_method_code": "MOBILE_MONEY", "metadata": { "order_id": "order_481" }, "created_at": "2026-02-14T10:31:04.000Z" } ``` ## Remboursement Un remboursement restitue de l’argent sur une transaction `completed`. Renvoyé par [Remboursements](/api/refunds). ```json filename="Remboursement" { "refund_id": "123e4567-e89b-12d3-a456-426614174000", "transaction_id": "123e4567-e89b-12d3-a456-426614174000", "refunded_amount": 5000, "status": "completed" } ``` ## Virement Un virement sort des fonds de votre solde lomi. `kind` vaut `withdrawal` (vers vous) ou `beneficiary` (vers un tiers). Le statut passe en général par `pending` → `processing` → `completed` ou `failed`. Renvoyé par [Virements](/api/payouts). ```json filename="Virement" { "success": true, "payout_id": "123e4567-e89b-12d3-a456-426614174000", "kind": "withdrawal", "status": "processing" } ``` ## Solde `GET /accounts/balance` renvoie le montant courant par devise. Renvoyé par [Soldes](/api/balances). ```json filename="Solde" { "currency_code": "XOF", "balance": 275000, "last_updated": "2026-02-14T10:45:00.000Z" } ``` Le disponible vs en attente est sur l’endpoint de répartition (`available_balance`, `pending_balance`, `total_balance`). Voir [Solde et règlement](/build/money/balance-and-settlement). ## Endpoint webhook Un endpoint webhook indique à lomi. où livrer les événements. Le `secret` de signature n’est renvoyé qu’à la **création**. Les listes et lectures utilisent `webhook_id` et n’incluent pas le secret. Renvoyé par [Webhooks](/api/webhooks). ```json filename="Endpoint webhook (création)" { "webhook_id": "123e4567-e89b-12d3-a456-426614174000", "url": "https://example.com/webhooks/lomi", "authorized_events": ["PAYMENT_SUCCEEDED", "PAYMENT_FAILED"], "is_active": true, "secret": "whsec_...", "created_at": "2026-02-14T10:30:00.000Z" } ``` ## Journal de livraison webhook Un journal de livraison décrit une tentative d’envoi webhook. Renvoyé dans [Webhooks](/api/webhooks). ```json filename="Journal de livraison webhook" { "log_id": "123e4567-e89b-12d3-a456-426614174000", "webhook_id": "123e4567-e89b-12d3-a456-426614174000", "event_type": "PAYMENT_SUCCEEDED", "success": false, "response_status": 500, "attempt_number": 3, "created_at": "2026-02-14T10:45:00.000Z" } ``` ## Erreur Les erreurs renvoient un code machine, un message lisible et, lorsque disponible, des détails structurés. ```json filename="Erreur" { "error": { "code": "unauthorized", "message": "Invalid API key", "details": "The provided API key is invalid or does not exist" }, "request_id": "550e8400-e29b-41d4-a716-446655440000" } ``` Voir [Erreurs](/api/errors) pour les codes HTTP et les échecs courants. ## Requête ### Paramètres d’URL *Pas d’autre paramètre dans l’URL.* ### Paramètres de requête *Aucun paramètre de requête.* ### En-têtes | Nom | Emplacement | Obligatoire | Schéma | Description | | -------------- | ----------- | ----------- | ------ | ---------------------------------------------------------------------------------------------------- | | `Lomi-Version` | header | Non | - | Optional schema version pin. Echoes OpenAPI info.version (currently 1.2.0). Routes stay unversioned. | ## Réponses | Statut | Description | | ------ | ----------- | | `200` | - | ## Erreurs Les erreurs suivent un format JSON standard. **401** : clé manquante ou invalide. **404** : ressource introuvable. **429** : trop de requêtes. Pour les créations, envoyez une clé d’idempotence si votre flux le permet.