Payscrow Docs

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

⚠️ Важно

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

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

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Уникальный идентификатор ордера в системе клиента.
order_sideenumBuy - клиент создает ордер на прием (пользователь отправляет деньги)
Sell - клиент создает ордер на вывод (пользователь принимает деньги).
payment_method_idenum, nullableСпособ 1: ID платежного метода. См. Получение платежных методов
method_typeenum, nullableСпособ 2: Тип агрегатного метода. См. Типы платежных методов
nspk_codestring, nullableСпособ 2: НСПК код банка (только с method_type)
amountdecimalЦелевая сумма ордера (без учета комиссии сервиса).
customer_namestring, nullableИмя клиента. Не рекомендуется использовать параметр, если нет реального имени пользователя
customer_payment_accountstring, nullableСчет клиента для выбранного платежного метода в формате Типы платежного метода, для перевода на него средств (Sell)
null для ордеров Buy
user_idstring, nullableИдентификатор пользователя для работы антифрод системы (блокирует массовые заявки от одного пользователя)
unique_amountbool, nullableУникализация суммы. Для повышения конверсии при выдаче реквизитов рекомендуется передавать параметр со значением true. В этом случае будут подобраны реквизиты с суммой в диапазоне от amount до amount + 9, а новая сумма вернётся в ответе в поле amount. Настоятельно рекомендуем использовать этот параметр при запросе реквизитов на «круглые» суммы (например, 1000, 2000 и т.д.).

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

json
{
	"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"client_order_id": "1234",
	"currency": "RUB",
	"method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"method_name": "Сбербанк",
	"initial_method_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
	"order_side": "Buy",
	"amount": "1000.00",
	"fee": "15.0",
	"status": "Completed",
	"holder_name": "Иванов Иван Иванович",
	"holder_account": "4627100101654724",
	"customer_name": "Петров Петр Петрович",
	"customer_account": null,
	"payment_link": 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 Payment method ID or payment type is required

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

  • 402 - Недостаточный баланс для Sell ордера

  • 404 Payment method not found

    Указан несуществующий платежный метод, для просмотра списка доступных методов можно воспользоваться Получение платежных методов

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

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

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

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