> ## 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

> Créer une intention de paiement

# Créer un paiement

Crée une nouvelle intention de paiement et retourne une URL de redirection vers le checkout.

## Endpoint

```
POST /v1/payments
```

## Headers

| Header              | Requis     | Description                         |
| ------------------- | ---------- | ----------------------------------- |
| `Authorization`     | ✅          | `Bearer sk_xxx`                     |
| `Content-Type`      | ✅          | `application/json`                  |
| `X-Idempotency-Key` | Recommandé | Clé unique pour éviter les doublons |

## Body

| Paramètre          | Type    | Requis      | Description                                                               |
| ------------------ | ------- | ----------- | ------------------------------------------------------------------------- |
| `amount`           | integer | ✅           | Montant en FCFA (min: 100)                                                |
| `currency`         | string  |             | Devise (défaut: `XOF`)                                                    |
| `payment_method`   | string  | ✅           | `ORANGE_MONEY`, `WAVE`, `MOOV`, `CARD`, `VISA`, `MASTERCARD`, `GIM_UEMOA` |
| `country`          | string  |             | Code pays: `ML`, `SN`, `CI`                                               |
| `customer_phone`   | string  | ✅           | Numéro de téléphone (+223...)                                             |
| `customer_name`    | string  | ✅ pour CARD | Nom du client (requis pour cartes)                                        |
| `customer_email`   | string  | ✅ pour CARD | Email du client (requis pour cartes)                                      |
| `return_url`       | string  | ✅           | URL de retour après paiement                                              |
| `client_reference` | string  |             | Votre référence (order\_id)                                               |
| `metadata`         | object  |             | Données personnalisées                                                    |

## Exemple

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.sahelpay.ml/v1/payments \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -H "X-Idempotency-Key: order-123" \
    -d '{
      "amount": 5000,
      "currency": "XOF",
      "payment_method": "ORANGE_MONEY",
      "country": "ML",
      "customer_phone": "+22370123456",
      "customer_name": "Amadou Diallo",
      "return_url": "https://votre-site.com/checkout/return",
      "client_reference": "order_123",
      "metadata": {
        "order_id": "order_123"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.sahelpay.ml/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json',
      'X-Idempotency-Key': 'order-123',
    },
    body: JSON.stringify({
      amount: 5000,
      currency: 'XOF',
      payment_method: 'ORANGE_MONEY',
      country: 'ML',
      customer_phone: '+22370123456',
      customer_name: 'Amadou Diallo',
      return_url: 'https://votre-site.com/checkout/return',
      client_reference: 'order_123',
    }),
  });
  ```
</CodeGroup>

## Réponse

```json theme={null}
{
  "success": true,
  "data": {
    "id": "txn_abc123def456",
    "status": "PENDING",
    "amount": 5000,
    "currency": "XOF",
    "payment_method": "ORANGE_MONEY",
    "redirect_url": "https://pay.sahelpay.ml/checkout/txn_abc123def456",
    "gateway_used": "internal_gateway_id",
    "routing_reason": "Routing optimisé pour coût et disponibilité",
    "expires_at": "2025-12-18T17:00:00.000Z",
    "created_at": "2025-12-18T16:45:00.000Z"
  }
}
```

### Champs de routing

| Champ            | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `gateway_used`   | Identifiant technique interne (pour monitoring uniquement) |
| `routing_reason` | Explication du routing choisi par SahelPay                 |

<Note>
  Ces champs sont **informatifs**. SahelPay choisit automatiquement le meilleur gateway selon le coût et la disponibilité. Voir le [guide Smart Routing](/guides/smart-routing) pour plus de détails.
</Note>

```

## Erreurs

| Code | Description |
|------|-------------|
| `INVALID_AMOUNT` | Montant invalide (< 100 ou > 5M) |
| `MISSING_PHONE` | Numéro de téléphone requis |
| `MISSING_RETURN_URL` | URL de retour requise |
| `DUPLICATE_PAYMENT` | Paiement déjà créé (idempotence) |
```