> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alphapay.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Référence API
> Documentation complète de l'API AlphaPay — encaissement, retraits, wallet, webhooks et KYC.
## Base URL
Toutes les requêtes doivent être adressées à :
```
https://api.alphapay.me/api/v1
```
## Authentification
Toutes les routes marchand nécessitent votre clé API secrète, transmise dans le header `Authorization` au format Bearer :
```bash theme={null}
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
```
Utilisez une clé `sk_test_...` en environnement de test, `sk_live_...` en production. Retrouvez vos clés API dans votre [tableau de bord](https://app.alphapay.me), section Développeur.
Votre clé secrète donne accès complet à votre compte marchand (encaissement, retraits, solde). Ne l'exposez jamais côté client (navigateur, application mobile) — utilisez-la uniquement depuis votre backend.
## Format des réponses
Toutes les réponses de l'API partagent la même enveloppe, qu'il s'agisse d'un succès ou d'une erreur.
```json Succès theme={null}
{
"success": true,
"data": { },
"code": 200
}
```
```json Erreur theme={null}
{
"success": false,
"error": {
"message": "Solde disponible insuffisant.",
"code": "insufficient_balance"
},
"code": 422
}
```
Le champ `error` prend deux formes selon le type d'erreur :
* **Erreur métier** (`{"message": "...", "code": "..."}`) — un code d'erreur stable que vous pouvez tester dans votre code, ex. `insufficient_balance`, `merchant_suspended`.
* **Erreur de validation** (`{"champ": ["message"], "autre_champ": ["message"]}`) — une entrée par champ invalide du corps de la requête.
## Codes d'erreur HTTP
| Code | Signification |
| ----- | ------------------------------------------------------------------------------------------------------------------ |
| `400` | Corps de requête invalide (champ manquant, format incorrect) |
| `401` | Clé API manquante, invalide ou expirée |
| `403` | Ressource n'appartenant pas à votre compte, ou compte suspendu |
| `404` | Ressource introuvable |
| `409` | Conflit d'état (ex. `Idempotency-Key` déjà utilisée avec un autre payload, transaction déjà dans un état terminal) |
| `410` | Ressource expirée (ex. lien de paiement ou session de checkout arrivé à expiration) |
| `422` | Requête valide mais impossible à exécuter en l'état (ex. solde insuffisant) |
| `429` | Trop de requêtes — respectez la limite de débit |
## Idempotence
Le header `Idempotency-Key` est **optionnel** : c'est vous qui décidez, requête par requête, si AlphaPay doit dédupliquer.
```bash theme={null}
Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6
```
**Sans le header** — chaque appel est traité comme une intention nouvelle. Deux requêtes identiques créent deux opérations distinctes.
**Avec le header** — une valeur unique que vous générez par intention logique d'opération (un UUID, par exemple) :
| Rejeu | Résultat |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Même clé, **même** corps | La réponse exacte du 1er appel est renvoyée (même code HTTP, même contenu). Rien n'est recréé. |
| Même clé, corps **différent** | `409 Conflict` — la clé est déjà associée à une autre requête. |
| Même clé, 1er appel encore en cours | `409 Conflict` — évite deux exécutions concurrentes. |
Optionnel ne veut pas dire facultatif en pratique. Sur les endpoints qui **déplacent de l'argent** — `POST /payments/softpay/initialize/`, `POST /payouts/initialize/`, `POST /settlements/`, `POST /wallet-transfers/`, `POST /payments/{id}/retry/` — un retry réseau sans clé crée un **second débit réel**. Envoyez-la systématiquement sur ces routes.
Générez une nouvelle `Idempotency-Key` à chaque nouvelle intention de paiement, mais réutilisez la même clé pour chaque *retry réseau* de cette même tentative. Un timeout ou une coupure réseau n'est jamais la preuve que la requête a échoué : elle a pu aboutir côté serveur.
## Limite de débit
Les appels authentifiés (clé API ou dashboard) sont limités à **300 requêtes par minute** par compte par défaut. Un dépassement renvoie `429 Too Many Requests`. Espacez vos appels ou mettez en cache les réponses peu volatiles (ex. liste des pays/réseaux supportés).
## Ressources
Encaissez via checkout hébergé ou softpay
Créez des liens de paiement réutilisables
Payez un bénéficiaire en mobile money
Consultez vos soldes et les taux de change
Recevez vos événements en temps réel
Inscription, KYC, première clé API