Депозиты

Депозит — приём платежа от вашего клиента. Платформа выдаёт реквизиты, ваш клиент переводит на них деньги, и после подтверждения платежа сделка закрывается.

В API депозит — это сделка с типом buy. Все запросы идут на общие эндпоинты сделок, тип задаётся полем type в теле запроса.

Действие	Метод	Путь
Создание депозита	`POST`	`/api/deals/create`
Получение депозита	`GET`	`/api/deals/get`
Обновление депозита	`POST`	`/api/deals/update`

Все действия раздела доступны только клиентам (по api_key). Сделка должна принадлежать вашему клиенту, иначе вернётся ACCESS_DENIED.

Создание депозита

Создаёт депозит и подбирает подходящий реквизит под указанные параметры.

Тело запроса (JSON)

Поле	Тип	Обяз.	Описание
`type`	`string`	✅	`buy`
`user_id`	`string`	✅	Идентификатор заказа на вашей стороне
`bank_uuid`	`string`	✅	UUID банка из списка банков
`amount`	`number`	✅	Сумма платежа, положительное число (формат `35.00`)
`currency`	`string`	✅	Валюта — см. «Справочники»
`payment_method`	`string`	✅	Метод оплаты — см. «Справочники»
`return_url`	`string`	⚠️	Адрес возврата плательщика с платёжной страницы
`success_url`	`string`	⚠️	Адрес перехода после успешной оплаты
`fail_url`	`string`	⚠️	Адрес перехода после неудачной оплаты
`callback_url`	`string`	⚠️	Адрес для уведомлений о смене статуса — см. «Колбеки»

bash

curl -X POST "https://arbitpay.online/api/deals/create" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "buy",
    "user_id": "order-10237",
    "bank_uuid": "a6ccb483-ffab-439f-ae08-34c87e6e6738",
    "amount": 39772.64,
    "currency": "UAH",
    "payment_method": "card"
  }'

Запрос идемпотентен по user_id. Если у вас уже есть сделка с тем же user_id, того же типа и на ту же запрашиваемую сумму в статусе created, повторный запрос вернёт её же (с сообщением о существующей сделке), а не создаст дубль — это защищает от таймаута и двойной отправки.

Важно:

идемпотентность действует, только пока сделка в статусе created. Как только она перешла в pending, unconfirmed, paid, canceled или dispute, повторный запрос с тем же user_id создаст новую сделку;
сравнивается исходная сумма из запроса, а не скорректированная payment.amount.

Платформа может скорректировать сумму на несколько копеек, чтобы платёж можно было однозначно сопоставить со сделкой. Оплачивать нужно ровно ту сумму, которая пришла в payment.amount. Если она отличается от запрошенной, в ответе дополнительно появляется поле payment.requested_amount.

Поля return_url, success_url и fail_url необязательны и применяются, если для выбранного метода оплаты используется платёжная страница. Передавайте полные адреса со схемой http или https — значения сохраняются в сделке как есть.

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

`code`	Условие
`ACCESS_DENIED`	Токен не принадлежит клиенту
`INVALID_METHOD`	Метод запроса не `POST`
`MISSING_FIELDS`	Отсутствует одно из обязательных полей
`INVALID_TYPE`	`type` не `buy` и не `sell`
`INVALID_AMOUNT`	`amount` не число или ≤ 0
`INVALID_CURRENCY`	Недопустимая валюта
`INVALID_PAYMENT_METHOD`	Недопустимый метод оплаты
`BANK_NOT_FOUND`	Банк по `bank_uuid` не найден или отключён
`REQUISITE_NOT_FOUND`	Не найден подходящий реквизит под указанные критерии
`NO_FREE_AMOUNT`	Нет свободной суммы платежа под указанные критерии

Получение депозита

Возвращает депозит по его uuid.

Параметры запроса (query)

Поле	Тип	Обяз.	Описание
`uuid`	`string`	✅	UUID сделки (36 символов)

bash

curl -X GET "https://arbitpay.online/api/deals/get?uuid=8f14e45f-cea1-4a2c-9b7a-1d2e3f4a5b6c" \
  -H "Authorization: Bearer <API_KEY>"

См. структуру ответа.

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

`code`	Условие
`ACCESS_DENIED`	Токен не принадлежит клиенту или сделка чужая
`INVALID_METHOD`	Метод запроса не `GET`
`MISSING_FIELDS`	Не передан `uuid`
`INVALID_UUID`	`uuid` не соответствует формату (36 символов)

