Payscrow Docs

Создание ордера 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 для нужной валюты можно получить в разделе Получение платежных методов.

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": "Sell",
    "payment_method_id": "2875d43f-b80e-46e1-a3f6-bb82912ccf3d",
    "amount": "1000",
    "customer_account": "79001234567",
    "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Счет клиента для выбранного платежного метода в формате Типы платежного метода, на который переводятся средства. Обязательный
customer_namestring, nullableИмя клиента. Не рекомендуется использовать параметр, если нет реального имени пользователя
user_idstring, nullableИдентификатор пользователя для работы антифрод системы (блокирует массовые заявки от одного пользователя)
webhook_urlurl, nullableURL для вебхука по данному ордеру. Если указан, уведомление отправляется на него вместо URL, настроенных на терминале. Валидный http(s) URL, до 512 символов

Пример ответа 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": "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,
	"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"
}

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

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

  • 400 Customer account is required

    Не передан 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

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

  • 422 Sell orders must specify a specific bank and cannot use aggregation methods. Use payment_method_id or nspk_code + method_type.

    Для Sell ордера указан агрегатный метод. Укажите конкретный банк через payment_method_id или nspk_code + method_type, см. способы указания платежного метода

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

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

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