Создание ордера H2H

Создает новый ордер в системе и возвращает информацию о нем.

POST /api/v1/order/

Способы указания платежного метода

Существует 2 способа указать платежный метод при создании ордера. Выберите наиболее подходящий для вашего случая:

🎯 Способ 1: По ID платежного метода (рекомендуемый)

Используйте конкретный payment_method_id для точного выбора банка или агрегатного метода.

{
	"client_order_id": "test_order_123",
	"order_side": "Buy",
	"payment_method_id": "2ec6dbd6-49a5-45d0-bd6d-b0134ee4639a", // агрегатный метод СБП
	"amount": "1000",
	"user_id": "test_user123"
}

Когда использовать:
Если нужен конкретный банк / агрегатный метод и у вас уже есть наши ID или вы готовы их использовать. Данный способ позволяет работать с абсолютно всеми платежными методами в системе.

🚀 Способ 2: По типу метода (упрощенный)

Используйте method_type для агрегатных методов без указания конкретного банка. Опционально добавьте nspk_code для указания конкретного банка.

{
	"client_order_id": "test_order_123",
	"order_side": "Buy",
	"method_type": "SBP",
	//"nspk_code": "bank100000000004", // Т-банк
	// Если необходимо создать ордер по конкретному банку, например - выплату по СБП
	"amount": "1000",
	"user_id": "test_user123"
}

Когда использовать:
Для максимальной быстрой интеграции, гибкости в использовании НСПК кодов напрямую (нет необходимости маппить payment_method_id).
На данный момент способ работает только для RUB

Какой способ выбрать?

• Способ 1 - если у вас уже есть маппинг на наши ID методов или вы готовы их использовать
• Способ 2 - для максимально быстрой интеграции, а так же простого подключения выплат СБП (если у вас уже используются НСПК коды)

⚠️ Важно

• Используйте только один из способов в запросе
• Агрегатный метод SBP работает только для приема платежей (Buy)
• Способ 2 с указанием nspk_code поддерживает не все банки (только те, у которых есть НСПК коды)
• Для работы с выплатами (Sell) используйте рекомендации по работе с выплатами

Пример запроса

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": "Buy",
    "payment_method_id": "8fe3669a-a448-4053-bc4b-43bb51cb3e9d",
    "amount": "1000",
    "user_id": "test_user123"
}'

Параметры тела запроса (body)

Параметр	Тип	Описание
client_order_id	string	Уникальный идентификатор ордера в системе клиента. От 1 до 64 символов.
order_side	enum	Buy - клиент создает ордер на прием (пользователь отправляет деньги) Sell - клиент создает ордер на вывод (пользователь принимает деньги).
payment_method_id	enum, nullable	Способ 1: ID платежного метода. См. Получение платежных методов
method_type	enum, nullable	Способ 2: Тип агрегатного метода. См. Типы платежных методов
nspk_code	string, nullable	Способ 2: НСПК код банка (только с method_type)
amount	decimal	Целевая сумма ордера (без учета комиссии сервиса).
customer_name	string, nullable	Имя клиента. Не рекомендуется использовать параметр, если нет реального имени пользователя
customer_account	string, nullable	Счет клиента для выбранного платежного метода в формате Типы платежного метода, для перевода на него средств (Sell) null для ордеров Buy
user_id	string, nullable	Идентификатор пользователя для работы антифрод системы (блокирует массовые заявки от одного пользователя)
webhook_url	url, nullable	URL для вебхука по данному ордеру. Если указан, уведомление отправляется на него вместо URL, настроенных на терминале. Валидный http(s) URL, до 512 символов
unique_amount	bool, nullable	Уникализация суммы. Для повышения конверсии при выдаче реквизитов рекомендуется передавать параметр со значением true. В этом случае будут подобраны реквизиты с суммой в диапазоне от amount до amount + 9, а новая сумма вернётся в ответе в поле amount. Настоятельно рекомендуем использовать этот параметр при запросе реквизитов на «круглые» суммы (например, 1000, 2000 и т.д.).

Тип интеграции order_with_form

При использовании типа интеграции order_with_form после успешного создания ордера система автоматически создаёт платёжную сессию на форме и возвращает ссылку на форму в поле form_url.

Особенности

• Поддерживается только для ордеров Buy
• Ордер уже создан к моменту выдачи ссылки — пользователь открывает форму и сразу видит реквизиты для оплаты
• Если реквизиты не найдены — возвращается стандартная ошибка (аналогичная обычному H2H), сессия не создаётся

⚠️ Важно

Поле form_url — отдельное от payment_link.

Дополнительные параметры запроса (только для order_with_form)

Параметр	Тип	Описание
redirect_url	string, nullable	URL для редиректа пользователя после оплаты
support_url	string, nullable	URL службы поддержки, отображается на форме
return_url	string, nullable	Ссылка «Вернуться на сайт» на странице оплаты, пользователь переходит по ней сам
customer_bank	string, nullable	Идентификатор банка для создания формы с предвыбранным банком пользователя. Возможные значения: sberbank, vtb, tinkoff, alfabank

Пример запроса

{
    "client_order_id": "test_order_123",
    "order_side": "Buy",
    "payment_method_id": "2ec6dbd6-49a5-45d0-bd6d-b0134ee4639a",
    "amount": "1000",
    "user_id": "test_user123",
    "redirect_url": "https://example.com/success",
    "support_url": "https://example.com/support",
    "return_url": "https://example.com/checkout",
	"customer_bank": "sberbank"
}

Пример ответа 201

{
	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"client_order_id": "1234",
	"currency": "RUB",
	"method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"method_name": "Сбербанк",
	"method_type": "BankCard",
	"initial_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"order_side": "Buy",
	"amount": "1000.00",
	"fee": "15.0",
	"fixed_fee": null, // заполняется только при ненулевом значении
	"status": "Completed",
	"holder_name": "Иванов Иван Иванович",
	"holder_account": "4627100000000001",
	"customer_name": "Петров Петр Петрович",
	"customer_account": null,
	"customer_bank": null,
	"payment_link": null,
	"webhook_url": null,
	"form_url": "https://example.com", // только для order_with_form
	"created_at": "2024-07-04T15:40:20.569613Z",
	"updated_at": "2024-07-06T13:27:56.717Z",
	"expires_at": "2024-07-08T15:40:20.569613Z"
}

На основании ответа вы можете сформировать диплинк для перехода к оплате

Описание ошибок

Ошибки клиента:

• 400 Payment method ID or method type is required

  В запросе не указан платежный метод

• 400 Customer account is required

  Для ордера Sell не передан customer_account

• 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

  Реквизит клиента находится в черном списке

• 429 User has reached the maximum limit of pending orders. Please try again later.

  Лимит запросов / блокировка антифродом по user_id

Серверные ошибки:

• 500 No available traders that match order requirements. Please, try again later or change order parameters.

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