> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sahelpay.ml/llms.txt
> Use this file to discover all available pages before exploring further.

# Créer un paiement sécurisé

> Créer une commande dont le paiement reste bloqué jusqu'à la livraison

# Créer un paiement sécurisé

<Warning>
  Pilote sur activation : `404 SECURE_ORDERS_DISABLED` si le service n'est pas ouvert pour votre compte.
  Voir le [guide](/guides/secure-orders).
</Warning>

## Endpoint

```
POST /v1/secure-orders
```

## Headers

| Header | Requis | Description |
| - | - | - |
| `Authorization` | ✅ | `Bearer sk_xxx` |
| `X-Idempotency-Key` | Recommandé | Rejeu sûr de la création |

## Body

| Paramètre | Type | Requis | Description |
| - | - | - | - |
| `amount` | integer | ✅ | Montant en XOF (100 à 10 000 000) |
| `description` | string | ✅ | Description visible par l'acheteur (2 à 200 caractères) |
| `customer_phone` | string | ✅ | Téléphone de l'acheteur, 8 à 15 chiffres, `+` initial optionnel |
| `customer_name` | string | | Nom de l'acheteur (100 caractères max) |
| `delivery_deadline_hours` | integer | | Délai de livraison après paiement, 1 à 720 (défaut 72) |
| `client_reference` | string | | Votre référence de commande (64 caractères max) |

## Exemple

```bash theme={null}
curl -X POST https://api.sahelpay.ml/v1/secure-orders \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-778" \
  -d '{
    "amount": 15000,
    "description": "Robe wax taille M",
    "customer_phone": "+22370000000",
    "delivery_deadline_hours": 48,
    "client_reference": "order-778"
  }'
```

## Réponse

`201 Created`, `data` = objet paiement sécurisé :

```json theme={null}
{
  "success": true,
  "data": {
    "id": "5f0c2c55-...",
    "reference": "...",
    "status": "CREATED",
    "is_test": true,
    "amount": 15000,
    "currency": "XOF",
    "amount_charged": 15000,
    "fee_total": 0,
    "amount_merchant_net": null,
    "description": "Robe wax taille M",
    "customer_phone": "+22370000000",
    "client_reference": "order-778",
    "payment_intent_id": null,
    "payment_status": null,
    "buyer_url": "https://app.sahelpay.ml/securise/<token>",
    "delivery_url": "https://app.sahelpay.ml/livraison/<token>",
    "delivery_window_hours": 48,
    "pay_before": "2026-10-10T10:00:00.000Z",
    "delivery_deadline": null,
    "code_attempts_remaining": 5,
    "code_locked": false,
    "created_at": "2026-10-03T10:00:00.000Z"
  }
}
```

* Envoyez `buyer_url` à l'acheteur : il y paie et retrouve son code après paiement.
* Envoyez `delivery_url` au livreur : il y saisit le code de l'acheteur.

## Erreurs

| HTTP | Code | Cause |
| - | - | - |
| `400` | — | Champ invalide |
| `404` | `SECURE_ORDERS_DISABLED` | Service non activé pour votre compte |
| `409` | `IDEMPOTENCY_CONFLICT` | Clé déjà utilisée pour une autre commande (montant, téléphone ou description différents) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.