Работа с заявками на выплату¶

Примечание: Параметры, отмеченные звездочкой (*), являются обязательными.

Создание заявки на выплату¶

Запрос¶

POST example.com/api/merchant/"merchant"/create_pay_out/

Заголовки¶

Name	Value
Content-Type*	application/json

Параметры запроса¶

Name	Type	Format	Description
order_id*	string max: 255		id заявки в вашей системе
payment_method*	string	enum (card, sbp, score, iban)	Тип выплаты (карты, сбп, номер счёта, IBAN)
fiat_amount*	string		Сумма заявки в фиатной валюте с двумя знаками после точки
fiat_currency*	string	enum	Валюта заказа. Доступные значения приведены в списке регионов
timeout	int		Таймаут ожидания выплаты в минутах
number_score	string (20)		Номер счёта (в случае выплаты по номеру счёта)
number_card	string (16)		Номер карты (в случае выплаты по номеру карты)
phone_number	string min 11 max:13		Номер телефона (в случае выплаты по СБП)
iban_number	string max: 34		IBAN (в случае выплаты по IBAN)
bank_name	string max: 72		Банк получателя (обязательно при payment_method = sbp)
bik	string		БИК банка получателя (при наличии)
full_name	string max: 128		ФИО получателя (при наличии)
success_callback_url*	string max: 512		URL для оповещения об успешной выплате
error_callback_url*	string max: 512		URL для отмены выплаты со стороны платформы
customer	string max: 128		Идентификатор клиента
order_description	string max: 8000		Описание заказа
sign*	string		Подпись заказа

Методика формирования подписи в запросе:¶

Подпись для создания заявки на выплату формируется путем нахождения SHA256 Хеша от строки:

order_id : fiat_amount : number_score/number_card/phone_number/iban_number : fiat_currency : sign_key

Из параметров number_score/number_card/phone_number/iban_number выбирается один, в зависимости от используемого метода выплаты.

Пример формирования подписи:

Строка для подписи:

order123:1500.00:79161234567:rub:test_sign_key

Результат SHA256:

53f49a84b929a1c6bf16fdf36ed151738def4b30a8088237ce480ffef538aa2f

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

{
  "order_id": "order123",
  "payment_method": "sbp",
  "fiat_amount": "1500.00",
  "fiat_currency": "rub",
  "timeout": 30,
  "phone_number": "79161234567",
  "bank_name": "Sberbank",
  "bik": "044525225",
  "full_name": "Иванов Иван Иванович",
  "success_callback_url": "https://yourwebsite.com/success",
  "error_callback_url": "https://yourwebsite.com/error",
  "customer": "CUST12345",
  "order_description": "Выплата вознаграждения за выполненную работу",
  "sign": "53f49a84b929a1c6bf16fdf36ed151738def4b30a8088237ce480ffef538aa2f"
}

Параметры ответа¶

Name	Type	Description
internal_transaction_id*	string max: 72	Уникальный ID транзакции в системе (внутренний идентификатор, предоставляется в информационных целях)
fiat_amount*	string	Сумма транзакции в фиатной валюте
usdt_amount*	string	Сумма транзакции в USDT
merchant_spent_usdt*	string	Сколько USDT списано с баланса мерчанта (4 знака после запятой)
fiat_currency*	string	Код фиатной валюты
exchange_rate*	string	Курс обмена фиат/USDT (4 знака после запятой)
payment_method*	string	Метод оплаты
reject_callback_url*	string max: 512	URL для отмены выплаты со стороны мерчанта

Возможные ошибки в ответе¶

Text	Value
overloading requisite	Перегрузка реквизитов, попробуйте создать заявку на другую сумму, с другим методом оплаты, либо подождать
low balance	У вас слишком низкий баланс для создания заявки
this payment method is disabled for your merchant	Данный метод выплаты отключен для вашего мерчанта

Примечание: Список ошибок не исчерпывающий и предоставляет лишь основные ошибки, учитывайте это при интеграции.

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

200Ошибка 400 и остальные 4xx

{
  "ok": true,
  "internal_transaction_id": "TRX-20240215-093045-123456789012",
  "fiat_amount": "1500.00",
  "usdt_amount": "15.8765",
  "merchant_spent_usdt": "15.2500",
  "fiat_currency": "rub",
  "exchange_rate": "98.2472",
  "payment_method": "sbp",
  "reject_callback_url": "https://yourwebsite.com/reject"
}

{
  "ok": false,
  "error": "message"
}

Отмена/подтверждение заявки на выплату со стороны платформы¶

Описание: Данный запрос представляет собой callback со стороны платформы при отмене или подтверждении заявки. Запрос отправляется платформой на указанный URL мерчанта (success_callback_url или error_callback_url) для уведомления об изменении статуса заявки.

Запрос¶

POST error_callback_url

или

POST success_callback_url

Заголовки¶

Name	Value
Content-Type*	application/json

Параметры запроса¶