Обновление депозита

Обновляет статус депозита, добавляет комментарий и/или прикрепляет изображение оплаты.

Тело запроса (JSON)

Поле	Тип	Обяз.	Описание
`uuid`	`string`	✅	UUID депозита (36 символов)
`status`	`string`	⚠️	Новый статус — см. «Справочники»
`comment`	`string`	⚠️	Текст комментария к депозиту
`image_base64`	`string`	⚠️	Изображение оплаты в формате data-URL: `data:image/(png\|jpg\|jpeg\|webp);base64,...`

Помимо uuid, необходимо передать хотя бы одно из полей status, comment, image_base64. Иначе — ошибка NO_FIELDS_TO_UPDATE.

bash

curl --request POST \
  --url "https://arbitpay.online/api/deals/update" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "uuid": "8f14e45f-cea1-4a2c-9b7a-1d2e3f4a5b6c",
    "comment": "Комментарий к сделке",
    "image_base64": "data:image/png;base64,iVBORw0KGgo..."
  }'

См. структуру ответа.

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

`code`	Условие
`ACCESS_DENIED`	Токен не принадлежит клиенту или депозит чужой
`INVALID_METHOD`	Метод запроса не `POST`
`MISSING_FIELDS`	Не передан `uuid`
`NO_FIELDS_TO_UPDATE`	Не передано ни одного поля для обновления
`INVALID_UUID`	`uuid` не соответствует формату
`INVALID_STATUS`	Недопустимое значение `status`
`INVALID_IMAGE_FORMAT`	`image_base64` не PNG/JPEG/WebP в формате data-URL

Структура ответа

Возвращается эндпоинтами создания, получения и обновления.

json

{
  "status": "success",
  "code": "SUCCESS",
  "data": {
    "deal": {
      "uuid": "8f14e45f-cea1-4a2c-9b7a-1d2e3f4a5b6c",
      "type": "buy",
      "status": "created",
      "created": "2026-07-08 12:34:56"
    },
    "requisite": {
      "name": "Иван",
      "surname": "Петров",
      "midname": "Сергеевич",
      "details": "4149600012342309",
      "organization_name": "ФОП Петров",
      "iban": "UA123456789012345678901234567",
      "identification_code": "1234567890",
      "payment_purpose": "Оплата услуг"
    },
    "payment": {
      "bank_name": "Кредит Днепр",
      "method": "card",
      "amount": "39772.64",
      "currency": "UAH",
      "time_limit": 30,
      "time_limit_unit": "minutes",
      "payment_url": ""
    },
    "comments": []
  },
  "message": "Deal retrieved successfully."
}

Описание полей

deal

Поле	Тип	Описание
`uuid`	`string`	Идентификатор сделки
`type`	`string`	Всегда `buy` для депозита
`status`	`string`	Текущий статус — см. «Справочники»
`created`	`string`	Дата и время создания
`receipt_url`	`string`	Ссылка на квитанцию. Поле появляется только после того, как квитанцию прикрепили

requisite — реквизиты, на которые платит ваш клиент

Поле	Тип	Описание
`name`	`string`	Имя
`surname`	`string`	Фамилия
`midname`	`string`	Отчество
`details`	`string`	Номер карты / счёта
`organization_name`	`string`	Название организации
`iban`	`string`	IBAN
`identification_code`	`string`	Идентификационный код
`payment_purpose`	`string`	Назначение платежа

payment — параметры платежа

Поле	Тип	Описание
`bank_name`	`string`	Название банка
`method`	`string`	Метод оплаты
`amount`	`string`	Сумма платежа — оплачивать нужно именно её
`requested_amount`	`number`	Только при создании и только если сумма была скорректирована — сумма из запроса
`currency`	`string`	Валюта
`time_limit`	`number`	Лимит времени на оплату
`time_limit_unit`	`string`	Единица измерения лимита (`minutes`)
`payment_url`	`string`	Ссылка на оплату для методов с платёжной страницей; иначе пустая строка

comments — массив комментариев к сделке.

Депозиты

Создание депозита#

Тело запроса (JSON)#

Возможные ошибки#

Получение депозита#

Параметры запроса (query)#

Возможные ошибки#

Обновление депозита#

Тело запроса (JSON)#

Возможные ошибки#

Структура ответа#

Описание полей#

Создание депозита

Тело запроса (JSON)

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

Получение депозита

Параметры запроса (query)

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

Обновление депозита

Тело запроса (JSON)

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

Структура ответа

Описание полей