Skip to main content

​
Initialize Merchant Payment

Generate a payment link for your customers. This endpoint allows merchants to create unique payment links for their products or services.

​
Endpoint

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

​
Headers

NameTypeRequiredDescription
AuthorizationstringYesBearer YOUR_API_KEY
Content-TypestringYesapplication/json

​
Request Body

{
  "externalTransactionId": string,    // Your unique reference
  "ItemName": string,                 // Product/service name
  "ItemPrice": number,                // Price (min: 100 FCFA)
  "customData": string,               // Custom data (optional)
  "callBackURL": string,              // Notification URL
  "successUrl": string,               // Success redirect URL
  "failureUrl": string,               // Failure redirect URL
  "ClientName": string,               // Customer name (optional)
  "ClientPhone": string,              // Customer phone (optional)
  "Email": string                     // Customer email (optional)
}

​
Parameters

ParameterTypeRequiredDescription
externalTransactionIdstringYesYour unique transaction identifier
ItemNamestringYesProduct or service name
ItemPricenumberYesPrice in FCFA (minimum: 100)
customDatastringNoAdditional data in JSON format
callBackURLstringYesURL for webhook notifications
successUrlstringYesRedirect URL after successful payment
failureUrlstringYesRedirect URL after failure
ClientNamestringNoCustomer name
ClientPhonestringNoCustomer phone number
EmailstringNoCustomer email address

​
Response

​
Successful Response (201)

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

​
Error Response (400)

{
  "message": ["Error description"],
  "success": false
}

​
Error Codes

HTTP CodeDescription
400Invalid parameters or minimum amount not met
401Invalid API key
403API under maintenance
409External transaction ID already used

​
Validations

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

​
Request Example

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": "Premium T-shirt",
    "ItemPrice": 5000,
    "customData": "{}",
    "callBackURL": "https://your-domain.com/callback",
    "successUrl": "https://your-domain.com/success",
    "failureUrl": "https://your-domain.com/failure"
  }'

​
Webhook Notification

When the transaction status changes, a webhook is sent to the URL specified in 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. Link Generation
    • Payment link is generated automatically
    • Format: https://pay.dexchange.sn/process/{transactionId}
    • Valid until payment or expiration
  2. Transaction Statuses
    • PENDING - Awaiting payment
    • SUCCESS - Payment successful
    • FAILED - Payment failed
    • EXPIRED - Link expired
  3. Security
    • API key verification
    • External ID uniqueness validation
    • Merchant status verification
  4. Notifications
    • Webhook for status updates
    • Merchant confirmation email
    • Real-time updates via WebSocket