---
slug: "alfa-bank-api"
name: "Alfa API"
vendor: "Альфа-Банк"
industry: "finance"
docsUrl: "https://developers.alfabank.ru/products/alfa-api/documentation"
version: 1
updatedAt: "2026-10-13"
---

# Alfa API

Отрасль: Платежи и финансы. Актуально на 2026-10-13.

API Альфа-Банка для доступа к банковским продуктам из партнёрских сервисов и ERP-систем. Поддерживает B2B-, B2C- и H2H-интеграции: выписки и данные по счетам, платёжные поручения, СБП, профиль организации, вебхуки и другие банковские операции. Основной способ доступа — Alfa ID на базе OAuth 2.0; для части B2B- и H2H-сценариев доступен API Key.

## Охват

Есть:

- Получение и обновление токена Alfa ID по Authorization Code Flow
- Получение выписки по счёту юридического лица
- Создание рублёвого платёжного поручения и проверка его статуса
- Подписка на вебхуки по выписке и входящим платежам СБП

Нет — смотри официальную документацию:

- СБП-переводы, оплата покупок через СБП и Alfa Pay Business
- Выписки файлами, форматы 1С и MT940, обороты по счёту
- Информация по счетам физических лиц и история карточных операций
- Эскроу-счета, номинальные счета и самозанятые
- Электронная подпись, цифровой рубль и транспортное шифрование
- Справки, документы, лимиты, кредитные продукты, зарплатный проект и ЦФА

## Сценарии

### Получить токен Alfa ID

Нужен перед вызовом методов, которые принимают `Bearer {access_token}`. Сценарий заканчивается получением `access_token`, `refresh_token` и `id_token`.

1. Создай интеграцию на Портале разработчика, подключи нужные scopes и получи `client_id` и `client_secret`. Для песочницы установи выданный тестовый TLS-сертификат.
2. Перенаправь пользователя на GET /oidc/authorize с `response_type=code`, `client_id`, `redirect_uri`, `scope` и `state`.
3. Получи `code` в `redirect_uri` и в течение двух минут однократно обменяй его на токены: POST /oidc/token с `grant_type=authorization_code`.
4. Передавай полученный токен как `Authorization: Bearer {access_token}`. По истечении часа вызови POST /oidc/token с `grant_type=refresh_token` и сохрани новую пару токенов.

```bash
curl --location 'https://baas.alfabank.ru/oidc/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code={code}' \
  --data-urlencode 'client_id={client_id}' \
  --data-urlencode 'client_secret={client_secret}' \
  --data-urlencode 'redirect_uri={redirect_uri}' \
  --data-urlencode 'code_verifier={code_verifier}'
```

### Получить выписку по счёту юридического лица

Возвращает операции по расчётному счёту за дату исполнения. Для валютного счёта параметр `curFormat` определяет, вернётся `curTransfer` или `swiftTransfer`.

1. Подключи scope `transactions` и получи доступ через Alfa ID или API Key.
2. Запроси страницу операций: GET /api/jp/v1/statement/transactions с `accountNumber` и `statementDate`.
3. Обработай `transactions` и переходи по страницам с помощью `page` и ссылок `_links`; на одной странице возвращается не больше 1000 объектов.

```bash
curl --location --globoff 'https://baas.alfabank.ru/api/jp/v1/statement/transactions?accountNumber={accountNumber}&statementDate={statementDate}&page={page}&curFormat={curFormat}' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Accept: application/json'
```

### Создать и проконтролировать платёжное поручение

Создаёт рублёвое платёжное поручение по собственному счёту или счёту клиента и позволяет дождаться банковского статуса. Перевод возможен только на счёт резидента РФ.

1. Подключи scope `payment`, получи `access_token` и сгенерируй уникальный `externalId` в формате UUID.
2. Создай документ: POST /api/jp/v2/payments. Чтобы передать электронную подпись вместе с документом, добавь `digestSignatures`; без подписи документ сохраняется в начальном статусе и ожидает подписания в Альфа-Бизнес.
3. Если документ подписан не в запросе, подпиши его в Альфа-Бизнес.
4. Проверяй обработку: GET /api/jp/v2/payments/{externalId}/state. В ответе придут `bankStatus`, `bankComment` и `crucialFieldsHash`.
5. Если нужно убедиться, что реквизиты получателя не изменились до появления выписки, сравни `crucialFieldsHash` из ответов создания и проверки статуса.