Name	Type	Format	Description
order_id*	string max: 255		ID заявки в вашей системе
standart_sign*	string		Стандартная подпись
type*	string	enum (pay_out)	Тип операции
status*	string	enum (successful, rejected_timeout, rejected_merchant, rejected_gate)	Статус заявки (successful - успешно, rejected_timeout - отклонено по таймауту, rejected_merchant - отклонено мерчантом, rejected_gate - отклонено поддержкой платформы)
fiat_amount*	string		Сумма заявки в фиатной валюте
usdt_amount*	string		Сумма заявки в USDT
merchant_spent_usdt*	string		Сумма USDT, потраченная мерчантом
fiat_currency*	string		Код фиатной валюты
exchange_rate*	string		Обменный курс
payment_method*	string	enum (card, sbp, score, iban)	Тип выплаты (карты, сбп, номер счёта, IBAN)
created_at*	string	ISO 8601	Дата и время создания заявки
updated_at*	string	ISO 8601	Дата и время обновления заявки
number_card	string		Номер карты (передается только при payment_method = card)
phone_number	string		Номер телефона (передается только при payment_method = sbp)
number_score	string		Номер счёта (передается только при payment_method = score)
iban_number	string		IBAN (передается только при payment_method = iban)
full_name*	string		ФИО получателя
bank_name*	string		Название банка получателя

Примечание: 1. Для удобства подключения при подтверждении/отмене заявки id может передаваться и в url, и в параметрах запроса. Со своей стороны вы можете фактически использовать только 1 из методов приёма id. 2. Из полей платежных реквизитов (number_card, phone_number, number_score, iban_number) передается только одно в зависимости от метода оплаты.

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

{
  "order_id": "123456789",
  "standart_sign": "p6o5n4m3l2k1j0i9h8g7f6e5d4c3b2a1",
  "type": "pay_out",
  "status": "successful",
  "fiat_amount": "5000.00",
  "usdt_amount": "49.8765",
  "merchant_spent_usdt": "49.2500",
  "fiat_currency": "rub",
  "exchange_rate": "100.2472",
  "payment_method": "card",
  "created_at": "2024-02-15T09:30:45Z",
  "updated_at": "2024-02-15T09:45:12Z",
  "number_card": "4276345439581234",
  "phone_number": null,
  "number_score": null,
  "iban_number": null,
  "full_name": "Петров Петр Петрович",
  "bank_name": "Тинькофф"
}

Запрос статуса заявки на выплату¶

Запрос¶

GET example.com/api/merchant/"merchant"/status_pay_out/"pay_out_id"/

Заголовки¶

Name	Value
Content-Type*	application/json
X-Api-Key*	X-Api-Key

Параметры ответа¶

Name	Type	Format	Description
order_id*	string max: 255		Id заявки в вашей системе
type*	string	enum (pay_out)	Тип операции
status*	string	enum (expectation, successful, rejected_timeout, rejected_merchant, rejected_gate)	Статус заявки (expectation - в ожидании выплаты, successful - успешно, rejected_timeout - отклонено по таймауту, rejected_merchant - отклонено мерчантом, rejected_gate - отклонено поддержкой платформы)
fiat_amount*	string		Сумма заявки в фиатной валюте
usdt_amount*	string		Сумма заявки в USDT
merchant_spent_usdt*	string		Сумма USDT, потраченная мерчантом
fiat_currency*	string		Код фиатной валюты
exchange_rate*	string		Обменный курс
payment_method*	string	enum (card, sbp, score, iban)	Тип выплаты (карты, сбп, номер счёта, IBAN)
created_at*	string	ISO 8601	Дата и время создания заявки
updated_at*	string	ISO 8601	Дата и время обновления заявки
number_card	string		Номер карты (передается только при payment_method = card)
phone_number	string		Номер телефона (передается только при payment_method = sbp)
number_score	string		Номер счёта (передается только при payment_method = score)
iban_number	string		IBAN (передается только при payment_method = iban)
full_name*	string		ФИО получателя
bank_name*	string		Название банка получателя
cheque_urls	array		Массив URL адресов чеков (при наличии)

Примечание: 1. Из полей платежных реквизитов (number_card, phone_number, number_score, iban_number) передается только одно в зависимости от метода оплаты. 2. Поле cheque_urls передается только если для заявки доступны чеки.

Обратите внимание! Не используйте поллинг для мониторинга статуса заявок. На сервере платформы установлены лимиты на запросы статуса. Для мониторинга статуса заявок используйте функционал callback. В случае необходимости использовать поллинг, согласуйте это с технической поддержкой платформы.

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

200Ошибка 400 и остальные 4xx

{
  "ok": true,
  "order_id": "123456789",
  "type": "pay_out",
  "status": "successful",
  "fiat_amount": "5000.00",
  "usdt_amount": "49.8765",
  "merchant_spent_usdt": "49.2500",
  "fiat_currency": "rub",
  "exchange_rate": "100.2472",
  "payment_method": "card",
  "created_at": "2024-02-15T09:30:45Z",
  "updated_at": "2024-02-15T09:45:12Z",
  "number_card": "4276345439581234",
  "phone_number": null,
  "number_score": null,
  "iban_number": null,
  "full_name": "Петров Петр Петрович",
  "bank_name": "Тинькофф",
  "cheque_urls": [
    "https://yourwebsite.com/cheque1.pdf",
    "https://yourwebsite.com/cheque2.pdf",
    "https://yourwebsite.com/cheque3.pdf"
  ]
}

{
  "ok": false,
  "error": "message"
}

Отмена заявки на выплату со стороны мерчанта¶

Запрос¶

POST example.com/api/merchant/"merchant"/rejected_pay_out/

Заголовки¶

Name	Value
Content-Type*	application/json

Параметры запроса¶

Name	Type	Format	Description
order_id*	string max: 255		id заявки в вашей системе
standart_sign*	string		Стандартная подпись

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

200Ошибка 400 и остальные 4xx

{
  "ok": true
}

{
  "ok": false,
  "error": "message"
}