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

Создает форму для оплаты и возвращает ссылку.

POST /api/v1/form/create

Создание формы

При получении формы пользователь переходит на платежную форму, где выбирает метод оплаты.

На форме отображаются кнопки с выбором метода оплаты, пользователю предоставлена возможность выбрать способ оплаты самостоятельно.

Передача button_name (предвыбор кнопки)

Если нужно указать банк пользователя, необходимо передать параметр button_name. В таком случае этап с выбором метода и банка пропускается, кнопка предвыбрана при создании формы, подсказки и диплинки на форме отображаются только по указанному банку. Пользователь в таком случае сразу переходит на страницу реквизитов.

{
	"client_order_id": "test_order_123",
	"order_side": "Buy",
	"button_name": "Sberpay", // Опционально передается банк пользователя, например Сбер
	"amount": "1000", 
	"unique_amount": false,
	"user_id": "test_user123"
}

Возможные значения для поля button_name:

AlfaPay; SberPay; TPay; VTBPay

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

curl -X POST "https://api.luckypay.pro/api/v1/form/create" \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
    "order_data": {
        "client_order_id": "test_order_123",
        "button_name": "Sberpay",
        "order_side": "Buy",
        "amount": "5543",
        "user_id": "user_123"
    },
    "redirect_url": "https://www.google.com/",
    "support_url": "https://www.google.com/",
    "return_url": "https://www.google.com/"
}'

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

Тело запроса имеет вложенную структуру: параметры ордера передаются внутри объекта order_data, а redirect_url, support_url и return_url — на верхнем уровне (см. примеры запросов выше).

{
	"order_data": { ... },
	"redirect_url": "https://example.com/success",
	"support_url": "https://example.com/support",
	"return_url": "https://example.com/checkout"
}

Параметр	Тип	Описание
order_data	object	Параметры создаваемого ордера, см. таблицу ниже.
redirect_url	url, nullable	Страница для перенаправления клиента после успешного закрытия сделки. Если оставить поле пустым - перенаправления не произойдёт
support_url	url, nullable	Ссылка, которая будет доступна пользователю для обращения к поддержке. Если оставить поле пустым, кнопка обращения в службу поддержки отображаться не будет.
return_url	url, nullable	Ссылка «Вернуться на сайт» на странице оплаты. Пользователь переходит по ней сам, в любой момент до оплаты. Если оставить поле пустым, ссылка отображаться не будет.

Поля объекта order_data

Параметр	Тип	Описание
client_order_id	string	Уникальный идентификатор ордера в системе клиента.
order_side	enum	Тип операции ордера. В текущей версии API доступно только значение "Buy" - создание ордера на прием.
button_name	enum, nullable	Позволяет предвыбрать способ оплаты на форме. При передаче параметра этап выбора метода пропускается. При отсутствии параметра на форме будут предложены доступные платежные методы.
amount	decimal	Целевая сумма ордера (без учета комиссии сервиса).
user_id	string, nullable	Идентификатор пользователя для работы антифрод системы (блокирует массовые заявки от одного пользователя)
unique_amount	bool, nullable	Уникализация суммы. Для повышения конверсии при выдаче реквизитов рекомендуется передавать параметр со значением true. В этом случае будут подобраны реквизиты с суммой в диапазоне от amount до amount + 9, а новая сумма появится при созданной сделке на форме и в КБ. Настоятельно рекомендуем использовать этот параметр при запросе реквизитов на «круглые» суммы (например, 1000, 2000 и т.д.).

return_url и redirect_url — разные вещи

• redirect_url — автоматический переход. Отрабатывает только после успешной оплаты: на экране успеха показывается отсчет и через 5 секунд пользователь уходит на указанный адрес.
• return_url — ручная ссылка «Вернуться на сайт» в нижней части страницы оплаты, рядом со ссылкой в поддержку. Доступна пока сделка не закрыта, в том числе во время ожидания подтверждения оплаты. Нужна, чтобы пользователь мог вернуться в ваш интерфейс, не бросая вкладку.

Параметры независимы, можно передать оба, один или ни одного.

⚠️ Важно

Сессия формы создается одним из двух способов:

• без предвыбора - на форме пользователю будут предложены доступные платежные методы;
• с предвыбранной кнопкой - при передаче button_name этап выбора метода пропускается, сразу начинается поиск реквизитов.

Если требуется создать ордер с конкретным платежным методом, используйте host-to-host создание ордера.

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

{
	"success": true,
	"message": null,
	"form_data": {
		"session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"form_url": "https://domain.at/?session_id=3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"order_data": {
			"client_order_id": "test_order_123",
			"order_side": "Buy",
			"payment_method_id": null,
			"amount": "5543.00",
			"customer_bank": null,
			"unique_amount": false
		},
		"support_url": "https://google.com/",
		"redirect_url": "https://google.com/",
		"return_url": "https://google.com/"
	}
}

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

• 400 - Передан order_side со значением "Sell" - форма доступна только для ордеров Buy
• 400 - Переданный button_name отсутствует в конфигурации платежных методов терминала
• 409 - На терминале не активирована платежная форма, обратитесь к администратору
• 429 - Лимит запросов / блокировка антифродом по user_id