```bash
curl --location 'https://sandbox.alfabank.ru/api/jp/v2/payments' \
  --header 'Authorization: Bearer {access-token}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "amount": 1.01,
    "date": "2022-10-11",
    "deliveryKind": "электронно",
    "externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6",
    "operationCode": "01",
    "payeeAccount": "40702810564564564531",
    "payeeBankBic": "040173745",
    "payeeName": "{payeeName}",
    "payerAccount": "40702810102300000001",
    "payerBankBic": "044525593",
    "payerBankCorrAccount": "30101810200000000593",
    "payerInn": "7736576798",
    "payerName": "{payerName}",
    "priority": "5",
    "purpose": "Оплата заказа №1. НДС не облагается"
  }'
```

### Получать уведомления по операциям

Вебхук избавляет от опроса API по выписке или входящим платежам СБП. Сценарий заканчивается активной подпиской и доставкой событий на партнёрский `callbackUri`.

1. Реализуй на своей стороне POST {callbackUri}. Метод должен принимать массив событий и возвращать любой код `2xx` после успешной обработки.
2. Убедись, что домен второго уровня `callbackUri` совпадает с доменом второго уровня `redirect_uri` интеграции, и заранее предоставь банку сетевой доступ к адресу.
3. Создай подписку: POST /api/v1/webhooks с нужным `object`. Для выписки используй `ul_transaction_default`; для входящих платежей СБП — `jp_sbp_incoming_payments`.
4. Проверь подписку: GET /api/v2/webhooks с обязательным `object`; используй `offset` и `limit` для пагинации.
5. При получении событий устраняй дубли по `transactionId` для выписки или `nspkTransactionId` для входящего платежа СБП и всё равно отвечай `2xx` на повторное сообщение.

```bash
curl -X POST https://baas.alfabank.ru/api/v1/webhooks \
  -H 'Authorization: Bearer {token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": "ul_transaction_default",
    "data": {
      "accounts": [
        "40702810800000000001",
        "40702810800000000004",
        "40702810800000000007"
      ]
    },
    "callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
    "version": 1
  }'
```

## Базовые URL

- Боевой хост: `https://baas.alfabank.ru`
- Тестовый хост: `https://sandbox.alfabank.ru`
- Авторизация пользователя в боевой среде: `https://id.alfabank.ru/oidc/authorize`
- Авторизация пользователя в песочнице: `https://id-sandbox.alfabank.ru/oidc/authorize`
- Продукты и сервисы: `https://baas.alfabank.ru/api`
- Продукты и сервисы в песочнице: `https://sandbox.alfabank.ru/api`
- Alfa ID: `https://baas.alfabank.ru/oidc`
- Alfa ID в песочнице: `https://sandbox.alfabank.ru/oidc`

## Авторизация

Тип: OAuth 2.0

Alfa ID использует OAuth 2.0/OIDC. Для Authorization Code Flow нужны `client_id`, `client_secret`, `redirect_uri` и scopes подключённых продуктов; токен передаётся в заголовке `Authorization: Bearer {access_token}`. Alfa ID подходит для всех типов интеграций и продуктов.

Для части B2B- и H2H-методов доступен API Key: передавай `Authorization: ApiKey {API Key}`. Внутренний ключ предназначен для операций по своей компании, внешний — по другой компании; API Key доступен не для всех продуктов, поэтому проверяй описание конкретного метода.

## Методы

### GET /oidc/authorize — Получение кода авторизации

Перенаправляет пользователя в Alfa ID. При успехе возвращает HTTP `302 Found`, а `code` приходит в `Location` на зарегистрированный `redirect_uri`.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-auth-code/v1/get-auth-code

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `response_type` | query | string | да | Значение code |
| `client_id` | query | string | да | Идентификатор сервиса |
| `redirect_uri` | query | string | да | Зарегистрированный URI перенаправления |
| `scope` | query | string | да | Области доступа; минимально необходим openid |
| `state` | query | string | да | Значение для защиты от межсайтовой подделки запросов |
| `nonce` | query | string | нет | Связывает клиентскую сессию с ID Token |
| `code_challenge` | query | string | нет | Код вызова PKCE |
| `code_challenge_method` | query | string | нет | Метод преобразования верификатора: plain или S256 |
| `prompt` | query | string | нет | Управляет повторным входом, согласием и выбором организации |
| `max_age` | query | string | нет | Максимальный возраст аутентификации |

