API документация для работы на выплаты со стороны команд¶

Данная документация описывает взаимодействие команд с платформой для обработки заявок на выплату.

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

Базовая информация¶

Универсальные параметры¶

Параметр	Type	Format	Description
X-Api-Key	string	max: 255	API-ключ для авторизации
sign_key	string	max: 255	Симметричный ключ для подписи важных операций
system_order_id	string	72	ID заявки внутри нашей системы (используется для технических операций)
merchant_order_id	string	max: 255	ID заявки мерчанта (отображается в интерфейсе)

Получение новой заявки (Callback)¶

Данный запрос отправляется платформой на указанный URL команды при создании новой заявки.

Запрос¶

POST your_callback_url

Заголовки¶

Name	Value
Content-Type*	application/json

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

Name	Type	Format	Description
system_order_id*	string	72	ID заявки внутри нашей системы
merchant_order_id*	string	max: 255	ID заявки мерчанта
payment_method*	string	enum (card, sbp)	Вид реквизитов (карта или СБП)
bank_name*	string	max: 72	Наименование банка
full_name	string	max: 128	ФИО получателя (обязательно для СБП)
number_card	string	16	Номер карты (для payment_method = card)
phone_number	string	min: 11, max: 13	Номер телефона (для payment_method = sbp)
fiat_amount*	string		Сумма заявки в рублях
usdt_amount	string		Сумма в USDT
exchange_rate	string		Курс платформы
timeout	int		Тайм-аут в минутах
sign*	string		Подпись запроса

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

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

system_order_id:requisite:fiat_amount:sign_key

где requisite - это номер карты или номер телефона в зависимости от типа платежа.

Примеры строк для формирования подписи:

Для payment_method = card:

SYS-123456789012345678901234567890123456789012345678901234567890123456789012:4276123456789012:5000.00:your_secret_key_here

Для payment_method = sbp:

SYS-123456789012345678901234567890123456789012345678901234567890123456789012:79161234567:5000.00:your_secret_key_here

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

{
  "system_order_id": "SYS-123456789012345678901234567890123456789012345678901234567890123456789012",
  "merchant_order_id": "MERCH-987654321",
  "payment_method": "card",
  "bank_name": "Сбербанк",
  "full_name": "Иванов Иван Иванович",
  "number_card": "4276123456789012",
  "fiat_amount": "5000.00",
  "usdt_amount": "49.8765",
  "exchange_rate": "100.2472",
  "timeout": 30,
  "sign": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

Ожидаемый ответ¶

При успешном получении заявки команда должна вернуть HTTP статус 200.

200 - Заявка принятаЛюбой другой статус - Ошибка

{
  "ok": true
}

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

Получение списка активных заявок¶

Запрос¶

GET example.com/api/team/orders/active

Заголовки¶

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

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

Name	Type	Format	Description
orders*	array		Массив активных заявок
total*	int		Общее количество активных заявок

Структура объекта заявки¶

Name	Type	Format	Description
system_order_id*	string	72	ID заявки внутри нашей системы
merchant_order_id*	string	max: 255	ID заявки мерчанта
payment_method*	string	enum (card, sbp)	Вид реквизитов
bank_name*	string	max: 72	Наименование банка
full_name	string	max: 128	ФИО получателя
number_card	string	16	Номер карты (если payment_method = card)
phone_number	string		Номер телефона (если payment_method = sbp)
fiat_amount*	string		Сумма заявки в рублях
usdt_amount	string		Сумма в USDT
exchange_rate	string		Курс платформы
status*	string	enum (expectation, in_progress)	Статус заявки
created_at*	string	ISO 8601	Дата и время создания

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

{
  "ok": true,
  "orders": [
    {
      "system_order_id": "SYS-123456789012345678901234567890123456789012345678901234567890123456789012",
      "merchant_order_id": "MERCH-987654321",
      "payment_method": "card",
      "bank_name": "Сбербанк",
      "full_name": "Иванов Иван Иванович",
      "number_card": "4276123456789012",
      "fiat_amount": "5000.00",
      "usdt_amount": "49.8765",
      "exchange_rate": "100.2472",
      "status": "expectation",
      "created_at": "2024-02-15T09:30:45Z"
    },
    {
      "system_order_id": "SYS-123456789012345678901234567890123456789012345678901234567890123456789013",
      "merchant_order_id": "MERCH-987654322",
      "payment_method": "sbp",
      "bank_name": "Тинькофф",
      "full_name": "Петров Петр Петрович",
      "phone_number": "79161234567",
      "fiat_amount": "3000.00",
      "usdt_amount": "29.9259",
      "exchange_rate": "100.2472",
      "status": "in_progress",
      "created_at": "2024-02-15T10:15:30Z"
    }
  ],
  "total": 2
}

Прикрепление чека к заявке¶

Запрос¶

POST example.com/api/team/orders/attach_cheque

Заголовки¶

Name	Value
Content-Type*	multipart/form-data
X-Api-Key*	X-Api-Key

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

Name	Type	Format	Description
system_order_id*	string	72	ID заявки внутри нашей системы
file*	file		Файл чека

Информация о файле¶

При загрузке файла автоматически передаются следующие данные:

Name	Description
filename	Имя файла (передается автоматически)
Content-Type	MIME-тип файла (передается автоматически)

Поддерживаемые форматы файлов: PDF, JPG, JPEG, PNG

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

cURL:

curl -X POST https://example.com/api/team/orders/attach_cheque \
  -H "X-Api-Key: your-api-key" \
  -F "system_order_id=SYS-123456789012345678901234567890123456789012345678901234567890123456789012" \
  -F "file=@/path/to/cheque.pdf"

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

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

{
  "ok": true,
  "message": "File successfully attached"
}

{
  "ok": false,
  "error": "Order not found or already completed"
}

Подтверждение заявки¶

Запрос¶

POST example.com/api/team/orders/confirm

Заголовки¶

Name	Value
Content-Type*	application/json

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

Name	Type	Format	Description
system_order_id*	string	72	ID заявки внутри нашей системы
sign*	string		Подпись подтверждения

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

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

system_order_id:sign_key

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

SYS-123456789012345678901234567890123456789012345678901234567890123456789012:your_secret_key_here

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

{
  "system_order_id": "SYS-123456789012345678901234567890123456789012345678901234567890123456789012",
  "sign": "77d30ae2b9dcf28ee6fa907cd551317fd40bf6baf70b5da94f58b74ac12e3b4e"
}

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

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

{
  "ok": true,
  "message": "Order successfully confirmed"
}

{
  "ok": false,
  "error": "Invalid signature or order not found"
}

Отклонение заявки¶

Запрос¶

POST example.com/api/team/orders/reject

Заголовки¶

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

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

Name	Type	Format	Description
system_order_id*	string	72	ID заявки внутри нашей системы

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

{
  "system_order_id": "SYS-123456789012345678901234567890123456789012345678901234567890123456789012"
}

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

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

{
  "ok": true,
  "message": "Order successfully rejected"
}

{
  "ok": false,
  "error": "Order not found or already completed"
}