# BeMorePay API v1.4

Версия документации: 1.4. Обновлено: 30.09.2026. Формат: REST API, JSON.
Эта страница — Markdown-версия документации https://bemorepay.ru/api_v1 для LLM и автоматической обработки.

## Кратко

- Base URL: `https://api.bemorepay.ru`. Все методы — `POST`.
- Заголовки: `Content-Type: application/json` во всех запросах; `Authorization: Bearer {terminal_token}` в методах с аутентификацией (все методы ниже).
- Токен терминала — статический ключ из 44 латинских букв и цифр. Выдаётся один раз при регистрации терминала, замена не предусмотрена.
- Тестовое окружение (Sandbox) доступно по запросу. Без него работает только production.
- Успех: в ответе `"status": true`. Ошибка: `"status": false` и поле `errors` (ошибки валидации по полям) или `error` (строка).
- Рекомендуемые методы: `formBankId`, `payments/recurrentext`, `transactions`, `payments/refund`. Методы `form` и `payments/recurrent` устарели, в новых интеграциях не использовать.

## Сквозной сценарий рекуррентных платежей

1. `POST /api/formBankId/` — получить ссылку `formUrl` на форму привязки карты. Клиент открывает её и привязывает карту.
2. Взять UUID привязки — **последний сегмент пути `formUrl`** (например, из `https://api.bemorepay.ru/api/terminal/019c4d2c-2bf5-70e9-bf8c-69c60cee0bf5` берётся `019c4d2c-2bf5-70e9-bf8c-69c60cee0bf5`).
3. `POST /api/transactions/` с `{"uuid": "<UUID привязки>"}` — получить статус привязки и токен карты: `transactions[].subscriber.token`. Пока карта не привязана, токена в ответе нет — запрос нужно повторить позже.
4. `POST /api/payments/recurrentext/` с этим токеном в поле `token` — создать рекуррентный платёж. В ответе верхнеуровневый `uuid` платежа.
5. `POST /api/transactions/` с `{"uuid": "<UUID платежа>"}` — проверить статус платежа. Статус финальный не сразу, проверять с паузой.
6. При необходимости возврата: `POST /api/payments/refund/` с UUID платежа и суммой, затем снова `transactions` с UUID возврата.

## Важные правила (частые ошибки)

- `orderNumber` (в `formBankId`, `form`) и `orderId` (в `recurrentext`, `recurrent`) передаются **строго строкой**: `"1010020"`, а не `1010020`. Число даёт ошибку валидации.
- `description` (в `recurrentext`, `recurrent`): **только латиница, без кириллицы и спецсимволов**. Описание на русском отклоняется.
- `bankId` — число (int), ID банка из личного кабинета, раздел «Сайты». Имя параметра с маленькой буквы: `bankId`, не `BankId`.
- UUID привязки карты не приходит отдельным полем — он в конце `formUrl` (см. сценарий выше).
- Один и тот же метод `transactions` принимает UUID привязки, UUID платежа и UUID возврата.
- Сумма возврата в `refund` должна совпадать с суммой исходного платежа.
- Возврат выполняется не мгновенно: заявка ставится в очередь и уходит в банк через несколько минут. Итоговый статус проверять через `transactions`.
- В ответе `refund` UUID возврата лежит внутри объекта `validated`, а в ответе `recurrentext` — на верхнем уровне (`uuid`).
- Суммы (`amount`) в запросах и ответах — строки с двумя знаками после точки: `"999.00"`.

## Метод `formBankId` — форма привязки карты с выбором банка

`POST https://api.bemorepay.ru/api/formBankId/`

Запрос формы для привязки карты с выбором банка (рекуррентные платежи).

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| `orderNumber` | string | да | ID транзакции на стороне мерчанта, строго строкой |
| `bankId` | int | да | ID банка, с которого получить форму. Доступные ID — в личном кабинете, раздел «Сайты» |
| `successUrl` | url | да | HTTPS-редирект при успешной оплате |
| `failUrl` | url | да | HTTPS-редирект при неуспешной оплате |
| `param1`, `param2`, `param3` | string (max 100) | нет | Метки мерчанта |
| `jsonParams` | JSON (строка) | нет | Дополнительные параметры, если не хватает `param1`–`param3` |

Запрос:

```bash
curl -X POST \
  -H 'Authorization: Bearer 4VKye****92a19' \
  -H 'Content-Type: application/json' \
  -i 'https://api.bemorepay.ru/api/formBankId/' \
  --data '{
    "orderNumber": "1010020",
    "bankId":      1,
    "param1":      "1",
    "param2":      "2",
    "param3":      "3",
    "jsonParams":  "{\"json1\":\"json1\"}",
    "successUrl":  "https://success.io",
    "failUrl":     "https://fail.io"
  }'
```