### POST /oidc/token — Получение токена доступа

С `grant_type=authorization_code` обменивает код на `access_token`, `refresh_token` и `id_token`.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-access-token/v1/get-access-token

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Content-Type` | header | string | да | application/x-www-form-urlencoded |
| `Accept` | header | string | да | application/json |
| `grant_type` | body | string | да | authorization_code |
| `code` | body | string | да | Код авторизации |
| `client_id` | body | string | да | Идентификатор сервиса |
| `client_secret` | body | string | да | Секретный ключ сервиса |
| `redirect_uri` | body | string | да | URI перенаправления |
| `code_verifier` | body | string | нет | Верификатор PKCE |

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

```json
{
  "access_token": "eyJraWQiOiJhbGZ...",
  "refresh_token": "13b8230b-b6bf-...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJraWQiOiJhbGZhLXR..."
}
```

### POST /oidc/token — Обновление токена доступа

С `grant_type=refresh_token` возвращает новую пару `access_token` и `refresh_token`.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/token-update/v1/token-update

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Content-Type` | header | string | да | application/x-www-form-urlencoded |
| `Accept` | header | string | да | application/json |
| `grant_type` | body | string | да | refresh_token |
| `refresh_token` | body | string | да | Токен обновления |
| `client_id` | body | string | да | Идентификатор сервиса |
| `client_secret` | body | string | да | Секретный ключ сервиса |

### GET /api/jp/v1/statement/transactions — Получение выписки

Возвращает операции по расчётному счёту за дату. Требует scope `transactions`; принимает Bearer-токен или API Key.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/transactions/articles/statement/v1/statement

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Authorization` | header | string | да | Bearer {access_token} или ApiKey {API Key} |
| `Accept` | header | string | да | application/json |
| `accountNumber` | query | string | да | Номер расчётного счёта |
| `statementDate` | query | string | да | Дата исполнения операции, YYYY-MM-DD |
| `page` | query | integer | нет | Номер страницы; не больше 1000 объектов на странице |
| `curFormat` | query | string | нет | Формат операции по валютному счёту |

### POST /api/jp/v2/payments — Создание рублёвого платёжного поручения

Создаёт поручение по собственному счёту или счёту клиента. Требует scope `payment` и Bearer-токен.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/payments/articles/create/v2/create

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Authorization` | header | string | да | Bearer {access_token} |
| `Accept` | header | string | да | application/json |
| `Content-Type` | header | string | да | application/json |
| `amount` | body | number | да | Сумма платежа |
| `date` | body | string | да | Дата документа, YYYY-MM-DD |
| `externalId` | body | string | да | Идентификатор документа партнёра, UUID |
| `operationCode` | body | string | да | 01 — платёжное поручение |
| `payeeAccount` | body | string | да | Счёт получателя |
| `payeeBankBic` | body | string | да | БИК банка получателя |
| `payeeName` | body | string | да | Полное наименование получателя |
| `payerAccount` | body | string | да | Счёт плательщика |
| `payerBankBic` | body | string | да | БИК банка плательщика |
| `payerBankCorrAccount` | body | string | да | Корсчёт банка плательщика |
| `payerInn` | body | string | да | ИНН плательщика |
| `payerName` | body | string | да | Полное наименование плательщика |
| `priority` | body | string | да | Очерёдность платежа: 1–5 |
| `purpose` | body | string | да | Назначение платежа, не больше 210 символов |
| `digestSignatures` | body | array | нет | Электронные подписи по дайджесту документа |
| `digestSignatures.base64Encoded` | body | string | да | Значение ЭП в Base64, если передан элемент массива |
| `digestSignatures.certificateUuid` | body | string | нет | Серийный номер RSA-сертификата |

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

```json
{
  "amount": 1,
  "bankComment": "",
  "bankStatus": "CREATED",
  "crucialFieldsHash": "3ba4cecce366c3ad8db6edafb71052b37a8a1acc8013ff565879d8711c0c4316",
  "externalId": "22a6dd81-103a-4d3a-8e9b-0ba4b527f5f6"
}
```

