Alfa API API

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

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

Охват

Есть:

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

Сценарии

Получить токен 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 и сохрани новую пару токенов.
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 объектов.
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 из ответов создания и проверки статуса.
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 на повторное сообщение.
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

Авторизация

Тип: 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

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

{
  "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-сертификата

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

{
  "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

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

{
  "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; без поля подписка создаётся на все доступные счета

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

{
  "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 нет Идентификатор пользователя

Нюансы

Ошибки

Код Описание
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 Сервис недоступен; тело ответа отсутствует

Ограничения

Источники

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