> For the complete documentation index, see [llms.txt](https://docs.intram.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.intram.org/merchant-api-v1/merchant-api.md).

# Overview

L'**API Merchant** est l'interface server-to-server pour piloter votre compte Intram depuis votre backend : lire le solde, déclencher des payouts, demander un paiement à un client, rembourser une transaction, recevoir des notifications signées.

Elle remplace progressivement l'ancienne API `/api/v1/payments/*` pour les usages backend ; les routes existantes restent en service inchangées (rétrocompatibilité totale).

## Caractéristiques

* **Asynchrone par défaut** — les mutations renvoient `202 Accepted` avec un `operation_id` que vous pouvez suivre par polling ou webhook signé.
* **Signée** — chaque requête porte un HMAC-SHA256 de son contenu (anti-tampering + anti-replay 5 min).
* **Idempotente** — chaque POST exige un `Idempotency-Key`; les rejeux dans les 24 h renvoient la réponse d'origine sans réexécuter.
* **Sandbox / Live isolés** — les clés sandbox touchent un wallet de test, les clés live touchent l'argent réel et exigent une whitelist IP.
* **Webhooks signés** — chaque event est livré avec un en-tête `X-Intram-Signature` et retenté selon un backoff exponentiel.

## Base URL

| Environnement        | URL                                              |
| -------------------- | ------------------------------------------------ |
| Production / Live    | `https://api.intram.org/v1`                      |
| Production / Sandbox | `https://api.intram.org/v1` (clé `pk_sandbox_…`) |

Le mode (sandbox vs live) est déterminé par la **clé** présentée — pas par l'URL.

## Endpoints en un coup d'œil

| Méthode           | Path                       | Description                                        | Type        |
| ----------------- | -------------------------- | -------------------------------------------------- | ----------- |
| `GET`             | `/balance`                 | Solde wallet courant                               | Synchrone   |
| `POST`            | `/payouts`                 | Reversement vers Mobile Money ou compte bancaire   | Async (202) |
| `POST`            | `/payment-requests`        | Demande de paiement client (renvoie l'URL gateway) | Async (202) |
| `POST`            | `/refunds`                 | Rembourse une transaction                          | Async (202) |
| `GET`             | `/transactions/:reference` | Statut d'une transaction                           | Synchrone   |
| `GET`             | `/operations/:id`          | Statut d'une opération asynchrone                  | Synchrone   |
| `GET/POST/DELETE` | `/webhooks`                | Gérer les souscriptions webhook                    | Synchrone   |

## Par où commencer

1. Lisez l'[Authentification](/merchant-api-v1/authentication.md) — c'est la marche la plus haute.
2. Gardez 5 minutes pour [Sandbox vs Live](/merchant-api-v1/sandbox-vs-live.md) — c'est ce qui décide si votre requête passe ou pas en production.
3. Suivez le [Quickstart](/merchant-api-v1/quickstart.md) — un appel `curl` signé à `/balance` en moins de 2 minutes.
4. Activez les [Webhooks](/merchant-api-v1/webhooks.md) — c'est comme ça que vous saurez quand un payout, un remboursement ou un paiement aboutit.

{% hint style="info" %}
Une collection Postman prête à l'emploi (avec script de signature automatique) est disponible : `paycfa-webservice/docs/merchant-api.postman_collection.json` + l'environnement sandbox associé.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.intram.org/merchant-api-v1/merchant-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.