Успешный ответ:

```json
{
  "status": true,
  "formUrl": "https://api.bemorepay.ru/api/terminal/019c4d2c-2bf5-70e9-bf8c-69c60cee0bf5",
  "data": {
    "orderNumber": "1010020",
    "bankId": 1,
    "amount": "1.00",
    "successUrl": "https://success.io",
    "failUrl": "https://fail.io"
  },
  "runTime": 0.11879205703735352
}
```

UUID привязки карты — последний сегмент `formUrl` (здесь `019c4d2c-2bf5-70e9-bf8c-69c60cee0bf5`). Его передают в поле `uuid` метода `transactions`.

Ответ с ошибкой:

```json
{
  "status": false,
  "errors": { "bankId": ["validation.required"] }
}
```

## Метод `payments/recurrentext` — рекуррентный платёж с выбором банка

`POST https://api.bemorepay.ru/api/payments/recurrentext/`

Создание рекуррентного платежа по токену привязанной карты.

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| `orderId` | string | да | ID транзакции на стороне мерчанта, строго строкой |
| `bankId` | int | да | ID банка из личного кабинета, раздел «Сайты» |
| `amount` | float (строка `"999.00"`) | да | Сумма платежа |
| `token` | uuid | да | Токен карты: `transactions[].subscriber.token` из ответа метода `transactions` после привязки карты |
| `description` | string (max 100) | нет | Описание транзакции. Только латиница, без кириллицы и спецсимволов |
| `param1`, `param2`, `param3` | string (max 100) | нет | Метки мерчанта |
| `jsonParams` | JSON (строка) | нет | Дополнительные параметры, если не хватает `param1`–`param3` |

Запрос:

```bash
curl -X POST \
  -H 'Authorization: Bearer 4VKye6z*****92a19a3c3' \
  -H 'Content-Type: application/json' \
  -i 'https://api.bemorepay.ru/api/payments/recurrentext/' \
  --data '{
    "orderId":     "1010020",
    "bankId":      1,
    "amount":      "999.00",
    "token":       "019a256c-3865-721e-b04a-0bd2bdf60db6",
    "description": "description",
    "param1":      "1",
    "param2":      "2",
    "param3":      "3",
    "jsonParams":  "{\"1\":\"1\"}"
  }'
```

Успешный ответ:

```json
{
  "status": true,
  "uuid": "019c4d2f-0f29-7045-95f0-70b52f2adf06"
}
```

`uuid` — UUID платежа, по нему проверяется статус через `transactions`.

Ответ с ошибкой:

```json
{
  "status": false,
  "orderId": null,
  "errors": { "bankId": ["validation.required"] }
}
```

## Метод `transactions` — статус привязки, платежа или возврата

`POST https://api.bemorepay.ru/api/transactions/`

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| `uuid` | uuid | да | UUID привязки карты (последний сегмент `formUrl` из ответа `formBankId`), либо UUID платежа (ответ `recurrentext`), либо UUID возврата (`validated.uuid` из ответа `refund`) |

Запрос:

```bash
curl -X POST \
  -H 'Authorization: Bearer 4VKye6zj*****2a19a3c3' \
  -H 'Content-Type: application/json' \
  -i 'https://api.bemorepay.ru/api/transactions/' \
  --data '{"uuid":"01995770-0550-72ba-a2da-95a6cf591b61"}'
```

Успешный ответ — привязка карты. Токен карты для `recurrentext` лежит в `transactions[].subscriber.token`:

```json
{
  "status": true,
  "uuid": "019c568d-55cd-7026-951d-e52bf5339123",
  "transactions": [{
    "uuid": "019c568d-55cd-7026-951d-e52bf5459123",
    "order_id": "2602131",
    "rrn": null,
    "status_code": 1,
    "status_description": "STATUS_SUCCESS",
    "currency": "RUB",
    "amount": "1.00",
    "card_number_first_six": "110070",
    "card_number_last_four": "0333",
    "card_expiration_date_month": "10",
    "card_expiration_date_year": "33",
    "card_holder_name": "USER NAME",
    "created_at": "2025-01-14 12:22:51",
    "transactionData": {
      "param1": "param1",
      "param2": "param2",
      "param3": "param3",
      "data": "{}"
    },
    "subscriber": {
      "card_number_first_six": "210223",
      "card_number_last_four": "0123",
      "card_expiration_date_month": "12",
      "card_expiration_date_year": "31",
      "card_holder_name": "USER NAME",
      "card_issuer_name": "",
      "issuer_bank_country_code": "",
      "currency": "",
      "card_type": "",
      "token": "019c568d-f157-735f-a342-d6b5fa6c0d5f",
      "status_code": 1,
      "created_at": "2026-11-13 12:31:08"
    }
  }]
}
```

