Type DL
How to create mobile money payouts with type DL
Type DL payouts allow you to send funds from your merchant account to mobile money wallets of West and Central African telecom operators — MTN, Orange, Wave, Moov, Free Money and others. The primary destinations are Ivory Coast and Senegal.
Before you start
How to authorize your requests
This integration is not available to all merchants. Check the availability and the list of enabled destinations with your account manager.
Before making requests, ensure your merchant account has sufficient funds to create a payout.
Choosing a destination (serviceId)
Each country + operator pair is a separate payout service. The list of services available to you is returned by:
GET /v1/payouts/servicesPass the serviceId of the target destination when creating a payout. When the
payout is created without serviceId, the default service is used — make sure
it is the DL destination you intend to pay to.
The recipient's phone number must belong to the operator of the selected destination: for example, a Wave (Senegal) wallet cannot be topped up through an Orange (Ivory Coast) service.
Creating a Payout
Send a POST request to create a new payout:
POST /v1/payoutsRequest Example
curl -X POST "https://api.panel.valutix.kz/v1/payouts" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": 10000,
"currency": "XOF",
"paymentType": "SIM",
"serviceId": 123,
"account": {
"name": "John Doe",
"requisites": "2250700000001",
"userId": "user_12345",
"userEmail": "john.doe@example.com"
},
"note": "Payout for order #1234"
}'Request Parameters
Main Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| amount | number | ✅ Yes | Payout amount |
| currency | string | ✅ Yes | Currency code |
| paymentType | string | ✅ Yes | Payment type — SIM |
| serviceId | number | ❌ No | Destination service ID from GET /v1/payouts/services; when omitted, the default service is used |
| account | object | ✅ Yes | Recipient details |
| note | string | ❌ No | Payout note |
| externalId | string | ❌ No | Payout ID in your system |
| callbackUrl | string | ❌ No | Webhook URL for this payout |
Account Object
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | ✅ Yes | Recipient full name |
| requisites | string | ✅ Yes | Wallet phone number in international format, digits only, no +: country code followed by the number (Ivory Coast — 2250700000001, Senegal — 221700000001) |
| userId | string | ✅ Yes | User ID in your system |
| userEmail | string | ❌ No | Recipient email — recommended to always pass; required for some destinations |
| userIp | string | ❌ No | User IP |
Supported Currencies
| Value | Description |
|---|---|
| XOF | CFA franc BCEAO — Ivory Coast, Senegal |
| Other | CDF, GHS, KES, NGN, ZAR, UGX, TZS, ZMW, BDT — subject to agreement with your manager |
Amount requirements: XOF — whole amounts in multiples of 5; TZS, KES,
GHS, UGX — whole amounts only, no decimals.
Payment Types
| Value | Description |
|---|---|
| SIM | Transfer to a mobile wallet by phone number |
Successful Response Example
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"merchantId": "123e4567-e89b-12d3-a456-426614174000",
"amount": "10000",
"account": {
"name": "John Doe",
"requisites": "2250700000001",
"userId": "user_12345",
"userEmail": "john.doe@example.com"
},
"status": "CREATED",
"type": "SIM",
"requisites": {},
"statusMessage": null,
"metadata": null,
"callbackUrl": null,
"createdAt": "2026-08-28T12:34:56Z",
"updatedAt": "2026-08-28T12:34:56Z",
"completedAt": null
}Response Fields
| Field | Type | Description |
|---|---|---|
| id | string | Payout UUID |
| merchantId | string | Your merchant UUID |
| amount | string | Payout amount |
| account | object | Recipient details |
| status | string | Current payout status |
| type | string | Payment type |
| requisites | object | Additional requisites |
| statusMessage | string / null | Status message (if any) |
| metadata | object / null | Additional metadata |
| callbackUrl | string / null | Webhook URL for this payout (null — merchant settings are used) |
| createdAt | string | Creation time |
| updatedAt | string | Last update time |
| completedAt | string / null | Completion time |
Payout Statuses
| Status | Description |
|---|---|
| CREATED | Payout has been created |
| PROCESSING | Payout is being processed |
| COMPLETED | Payout completed successfully |
| FAILED | Payout failed |
| CANCELED | Payout has been canceled |
| EXPIRED | Payout has expired |
The final status usually arrives within a few minutes after the payout is created.
Checking Payout Status
To get the current payout status, send a GET request:
GET /v1/payouts/{payoutId}Request Example
curl -X GET "https://api.panel.valutix.kz/v1/payouts/123e4567-e89b-12d3-a456-426614174000" \
-H "X-Api-Token: YOUR_API_TOKEN"Payout status change notifications are also delivered via webhooks: pass
callbackUrl in the request body or set it in your merchant settings.
Polling the status by ID can be used as a fallback (for example, every 30
minutes).
Payout webhooks
Recommendations
- Always check your merchant balance before creating payouts - Pass the
serviceIdof the target destination and make sure the phone number belongs to the operator of that destination - Send the phone number in international format without+- Save the payoutidfrom the response to track the status - Use webhook notifications (callbackUrl) and verify theX-Signatureheader; polling by ID is a fallback - Handle every possible status value in your integration