# API Live Kratos Pay — Payin et Payout

Ce guide décrit les endpoints Live de création de transactions. Les appels peuvent déplacer de vrais fonds : vérifiez l’environnement, le montant, le numéro et l’opérateur avant chaque envoi.

## Authentification

Envoyez la clé publique Live dans l’en-tête `X-MoK-Public-Key`. Aucune clé secrète ni aucun `applicationId` n’est requis par ces endpoints.

```http
X-MoK-Public-Key: <VOTRE_CLE_PUBLIQUE_LIVE>
Content-Type: application/json
Accept: application/json
```

Base URL : `https://api.kratospay.com`

## Payin — encaissement

**POST** `/api/v1/live/payin`

```json
{
  "amount": 5000,
  "currency": "XAF",
  "phoneNumber": "237690000000",
  "operator": "orange_money_cm",
  "reference": "INV-123456",
  "description": "Paiement facture internet"
}
```

Réponse de succès :

```json
{
  "status": "SUCCESS",
  "reference": "INV-123456",
  "amount": 5000,
  "currency": "XAF",
  "timestamp": "2026-09-10T15:30:00Z",
  "gatewayMessage": "Transaction réussie"
}
```

## Payout — décaissement

**POST** `/api/v1/live/payout`

```json
{
  "amount": 5000,
  "currency": "XAF",
  "phoneNumber": "237690000000",
  "operator": "mtn_momo_cm",
  "reference": "OUT-123456",
  "description": "Paiement fournisseur"
}
```

Réponse de succès (exemple) :

```json
{
  "status": "SUCCESS",
  "reference": "OUT-123456",
  "amount": 5000,
  "currency": "XAF",
  "timestamp": "2026-09-10T15:30:00Z",
  "gatewayMessage": "Transaction réussie"
}
```

## Exemple de réponse d’erreur

Exemple de réponse de validation suivant le format d’erreur de l’API. Les valeurs de `details` et le code HTTP dépendent de l’erreur rencontrée.

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is invalid.",
    "details": {
      "phoneNumber": [
        "The phone number field is required."
      ]
    }
  },
  "meta": {
    "request_id": "example-request-id",
    "timestamp": "2026-09-10T15:30:00Z"
  }
}
```

## Bonnes pratiques

- Envoyez les six champs du payload avec leurs noms exacts et une référence unique par transaction.
- Contrôlez `status` dans le corps de la réponse ; ne déduisez pas la réussite du seul code HTTP.
- En cas d’erreur, exploitez `error.code`, `error.message` et `error.details`. Conservez `meta.request_id` pour le diagnostic.
- Ne relancez pas automatiquement une transaction sans stratégie d’idempotence côté intégration.
- Les exemples de réponse sont des illustrations du contrat et ne garantissent pas une transaction réelle.