Payscrow Docs

Создание ордера Buy (H2H) ​

Создает новый ордер на прием (пользователь отправляет деньги) и возвращает информацию о нем.

http
POST /api/v1/order/

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

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

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

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

json
{
	"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 для указания конкретного банка.

json
{
	"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 - для максимально быстрой интеграции (если у вас уже используются НСПК коды)

⚠️ Важно

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

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

INFO

Запрос идентичен для всех валют. payment_method_id для нужной валюты можно получить в разделе Получение платежных методов.

bash
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"
}'

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

ПараметрТипОписание
client_order_idstringУникальный идентификатор ордера в системе клиента. От 1 до 64 символов.
order_sideenumВсегда Buy - клиент создает ордер на прием (пользователь отправляет деньги). Для выплат см. Создание ордера Sell (H2H)
payment_method_idenum, nullableСпособ 1: ID платежного метода. См. Получение платежных методов
method_typeenum, nullableСпособ 2: Тип агрегатного метода. См. Типы платежных методов
nspk_codestring, nullableСпособ 2: НСПК код банка (только с method_type)
amountdecimalЦелевая сумма ордера (без учета комиссии сервиса).
customer_namestring, nullableИмя клиента. Не рекомендуется использовать параметр, если нет реального имени пользователя
user_idstring, nullableИдентификатор пользователя для работы антифрод системы (блокирует массовые заявки от одного пользователя)
webhook_urlurl, nullableURL для вебхука по данному ордеру. Если указан, уведомление отправляется на него вместо URL, настроенных на терминале. Валидный http(s) URL, до 512 символов
unique_amountbool, nullableУникализация суммы. Для повышения конверсии при выдаче реквизитов рекомендуется передавать параметр со значением true. В этом случае будут подобраны реквизиты с суммой в диапазоне от amount до amount + 9, а новая сумма вернётся в ответе в поле amount. Настоятельно рекомендуем использовать этот параметр при запросе реквизитов на «круглые» суммы (например, 1000, 2000 и т.д.).

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

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

Особенности

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

⚠️ Важно

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

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

ПараметрТипОписание
redirect_urlstring, nullableURL для редиректа пользователя после оплаты
support_urlstring, nullableURL службы поддержки, отображается на форме
return_urlstring, nullableСсылка «Вернуться на сайт» на странице оплаты, пользователь переходит по ней сам
customer_bankstring, nullableИдентификатор банка для создания формы с предвыбранным банком пользователя. Возможные значения: sberbank, vtb, tinkoff, alfabank

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

json
{
    "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 ​

Валюта
json
{
	"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": "John Doe",
	"holder_account": "4627100000000001",
	"customer_name": "John Doe",
	"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

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

  • 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.

    Сумма ордера вне лимитов выбранного платежного метода

  • 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.

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