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

# Initialize Merchant Payment

> Generate a merchant payment link

# 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

```bash theme={null}
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

```json theme={null}
{
  "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)

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

### Error Response (400)

```json theme={null}
{
  "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

1. **Minimum Amount**

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

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

## Request Example

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

```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. **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