Skip to main content

​
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

POST /api/v1/transaction/merchant/get-link

​
Headers

NomTypeRequisDescription
AuthorizationstringOuiBearer YOUR_API_KEY
Content-TypestringOuiapplication/json

​
Corps de la Requête

{
  "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ètreTypeRequisDescription
externalTransactionIdstringOuiVotre identifiant unique de transaction
ItemNamestringOuiNom du produit ou service
ItemPricenumberOuiPrix en FCFA (minimum: 100)
customDatastringNonDonnées additionnelles au format JSON
callBackURLstringOuiURL pour les notifications webhook
successUrlstringOuiURL de redirection après paiement réussi
failureUrlstringOuiURL de redirection après échec
ClientNamestringNonNom du client
ClientPhonestringNonNuméro de téléphone du client
EmailstringNonAdresse email du client

​
Réponse

​
Réponse Réussie (201)

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

​
Réponse d’Erreur (400)

{
  "message": ["Description de l'erreur"],
  "success": false
}

​
Codes d’Erreur

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

​
Validations

  1. Montant Minimum 
    if (data.ItemPrice < 100) {
  throw new Error('Montant minimum 100 FCFA');
}
  2. ID Transaction Unique 
    const isExternalTransactionIdExist =
  await this.isExternalMerchantTransactionIdExist(
    data.externalTransactionId,
    CUID,
  );
if (isExternalTransactionIdExist) {
  throw new Error('External transaction ID already exists');
}

​
Exemple de Requête

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: 
{
  "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