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

Сценарий из mcp-everything. Актуально на 2026-10-13.

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

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. НДС не облагается"
  }'
```

## Базовые 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 доступен не для всех продуктов, поэтому проверяй описание конкретного метода.

## Методы сценария

### 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"
}
```

## Нюансы

- В песочнице все вызовы 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, заголовками и телом запроса.

## Другие сценарии

- [Получить токен Alfa ID](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/poluchit-token-alfa-id.md)
- [Получить выписку по счёту юридического лица](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/poluchit-vypisku-po-schetu.md)
- [Получать уведомления по операциям](https://mcp-everything.ru/integrations/alfa-bank-api/scenarios/poluchat-uvedomleniya-po-operatsiyam.md)

---

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