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

# Initialisation Paiement Marchand

> Générer un lien de paiement marchand

# Initialisation Paiement Marchand

Générez un lien de paiement pour vos clients. Cette endpoint permet aux marchands de créer des liens de paiement uniques pour leurs produits ou services.

## Endpoint

```bash theme={null}
POST /api/v1/transaction/merchant/get-link
```

## Headers

| Nom           | Type   | Requis | Description           |
| ------------- | ------ | ------ | --------------------- |
| Authorization | string | Oui    | Bearer YOUR\_API\_KEY |
| Content-Type  | string | Oui    | application/json      |

## Corps de la Requête

```json theme={null}
{
  "externalTransactionId": string,    // Votre référence unique
  "ItemName": string,                 // Nom du produit/service
  "ItemPrice": number,                // Prix (min: 100 FCFA)
  "customData": string,               // Données personnalisées (optional)
  "callBackURL": string,              // URL de notification
  "successUrl": string,               // URL de redirection succès
  "failureUrl": string,               // URL de redirection échec
  "ClientName": string,               // Nom du client (optional)
  "ClientPhone": string,              // Téléphone du client (optional)
  "Email": string                     // Email du client (optional)
}
```

### Paramètres

| Paramètre             | Type   | Requis | Description                              |
| --------------------- | ------ | ------ | ---------------------------------------- |
| externalTransactionId | string | Oui    | Votre identifiant unique de transaction  |
| ItemName              | string | Oui    | Nom du produit ou service                |
| ItemPrice             | number | Oui    | Prix en FCFA (minimum: 100)              |
| customData            | string | Non    | Données additionnelles au format JSON    |
| callBackURL           | string | Oui    | URL pour les notifications webhook       |
| successUrl            | string | Oui    | URL de redirection après paiement réussi |
| failureUrl            | string | Oui    | URL de redirection après échec           |
| ClientName            | string | Non    | Nom du client                            |
| ClientPhone           | string | Non    | Numéro de téléphone du client            |
| Email                 | string | Non    | Adresse email du client                  |

## Réponse

### Réponse Réussie (201)

```json theme={null}
{
  "success": true,
  "transactionId": "MID123456789",
  "PaymentUrl": "https://pay.dexchange.sn/process/MID123456789",
  "externalTransactionId": "ORDER-001",
  "Status": "PENDING"
}
```

### Réponse d'Erreur (400)

```json theme={null}
{
  "message": ["Description de l'erreur"],
  "success": false
}
```

## Codes d'Erreur

| Code HTTP | Description                                         |
| --------- | --------------------------------------------------- |
| 400       | Paramètres invalides ou montant minimum non atteint |
| 401       | Clé API invalide                                    |
| 403       | API en maintenance                                  |
| 409       | ID de transaction externe déjà utilisé              |

## Validations

1. **Montant Minimum**

   ```typescript theme={null}
   if (data.ItemPrice < 100) {
     throw new Error('Montant minimum 100 FCFA');
   }
   ```

2. **ID Transaction Unique**
   ```typescript theme={null}
   const isExternalTransactionIdExist =
     await this.isExternalMerchantTransactionIdExist(
       data.externalTransactionId,
       CUID,
     );
   if (isExternalTransactionIdExist) {
     throw new Error('External transaction ID already exists');
   }
   ```

## Exemple de Requête

```bash theme={null}
curl -X POST https://api.dexchange.sn/api/v1/transaction/merchant/get-link \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalTransactionId": "ORDER-001",
    "ItemName": "T-shirt Premium",
    "ItemPrice": 5000,
    "customData": "{}",
    "callBackURL": "https://your-domain.com/callback",
    "successUrl": "https://your-domain.com/success",
    "failureUrl": "https://your-domain.com/failure"
  }'
```

## Webhook de Notification

Lorsque le statut de la transaction change, un webhook est envoyé à l'URL spécifiée dans `callBackURL`:

```json theme={null}
{
  "id": "MID123456789",
  "externalTransactionId": "ORDER-001",
  "transactionType": "PAYMENT",
  "AMOUNT": 5000,
  "FEE": 0,
  "PHONE_NUMBER": "771234567",
  "STATUS": "SUCCESS",
  "CUSTOM_DATA": "{}",
  "COMPLETED_AT": "2024-03-20T10:35:00Z"
}
```

## Notes

1. **Génération du lien**

   * Le lien de paiement est généré automatiquement
   * Format: `https://pay.dexchange.sn/process/{transactionId}`
   * Valide jusqu'au paiement ou expiration

2. **Statuts de Transaction**

   * `PENDING` - En attente de paiement
   * `SUCCESS` - Paiement réussi
   * `FAILED` - Paiement échoué
   * `EXPIRED` - Lien expiré

3. **Sécurité**

   * Vérification de l'API key
   * Validation de l'unicité de l'ID externe
   * Vérification du statut du marchand

4. **Notifications**
   * Webhook pour les mises à jour de statut
   * Email de confirmation au marchand
   * Mise à jour en temps réel via WebSocket