### GET /api/jp/v2/payments/{externalId}/state — Получение статуса платёжного поручения

Возвращает банковский статус, комментарий и хэш ключевых реквизитов документа. Требует scope `payment`.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/payments/articles/status/v2/status

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Authorization` | header | string | да | Bearer {access_token} |
| `Accept` | header | string | да | application/json |
| `externalId` | path | string | да | Идентификатор документа партнёра, UUID |

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

```json
{
  "bankStatus": "ACCEPTED",
  "bankComment": "Отправим платёж в течение банковского дня",
  "crucialFieldsHash": "3ba4cecce366c3ad8db6edafb71052b37a8a1acc8013ff565879d8711c0c4316"
}
```

### POST /api/v1/webhooks — Создание вебхука

Создаёт подписку на событие. Требует Bearer-токен и scope события.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/create-webhook/v1/create-webhook

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Authorization` | header | string | да | Bearer {access_token} |
| `Accept` | header | string | да | application/json |
| `Content-Type` | header | string | да | application/json |
| `object` | body | string | да | ul_transaction_default или jp_sbp_incoming_payments |
| `callbackUri` | body | string | да | URL партнёра для доставки вебхука |
| `version` | body | integer | нет | Для указанных объектов поддерживается 1 |
| `data` | body | object | нет | Дополнительные параметры подписки |
| `data.accounts` | body | array of string | нет | Счета для ul_transaction_default; без поля подписка создаётся на все доступные счета |

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

```json
{
  "id": "f9f8c674-7a2a-4297-bdb8-ddd3013de3a3",
  "object": "ul_transaction_default",
  "enabled": true,
  "callbackUri": "https://webhook.partner.ru/api/v1/webhook-events",
  "version": 1
}
```

### GET /api/v2/webhooks — Получение списка вебхуков

Возвращает подписки по типу события с пагинацией.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/get-lists-webhooks/v2/get-lists-webhooks

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `Authorization` | header | string | да | Bearer {access_token} |
| `Accept` | header | string | да | application/json |
| `object` | query | string | да | ul_transaction_default или jp_sbp_incoming_payments |
| `offset` | query | integer | нет | Смещение в результатах |
| `limit` | query | integer | нет | Количество элементов |

### {callbackUri} — Партнёрский метод для получения вебхуков

Метод реализуется партнёром. При успешной обработке должен вернуть любой код `2xx`; тело входящего запроса — массив событий.

Документация: https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/partner-webhook/v1/partner-webhook

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `actionType` | body | string | да | Тип действия с объектом |
| `eventTime` | body | string | да | Время события |
| `object` | body | string | да | Тип объекта события |
| `data` | body | object | да | Данные события |
| `organizationId` | body | string | нет | Идентификатор организации |
| `sub` | body | string | нет | Идентификатор пользователя |

## Нюансы

- В песочнице все вызовы Alfa API должны выполняться с mTLS. Тестовый сертификат и закрытый ключ выдаются после подключения; негативные сценарии песочницы могут отличаться от промышленной среды и спецификации метода.
- Код авторизации действует две минуты и используется один раз. `access_token` действует один час; `refresh_token` — 180 дней и может быть использован не более двух раз, после обновления сохраняй новую пару токенов.
- При `Content-Type: application/x-www-form-urlencoded` в cURL специальные символы `client_secret` нужно экранировать; `redirect_uri` экранировать не нужно. При отправке через Postman в режиме `x-www-form-urlencoded` специальное экранирование не требуется.
- API Key действует один год или бессрочно, но автоматически отзывается, если после последнего запроса прошло более 30 дней.
- `statementDate` допускает даты не ранее пяти лет от первого дня текущего года. Одна страница выписки содержит не больше 1000 операций.
- `externalId` платёжного поручения назначает партнёр. Документация требует UUID; в песочнице для каждого нового теста генерируй уникальное значение.
- Платёж без `digestSignatures` сохраняется в начальном статусе и ожидает подписания в Альфа-Бизнес. Для платёжного поручения по собственному счёту можно передать одну или две подписи.
- Партнёрский обработчик вебхука рекомендуется завершать не более чем за 300 мс. Если приходит `4xx`/`5xx`, ответ не получен за пять секунд или соединение не установлено, банк повторяет доставку через 30 секунд, 5 и 30 минут, 1, 3, 6, 12, 24, 48 и 72 часа.
- Дубли вебхуков по выписке нужно определять по `transactionId`, по входящим платежам СБП — по `nspkTransactionId`; на дубликат всё равно возвращай `2xx`.
- Старые версии endpoint’ов поддерживаются от двух до шести месяцев. Переход на новую версию нужно предварительно тестировать в песочнице.
- Сохраняй заголовок ответа `x-traceid`: при обращении в поддержку банк просит передать `X-TraceId` вместе с датой, временем, URI, заголовками и телом запроса.

