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

Отправить пользователя на платежную форму можно двумя способами:

• Ордер с реквизитами на форме — ордер создается сразу, пользователь открывает форму и видит реквизиты для оплаты. Подходит, когда платежный метод известен заранее.
• Сессия формы — пользователь сам выбирает способ оплаты на форме, либо способ предвыбран через button_name.

Ордер с реквизитами на форме

POST /api/v1/order/

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

Особенности

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

⚠️ Важно

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

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

INFO

Выберите валюту и платежный метод, чтобы увидеть пример запроса и ответа. Актуальные payment_method_id для вашего терминала можно получить в разделе Получение платежных методов.

Валюта

Платежный метод

curl -X POST "https://api.payscrow-cascade.io/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",
    "redirect_url": "https://example.com/success",
    "support_url": "https://example.com/support",
    "return_url": "https://example.com/checkout"
}'

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

Платежный метод указывается так же, как при создании ордера Buy (H2H): через payment_method_id либо через method_type (+ nspk_code).

Параметр	Тип	Описание
client_order_id	string	Уникальный идентификатор ордера в системе клиента. От 1 до 64 символов.
order_side	enum	Всегда Buy - клиент создает ордер на прием (пользователь отправляет деньги)
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	Имя клиента. Не рекомендуется использовать параметр, если нет реального имени пользователя
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 и т.д.).
redirect_url	string, nullable	URL для редиректа пользователя после оплаты
support_url	string, nullable	URL службы поддержки, отображается на форме
return_url	string, nullable	Ссылка «Вернуться на сайт» на странице оплаты, пользователь переходит по ней сам
customer_bank	string, nullable	Идентификатор банка для создания формы с предвыбранным банком пользователя. Возможные значения: sberbank, vtb, tinkoff, alfabank
request_metadata	object, nullable	Дополнительные параметры ордера для отдельных валют и методов. Для TRY (IBAN) обязателен order_metadata.tcid — идентификационный номер плательщика (TC Kimlik No). В ответе не возвращается

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

Валюта

Платежный метод

{
	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"client_order_id": "1234",
	"currency": "RUB",
	"method_id": "0cac451e-1ba3-4263-8fc3-02ed158e7ec9",
	"method_name": "Яндекс Банк",
	"method_type": "BankCard",
	"initial_method_id": "8fe3669a-a448-4053-bc4b-43bb51cb3e9d",
	"order_side": "Buy",
	"amount": "1000.00",
	"fee": "15.0",
	"fixed_fee": null, // заполняется только при ненулевом значении
	"status": "Completed",
	"holder_name": "John Doe",
	"holder_account": "2204314159266770",
	"customer_name": "John Doe",
	"customer_account": null,
	"customer_bank": null,
	"receipt_email": null, // почта для отправки чека, только для Buy
	"payment_link": null,
	"webhook_url": null,
	"form_url": "https://example.com",
	"created_at": "2024-07-04T15:40:20.569613Z",
	"updated_at": "2024-07-06T13:27:56.717Z",
	"expires_at": "2024-07-08T15:40:20.569613Z"
}

Ошибки — как при создании ордера Buy (H2H).

Сессия формы

POST /api/v1/form/create

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

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

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

Передача 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; GazpromPay; MKBPay; MTSMoneyPay; MTSPay; OTPPay; OzonPay; PSBPay; PochtaPay; RSHBPay; RaifPay; SberPay; SovcomPay; TPay; UralsibPay; VTBPay; WBPay; YooMoneyPay

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

curl -X POST "https://api.payscrow-cascade.io/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