Skip to content

Создание ордера 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_idstringУникальный идентификатор ордера в системе клиента. От 1 до 64 символов.
order_sideenumВсегда Sell - клиент создает ордер на вывод (пользователь принимает деньги). Для приема см. Создание ордера Buy (H2H)
payment_method_idenum, nullableСпособ 1: ID платежного метода. См. Получение платежных методов
method_typeenum, nullableСпособ 2: Тип агрегатного метода. См. Типы платежных методов
nspk_codestring, nullableСпособ 2: НСПК код банка (только с method_type)
amountdecimalЦелевая сумма ордера (без учета комиссии сервиса).
customer_accountstring, nullableСчет клиента для выбранного платежного метода в формате Типы платежного метода, на который переводятся средства. Обязательный для всех методов, кроме NSPKLink
payment_linkstring, nullableСсылка на оплату для метода NSPKLink (QR РФ). Обязательна для NSPKLink, customer_account при этом не нужен. Формат — только https://qr.nspk.ru/..., до 512 символов. В Buy ордерах поле игнорируется
customer_namestring, nullableИмя клиента. Не рекомендуется использовать параметр, если нет реального имени пользователя
user_idstring, nullableИдентификатор пользователя для работы антифрод системы (блокирует массовые заявки от одного пользователя)
webhook_urlurl, nullableURL для вебхука по данному ордеру. Если указан, уведомление отправляется на него вместо URL, настроенных на терминале. Валидный http(s) URL, до 512 символов
request_metadataobject, 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.

    Нет доступных реквизитов на указанные параметры ордера, попробуйте другие суммы / платежные методы или обратитесь к администратору за информацией о конверсии на выдачу