## Ошибки

| Код | Описание |
|---|---|
| `400 / invalid_request` | Неверные входные параметры или формат запроса |
| `400 / invalid_client` | Ошибка аутентификации клиента: неверный client_id или client_secret |
| `400 / invalid_grant` | Недействительный код авторизации, refresh token или несоответствие redirect_uri |
| `401 / invalid_token` | Токен истёк, отозван, имеет неверный формат или недействителен |
| `403 / insufficient_scope` | У токена нет scope запрошенного сервиса |
| `403 / access_denied` | Доступ к счёту запрещён |
| `403 / insufficient_privileges` | Недостаточно прав пользователя или нет доступа к callbackUri |
| `404 / unknown_endpoint` | Endpoint не найден или неактивен |
| `404 / not_found` | Платёж не найден или пока не исполнен |
| `409 / conflict` | Платёжное поручение с таким externalId уже существует |
| `429` | Слишком много запросов; тело ответа отсутствует |
| `500 / internal_error` | Внутренняя ошибка сервиса |
| `503` | Сервис недоступен; тело ответа отсутствует |

## Ограничения

- Одновременно доступно не более пяти промышленных интеграций.
- Для файлового обмена по одной временной ссылке можно передать только один файл; несколько файлов нужно поместить в ZIP без пароля или загружать отдельными запросами.
- Максимальный размер файла с MIME-типом `text/plain` — 250 Мбайт, с другим MIME-типом — 60 Мбайт.
- Время жизни файловой ссылки задаётся параметром `X-Amz-Expires` в секундах и отсчитывается от `X-Amz-Date`.
- Числовые лимиты частоты запросов в изученных материалах не указаны, но методы могут возвращать HTTP `429`.

## Источники

- [Введение в Alfa API](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/intro/intro)
- [Начало работы в песочнице](https://developers.alfabank.ru/products/alfa-api/documentation/articles/sandbox/articles/intro/intro)
- [Авторизация](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/authorization/authorization)
- [Получение кода авторизации](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-auth-code/v1/get-auth-code)
- [Получение токена доступа](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/get-access-token/v1/get-access-token)
- [Обновление токена доступа](https://developers.alfabank.ru/products/alfa-api/documentation/articles/alfa-id/articles/acf/articles/token-update/v1/token-update)
- [API Key](https://developers.alfabank.ru/products/alfa-api/documentation/articles/api-key/api-key)
- [Получение выписки](https://developers.alfabank.ru/products/alfa-api/documentation/articles/transactions/articles/statement/v1/statement)
- [Создание рублёвого платёжного поручения](https://developers.alfabank.ru/products/alfa-api/documentation/articles/payments/articles/create/v2/create)
- [Получение статуса платёжного поручения](https://developers.alfabank.ru/products/alfa-api/documentation/articles/payments/articles/status/v2/status)
- [Создание вебхука](https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/create-webhook/v1/create-webhook)
- [Получение списка вебхуков](https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/get-lists-webhooks/v2/get-lists-webhooks)
- [Партнёрский метод для получения вебхуков](https://developers.alfabank.ru/products/alfa-api/documentation/articles/webhooks/articles/partner-webhook/v1/partner-webhook)
- [Пагинация](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/pagination/pagination)
- [Версионирование](https://developers.alfabank.ru/products/alfa-api/documentation/articles/specification/articles/version/version)
- [Требования и ограничения файлового обмена](https://developers.alfabank.ru/products/alfa-api/documentation/articles/secure-file-transfer/articles/intro/intro)

---

Если этого недостаточно — официальная документация: https://developers.alfabank.ru/products/alfa-api/documentation
JSON: https://mcp-everything.ru/api/integrations/alfa-bank-api. MCP: https://mcp-everything.ru/mcp