Создание ордера Sell (H2H)
Создает новый ордер на вывод (пользователь принимает деньги) и возвращает информацию о нем.
http
POST /api/v1/order/Рекомендации
Перед интеграцией выплат ознакомьтесь с рекомендациями по работе с выплатами.
Способы указания платежного метода
Существует 2 способа указать платежный метод при создании ордера. Выберите наиболее подходящий для вашего случая:
🎯 Способ 1: По ID платежного метода (рекомендуемый)
Используйте конкретный payment_method_id для точного выбора банка.
json
{
"client_order_id": "test_order_123",
"order_side": "Sell",
"payment_method_id": "2875d43f-b80e-46e1-a3f6-bb82912ccf3d", // СБП Сбербанк
"amount": "1000",
"customer_account": "79001234567",
"user_id": "test_user123"
}Когда использовать:
Если нужен конкретный банк и у вас уже есть наши ID или вы готовы их использовать. Данный способ позволяет работать с абсолютно всеми платежными методами в системе.
🚀 Способ 2: По типу метода (упрощенный)
Используйте method_type вместе с nspk_code для указания банка получателя.
json
{
"client_order_id": "test_order_123",
"order_side": "Sell",
"method_type": "SBP",
"nspk_code": "bank100000000111", // Сбербанк
"amount": "1000",
"customer_account": "79001234567",
"user_id": "test_user123"
}Когда использовать:
Для максимальной быстрой интеграции и простого подключения выплат СБП, если у вас уже используются НСПК коды (нет необходимости маппить payment_method_id).
На данный момент способ работает только для RUB
Какой способ выбрать?
- Способ 1 - если у вас уже есть маппинг на наши ID методов или вы готовы их использовать
- Способ 2 - для максимально быстрой интеграции и простого подключения выплат СБП (если у вас уже используются НСПК коды)
⚠️ Важно
- Используйте только один из способов в запросе
- Агрегатный метод SBP не работает для выплат: используйте инхаус-банк через конкретный
payment_method_idили добавьтеnspk_codeк запросу. См. Типы платежных методов - Способ 2 с указанием
nspk_codeподдерживает не все банки (только те, у которых есть НСПК коды)
Пример запроса
INFO
Выберите валюту и платежный метод, чтобы увидеть пример запроса и ответа. Актуальные payment_method_id для вашего терминала можно получить в разделе Получение платежных методов.
Реквизит получателя передается в customer_account: номер карты, номер телефона или номер счета (IBAN, CBU/CVU) — в зависимости от метода. Исключение — метод NSPKLink (QR РФ): для него вместо customer_account передается ссылка на оплату в payment_link.
bash
curl -X POST 'https://api.luckypay.pro/api/v1/order/' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: your_api_key' \
-d '{
"client_order_id": "test_order_123",
"order_side": "Sell",
"payment_method_id": "8fe3669a-a448-4053-bc4b-43bb51cb3e9d",
"amount": "1000",
"customer_account": "4627100000000002",
"user_id": "test_user123"
}'Параметры тела запроса (body)
| Параметр | Тип | Описание |
|---|---|---|
| client_order_id | string | Уникальный идентификатор ордера в системе клиента. От 1 до 64 символов. |
| order_side | enum | Всегда Sell - клиент создает ордер на вывод (пользователь принимает деньги). Для приема см. Создание ордера Buy (H2H) |
| payment_method_id | enum, nullable | Способ 1: ID платежного метода. См. Получение платежных методов |
| method_type | enum, nullable | Способ 2: Тип агрегатного метода. См. Типы платежных методов |
| nspk_code | string, nullable | Способ 2: НСПК код банка (только с method_type) |
| amount | decimal | Целевая сумма ордера (без учета комиссии сервиса). |
| customer_account | string, nullable | Счет клиента для выбранного платежного метода в формате Типы платежного метода, на который переводятся средства. Обязательный для всех методов, кроме NSPKLink |
| payment_link | string, nullable | Ссылка на оплату для метода NSPKLink (QR РФ). Обязательна для NSPKLink, customer_account при этом не нужен. Формат — только https://qr.nspk.ru/..., до 512 символов. В Buy ордерах поле игнорируется |
| customer_name | string, nullable | Имя клиента. Не рекомендуется использовать параметр, если нет реального имени пользователя |
| user_id | string, nullable | Идентификатор пользователя для работы антифрод системы (блокирует массовые заявки от одного пользователя) |
| webhook_url | url, nullable | URL для вебхука по данному ордеру. Если указан, уведомление отправляется на него вместо URL, настроенных на терминале. Валидный http(s) URL, до 512 символов |
| request_metadata | object, nullable | Дополнительные параметры ордера для отдельных валют и методов. Для TRY (IBAN) обязателен order_metadata.tcid — идентификационный номер получателя (TC Kimlik No). В ответе не возвращается |
Пример ответа 201
json
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"client_order_id": "test_order_123",
"currency": "RUB",
"method_id": "8fe3669a-a448-4053-bc4b-43bb51cb3e9d",
"method_name": "Любой банк РФ",
"method_type": "BankCard",
"initial_method_id": "8fe3669a-a448-4053-bc4b-43bb51cb3e9d",
"order_side": "Sell",
"amount": "1000.00",
"fee": "15.0",
"fixed_fee": null,
"status": "Completed",
"holder_name": null,
"holder_account": null,
"customer_name": "John Doe",
"customer_account": "4627100000000002",
"customer_bank": null,
"receipt_email": null,
"payment_link": null,
"webhook_url": null,
"created_at": "2024-07-04T15:40:20.569613Z",
"updated_at": "2024-07-06T13:27:56.717Z",
"expires_at": "2024-07-08T15:40:20.569613Z"
}fixed_fee заполняется только при ненулевом значении.
Описание ошибок
Ошибки клиента:
400
Customer account is requiredНе передан
customer_account(для всех методов, кромеNSPKLink)402
Insufficient funds. The order amount exceeds the available balance. Please deposit more funds and try again.Недостаточный баланс для Sell ордера
404
Payment method not foundУказан несуществующий платежный метод, для просмотра списка доступных методов можно воспользоваться Получение платежных методов
409
Expectation Failed. Amount for the chosen payment method doesn't meet limits. Check payment method limits and try again.Сумма ордера вне лимитов выбранного платежного метода
409
Customer account is blacklistedРеквизит клиента находится в черном списке
422
Sell orders must specify a specific bank and cannot use aggregation methods. Use payment_method_id or nspk_code + method_type.Для Sell ордера указан агрегатный метод
SBP. Укажите конкретный банк черезpayment_method_idилиnspk_code+method_type, см. способы указания платежного метода
Серверные ошибки:
500
No available traders that match order requirements. Please, try again later or change order parameters.Нет доступных реквизитов на указанные параметры ордера, попробуйте другие суммы / платежные методы или обратитесь к администратору за информацией о конверсии на выдачу