Тип DL
Как создавать выплаты на мобильные кошельки через тип DL
Выплаты типа DL позволяют отправлять средства с вашего мерчант-счёта на мобильные кошельки (mobile money) телеком-операторов Западной и Центральной Африки — MTN, Orange, Wave, Moov, Free Money и других. Основные направления — Кот-д’Ивуар и Сенегал.
Перед тем как начать
Как авторизовывать запросы
Эта интеграция доступна не всем мерчантам. Уточните доступность и список подключённых направлений у вашего менеджера.
Перед запросами убедитесь, что на вашем мерчант-счёте достаточно средств для выплаты.
Выбор направления (serviceId)
Каждая пара «страна + оператор» — это отдельный сервис выплат. Список доступных вам сервисов возвращает запрос:
GET /v1/payouts/servicesПередавайте serviceId нужного направления при создании выплаты. Если выплата
создаётся без serviceId, используется сервис по умолчанию — убедитесь, что это
именно нужное DL-направление.
Номер телефона получателя должен принадлежать оператору выбранного направления: например, кошелёк Wave (Сенегал) нельзя пополнить через сервис Orange (Кот-д’Ивуар).
Создание выплаты
Отправьте POST-запрос для создания новой выплаты:
POST /v1/payoutsПример запроса
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": "Выплата по заказу №1234"
}'Параметры запроса
Основные параметры
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| amount | number | ✅ Да | Сумма выплаты |
| currency | string | ✅ Да | Код валюты |
| paymentType | string | ✅ Да | Тип платежа — SIM |
| serviceId | number | ❌ Нет | ID сервиса направления из GET /v1/payouts/services; без него используется сервис по умолчанию |
| account | object | ✅ Да | Реквизиты получателя |
| note | string | ❌ Нет | Заметка к выплате |
| externalId | string | ❌ Нет | Идентификатор выплаты в вашей системе |
| callbackUrl | string | ❌ Нет | Адрес webhook-уведомлений по выплате |
Объект account
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| name | string | ✅ Да | Полное имя получателя |
| requisites | string | ✅ Да | Номер телефона кошелька в международном формате, только цифры, без +: код страны и номер (Кот-д’Ивуар — 2250700000001, Сенегал — 221700000001) |
| userId | string | ✅ Да | ID пользователя в вашей системе |
| userEmail | string | ❌ Нет | Email получателя — рекомендуется передавать всегда; для части направлений обязателен |
| userIp | string | ❌ Нет | IP пользователя |
Поддерживаемые валюты
| Значение | Описание |
|---|---|
| XOF | Франк КФА BCEAO — Кот-д’Ивуар, Сенегал |
| Другие | CDF, GHS, KES, NGN, ZAR, UGX, TZS, ZMW, BDT — по согласованию с менеджером |
Требования к суммам: XOF — целые суммы, кратные 5; TZS, KES, GHS,
UGX — только целые суммы, без копеек.
Типы платежей
| Значение | Описание |
|---|---|
| SIM | Перевод на мобильный кошелёк по номеру телефона |
Пример успешного ответа
{
"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
}Поля ответа
| Поле | Тип | Описание |
|---|---|---|
| id | string | UUID выплаты |
| merchantId | string | UUID вашего мерчанта |
| amount | string | Сумма выплаты |
| account | object | Реквизиты получателя |
| status | string | Текущий статус выплаты |
| type | string | Тип платежа |
| requisites | object | Дополнительные реквизиты |
| statusMessage | string / null | Сообщение статуса (если есть) |
| metadata | object / null | Дополнительные метаданные |
| callbackUrl | string / null | Адрес webhook-уведомлений для этой выплаты (null — настройки мерчанта) |
| createdAt | string | Время создания |
| updatedAt | string | Время последнего обновления |
| completedAt | string / null | Время завершения |
Статусы выплат
| Статус | Описание |
|---|---|
| CREATED | Выплата создана |
| PROCESSING | Выплата обрабатывается |
| COMPLETED | Выплата успешно завершена |
| FAILED | Ошибка выплаты |
| CANCELED | Выплата отменена |
| EXPIRED | Срок действия выплаты истёк |
Финальный статус обычно приходит в течение нескольких минут после создания выплаты.
Проверка статуса выплаты
Чтобы узнать текущий статус выплаты, отправьте GET-запрос:
GET /v1/payouts/{payoutId}Пример запроса
curl -X GET "https://api.panel.valutix.kz/v1/payouts/123e4567-e89b-12d3-a456-426614174000" \
-H "X-Api-Token: YOUR_API_TOKEN"Уведомления об изменении статуса выплаты также доставляются через
webhook'и: передайте callbackUrl в теле запроса или укажите его в
настройках мерчанта. Опрос статуса по ID может использоваться как резервный
способ (например, каждые 30 минут).
Webhook'и по выплатам
Рекомендации
- Всегда проверяйте баланс мерчанта перед созданием выплат - Передавайте
serviceIdнужного направления и следите, чтобы номер телефона принадлежал оператору этого направления - Передавайте номер телефона в международном формате без+- Сохраняйтеidвыплаты из ответа для отслеживания статуса - Используйте webhook-уведомления (callbackUrl) и проверяйте подписьX-Signature; опрос статуса по ID — резервный способ - Обрабатывайте все возможные значения статусов в своей интеграции