## Requête

Les « factures » de l’API correspondent aux **commandes** (`Order`) accessibles par leur **UUID** public.

```http
POST /v1/invoices/{order_uuid}/pay
Authorization: Bearer kh_live_xxxx
Content-Type: application/json
```

### Paramètres de chemin

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `order_uuid` | UUID | Oui | UUID de la commande / facture |

### Corps de la requête

```json
{
  "payment_method": "notchpay",
  "phone_number": "677123456",
  "callback_url": "https://votre-app.example/callback-paiement"
}
```

| Champ | Type | Requis | Description |
|-------|------|--------|-------------|
| `payment_method` | string | Non | `notchpay`, `mobile_money` ou `card` |
| `phone_number` | string | Non | Indicatif / numéro pour Mobile Money si applicable |
| `callback_url` | URL | Non | URL de retour ; défaut : page commande côté client KennHosting |

## Réponse (200 OK)

```json
{
  "success": true,
  "data": {
    "payment_id": "KHNP-API-KH-XXXXXXXXXX-1710000000",
    "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
    "amount_fcfa": 10009,
    "currency": "XAF",
    "method": "notchpay",
    "status": "pending",
    "checkout_url": "https://…",
    "expires_at": "2024-06-15T10:45:00+00:00"
  }
}
```

| Champ | Description |
|-------|-------------|
| `payment_id` | **Référence** du paiement (`OrderPayment.reference`), à conserver pour le suivi |
| `invoice_id` | UUID de la commande |
| `checkout_url` | Lien de paiement NotchPay |
| `expires_at` | Date/heure limite indicative (15 minutes) |

## Statut d’un paiement

```http
GET /v1/payments/{reference}
Authorization: Bearer kh_live_xxxx
```

`{reference}` est la valeur `payment_id` renvoyée par `POST …/pay`. Vous pouvez aussi passer l’**identifiant numérique** interne du paiement si vous le connaissez.

**Permission :** `invoices:read`

### Réponse

```json
{
  "success": true,
  "data": {
    "reference": "KHNP-API-KH-XXXXXXXXXX-1710000000",
    "id": 42,
    "status": "pending",
    "amount": 10009,
    "currency": "XAF",
    "provider": "notchpay",
    "order": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "order_number": "KH-XXXXXXXXXX"
    },
    "paid_at": null,
    "created_at": "2024-06-15T10:30:00+00:00"
  }
}
```

Les statuts possibles pour `status` dépendent du fournisseur (ex. `pending`, `paid`, etc.).

<Note>
  Le champ `provider` de `GET /v1/payments/{reference}` dépend du moyen réellement utilisé
  (`notchpay`, `cinetpay`, etc.). Ne supposez pas une valeur unique côté intégration.
</Note>

## Webhooks

Les événements sortants documentés côté compte (ex. `payment.completed`, `payment.failed`) restent la source fiable pour l’automatisation. Configurez-les dans l’espace client → API → Webhooks.

## Permissions requises

- `POST …/invoices/{uuid}/pay` : `invoices:pay`
- `GET …/payments/{reference}` : `invoices:read`

<Warning>
  Les clés **sandbox** (`kh_test_`) ne permettent pas d’initier un paiement : toute écriture renvoie `403` avec `sandbox_read_only`.
</Warning>