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

Name	Type	Required	Description
Authorization	string	Yes	Bearer YOUR_API_KEY
Content-Type	string	Yes	application/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

Parameter	Type	Required	Description
externalTransactionId	string	Yes	Your unique transaction identifier
ItemName	string	Yes	Product or service name
ItemPrice	number	Yes	Price in FCFA (minimum: 100)
customData	string	No	Additional data in JSON format
callBackURL	string	Yes	URL for webhook notifications
successUrl	string	Yes	Redirect URL after successful payment
failureUrl	string	Yes	Redirect URL after failure
ClientName	string	No	Customer name
ClientPhone	string	No	Customer phone number
Email	string	No	Customer 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 Code	Description
400	Invalid parameters or minimum amount not met
401	Invalid API key
403	API under maintenance
409	External transaction ID already used

Validations

Minimum Amount

if (data.ItemPrice < 100) {
  throw new Error('Minimum amount 100 FCFA');
}

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

Link Generation
- Payment link is generated automatically
- Format: https://pay.dexchange.sn/process/{transactionId}
- Valid until payment or expiration
Transaction Statuses
- PENDING - Awaiting payment
- SUCCESS - Payment successful
- FAILED - Payment failed
- EXPIRED - Link expired
Security
- API key verification
- External ID uniqueness validation
- Merchant status verification
Notifications
- Webhook for status updates
- Merchant confirmation email
- Real-time updates via WebSocket

API Reference

Services List

DIRECT API

Bills & Top-ups

Merchant Payments

Sub-Merchants

Webhooks

Initialize Merchant Payment

Initialize Merchant Payment

Endpoint

Headers

Request Body

Parameters

Response

Successful Response (201)

Error Response (400)

Error Codes

Validations

Request Example

Webhook Notification

Notes

​Initialize Merchant Payment

​Endpoint

​Headers

​Request Body

​Parameters

​Response

​Successful Response (201)

​Error Response (400)

​Error Codes

​Validations

​Request Example

​Webhook Notification

​Notes

Initialize Merchant Payment

Endpoint

Headers

Request Body

Parameters

Response

Successful Response (201)

Error Response (400)

Error Codes

Validations

Request Example

Webhook Notification

Notes