Успешный ответ — рекуррентный платёж:

```json
{
  "status": true,
  "uuid": "019c4d2f-c46f-7194-913c-24f289c7a2c3",
  "transactions": [{
    "uuid": "019c4d2f-c46f-7194-913c-24f289c7a2c3",
    "order_id": "3945495_20260211145137",
    "rrn": "604214032713",
    "status_code": 1,
    "status_description": "STATUS_SUCCESS",
    "currency": "RUB",
    "amount": "496.00",
    "card_number_first_six": null,
    "card_number_last_four": null,
    "card_expiration_date_month": null,
    "card_expiration_date_year": null,
    "card_holder_name": null,
    "created_at": "2026-02-11 14:52:43"
  }]
}
```

Ключевые поля транзакции: `status_description` (например `STATUS_SUCCESS`) и `status_code` (`1` — успешно), `amount`, `order_id` (строка), `created_at`. В списке `transactions` может быть несколько записей; актуальная — с наибольшим `created_at`.

Ответ с ошибкой:

```json
{
  "status": false,
  "error": "Authentication error"
}
```

## Метод `payments/refund` — возврат платежа

`POST https://api.bemorepay.ru/api/payments/refund/`

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| `uuid` | uuid | да | UUID транзакции для возврата |
| `amount` | float (строка `"1.00"`) | да | Сумма возврата — должна совпадать с суммой исходного платежа |

Запрос:

```bash
curl -X POST \
  -H 'Authorization: Bearer 4VKye6zj*****2a19a3c3' \
  -H 'Content-Type: application/json' \
  -i 'https://api.bemorepay.ru/api/payments/refund/' \
  --data '{"uuid":"01995770-0550-72ba-a2da-95a6cf591b61","amount":"1.00"}'
```

Успешный ответ:

```json
{
  "status": true,
  "validated": {
    "uuid": "019c4d2f-c46f-7194-913c-24f289c7a2c3",
    "amount": "1.00"
  }
}
```

`validated.uuid` — UUID возврата. Ответ только подтверждает создание заявки. Заявка ставится в очередь и уходит в банк через несколько минут; итоговый статус нужно проверить методом `transactions` по UUID возврата.

Ответ с ошибкой:

```json
{
  "status": false,
  "error": "Authentication error"
}
```

## Устаревшие методы

Будут отключены в одном из будущих релизов. В новых интеграциях не использовать.

### `form` (устарел) — заменён на `formBankId`

`POST https://api.bemorepay.ru/api/form/` — форма привязки карты без выбора банка.

| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| `orderNumber` | string | да | ID транзакции на стороне мерчанта, строго строкой |
| `successUrl` | url | да | HTTPS-редирект при успешной оплате |
| `failUrl` | url | да | HTTPS-редирект при неуспешной оплате |
| `param1`, `param2`, `param3` | string (max 100) | нет | Метки мерчанта |
| `jsonParams` | JSON (строка) | нет | Дополнительные параметры |

Параметр `amount` упразднён (с v1.1): передавать не нужно, при наличии игнорируется. Ответ такой же, как у `formBankId`, но без `bankId`: `formUrl`, `data`, `runTime`. UUID привязки так же берётся из конца `formUrl`.

### `payments/recurrent` (устарел) — заменён на `payments/recurrentext`

`POST https://api.bemorepay.ru/api/payments/recurrent/` — рекуррентный платёж без выбора банка.

Параметры те же, что у `payments/recurrentext`, но без `bankId`: `orderId` (string), `amount`, `token`, `description` (только латиница), `param1`–`param3`, `jsonParams`. Успешный ответ: `{"status": true, "uuid": "..."}`.

## История изменений

- **v1.4** (30.09.2026) — исправление. `orderNumber` и `orderId` — строка (`string`). Пример ответа `refund` приведён к виду с объектом `validated`. Уточнено: `description` — только латиница, без кириллицы и спецсимволов; UUID привязки берётся из последнего сегмента `formUrl`. Sandbox доступен по запросу.
- **v1.3** (29.08.2026) — исправлено название параметра `BankId` на `bankId` в `formBankId` и `payments/recurrentext`.
- **v1.2** (07.08.2026) — новые методы `formBankId` и `payments/recurrentext` с обязательным `bankId`; `form` и `payments/recurrent` объявлены устаревшими.
- **v1.1** (14.06.2026) — в `form` параметр `amount` упразднён.
- **v1.0** (15.02.2026) — первый релиз: `form`, `payments/recurrent`, `transactions`, `payments/refund`.