Беларусбанк: API для работы с платежами

Обзор и возможности

Беларусбанк предоставляет интернет-эквайринг и платежный шлюз, который можно подключить через API. Для бизнеса это означает: онлайн-оплата банковскими картами, подтверждение через 3‑D Secure, возвраты и сторнирования, а также уведомления о событиях. Если вы строите интернет-магазин, подписочный сервис или маркетплейс, API для работы с платежами в Беларусбанке поможет автоматизировать весь цикл — от создания заказа до сверки поступлений.

Ключевые задачи, которые решает Беларусбанк API платежи:

прием платежей по картам с поддержкой 3‑D Secure;
авторизация (блокировка средств) и последующее списание (capture);
частичный и полный возврат платежа Беларусбанк;
вебхуки Беларусбанк для уведомлений о статусах;
сохранение карты и рекуррентные списания (где доступно);
инструменты для сверки и отчетности.

Для быстрого старта ознакомьтесь с основами интеграции и определите подходящий платежный сценарий.

![Diagram: Belarusbank payment gateway components]

Получить CloudPayments бесплатно

Платежный флоу

Ниже — типичный поток эквайринга Беларусбанк API. Конкретные шаги и названия методов могут отличаться в зависимости от договора и настроек.

Создание заказа: ваш бэкенд инициирует платеж — сумма, валюта, описание, idempotency-key.
Сбор карточных данных: на хостed‑странице банка или через защищенный SDK/токенизацию.
3‑D Secure Беларусбанк: аутентификация держателя карты (frictionless или challenge).
Авторизация: банк-эмитент блокирует средства на карте клиента.
Списание (capture) или автоматическое завершение: мгновенно либо отложенно.
Вебхуки: ваш сервер принимает асинхронные уведомления об успешной оплате, отмене, возврате.
Сверка: формируете отчеты и автоматизируете бухучет.

![Diagram: Payment flow via Belarusbank API]

Типовые операции API

Ниже — обзор распространенных операций, которые встречаются при работе с эквайрингом Беларусбанка.

Операция	Когда использовать	Параметры/заметки
Создание платежа (init)	Перед началом оплаты	amount, currency, orderId, description, returnUrl, idempotency-key
Проверка статуса (get)	Для получения актуального статуса	paymentId или orderId, подпись/токен
Подтверждение списания (capture)	После предварительной авторизации	paymentId, captureAmount (опционально частичный)
Отмена авторизации (void)	До списания, если заказ отменен	paymentId, reason
Возврат (refund)	После списания — полный/частичный	paymentId, refundAmount, reason
Регистрировать карту/токен (card-on-file)	Для подписок/автоплатежей	customerId, consent, tokenizationFlow
Повторная отправка вебхука	Если ваш endpoint временно недоступен	eventId/attempt, подпись

Статусы оплаты в API обычно отражают жизненный цикл транзакции:

Статус	Значение
created/pending	Платеж инициирован, ожидание ввода карты/3DS
authorized	Средства успешно заблокированы
captured/succeeded	Списание завершено, платеж успешен
canceled/voided	Авторизация отменена
refunded	Выполнен возврат (полный или частичный)
failed	Ошибка проведения операции

Безопасность и аутентификация

Платежные интеграции требуют повышенной безопасности. В типовой схеме используются:

TLS 1.2+ и проверка сертификатов;
серверная аутентификация по ключам/сертификатам или по HMAC‑подписи запросов; иногда могут применяться OAuth2 client_credentials — выбирайте то, что указано в договоре;
белые списки IP и mTLS для повышения стойкости канала;
минимизация обработки карточных данных вашим сервером (хостed‑пейдж/SDK), чтобы снизить требования PCI DSS.

Ознакомьтесь с практиками 3DS и PCI в разделе PCI DSS и 3‑D Secure. При проектировании API‑вызовов закладывайте идемпотентность и повторяемость, особенно для сетево‑чувствительных операций — подробнее в гайде вебхуки и идемпотентность.

3‑D Secure

3‑D Secure Беларусбанк — критический слой защиты, который снижает риск мошенничества и чарджбеков. В современном потоке 3DS2 возможны два сценария:

Frictionless: банк выпускающий карту не требует дополнительного подтверждения; клиент платит без лишних шагов.
Challenge: клиент подтверждает операцию через SMS‑код/приложение банка/биометрию.

Рекомендации интеграции:

передавайте максимум контекстных данных (email, адрес доставки, device info) для повышения доли frictionless;
закладывайте таймауты на challenge и повторную инициализацию при истечении сессии;
корректно обрабатывайте коды результата 3DS и переводите заказ в «ожидает подтверждения», если исход не ясен.

Подробнее — в материале PCI DSS и 3‑D Secure.

Вебхуки и идемпотентность

Вебхуки Беларусбанк используются для асинхронных уведомлений: успешная оплата, отмена, refund, chargeback, периодические списания. Хорошая практика — принимать вебхуки даже при локальных сбоях и подтверждать обработку 2xx‑ответом.

Что важно предусмотреть:

подпись уведомлений (HMAC/сертификат) и проверку целостности;
повторы от банка: делайте обработку идемпотентной и храните eventId;
связь событий с заказами по вашему уникальному orderId;
отдельный endpoint для тестовой среды.

См. паттерны вебхуков и идемпотентности и практики ошибок и мониторинга.

Sandbox и тестирование

Для безопасного испытания интеграции используется sandbox Беларусбанк. В песочнице вы:

проверяете сценарии 3DS (успех/отказ), авторизацию и списание;
репетируете отмены и частичные возвраты;
тестируете вебхуки, авто‑ретраи и идемпотентность;
валидируете корректность редиректов/returnUrl.

Помните: набор тестовых карт и ответа кодов может отличаться от продакшена. Не смешивайте real‑keys с тестовыми. Подробности — в разделе Sandbox и тестовые сценарии.

Возвраты и сторнирования

Возврат платежа Беларусбанк возможен как полный, так и частичный. Два смежных действия важно не путать:

Сторнирование (void) — отмена авторизации до списания. Хорошо подходит при отмене заказа сразу после оплаты.
Возврат (refund) — после списания. Можно делать несколько частичных возвратов до суммы операции.

Практические советы:

фиксируйте причины возврата для аналитики и антифрода;
соблюдайте временные окна (они зависят от правил эквайринга);
синхронизируйте статусы через вебхуки и ручные проверки.

Читайте подробности о стратегиях в разделе возвраты и сторнирования.

Рекуррентные платежи

Для подписок и регулярных списаний полезны токены карты (card‑on‑file) и разделение CIT/MIT. В эквайринг Беларусбанк API обычно предусмотрен сценарий:

первичный платеж с явным согласием клиента;
сохранение токена (без хранения PAN у мерчанта);
последующие списания по расписанию с уведомлениями клиента.

Смотрите паттерны рекуррентных подписок и убедитесь, что информирование клиента соответствует требованиям локального регулирования.

Мобильная интеграция

Мобильные приложения повышают конверсию, если использовать нативные платежные формы и SDK. Проверьте, доступен ли у банка SDK/hosted UI для iOS/Android, чтобы не касаться карточных данных на вашем бэкенде и снизить нагрузку PCI DSS. Рекомендации по встраиванию — в разделе SDK для мобильных.

Сверка и отчеты

Сверка — ключ к прозрачному учету. Организуйте ежедневный обмен реестрами и автоматическую консолидацию:

сопоставление ордеров с транзакциями банка;
проверка сумм, комиссий, статусов и дат поступления;
формирование актов и выгрузок для бухгалтерии (CSV/Excel/API).

Начните с гайда Сверка и аналитика, чтобы построить надежный pipeline отчетности.

Мониторинг и надежность

Инциденты в платежах дорого обходятся. Введите метрики:

доля успеха по картам и по банкам-эмитентам;
распределение причин отказов (3DS, insufficient funds, do not honor);
время ответа API и конверсия по шагам флоу;
отложенные вебхуки и ретраи.

Постройте алерты и дашборды — см. Ошибки и мониторинг. Для устойчивости добавляйте:

экспоненциальные повторы с джиттером;
таймауты и Circuit Breaker;
идемпотентность всех «денежных» методов.

Сравнение и альтернативы

Выбирая поставщика, сравните прямой эквайринг банка и агрегаторов. Прямой канал дает контроль и тарифы, агрегаторы — скорость запуска и больше способов оплаты. Материал для оценки — Банки vs агрегаторы.

Сравните также другие интеграции на сайте:

Частые вопросы и советы

Какой сценарий выбрать: авторизация+capture или сразу списание? Если логистика долгая — используйте двухстадийный флоу с capture, чтобы не списывать до отгрузки.
Можно ли принимать разные валюты? Чаще всего базовая валюта — BYN; поддержка иных валют зависит от договора и настроек процессинга — уточняйте у банка.
Что делать при неоднозначном ответе 3DS? Переводите заказ в «ожидает подтверждения» и ждите вебхук либо выполняйте безопасный повтор с тем же idempotency‑key.
Как организовать rollback? При ошибке после авторизации инициируйте void; если списание уже прошло — делайте refund.
Где посмотреть коды ошибок? Ориентируйтесь на документацию и стройте карту сопоставления кода/сообщения/совета для оператора.

Итоги и следующий шаг

Беларусбанк API для работы с платежами — надежная основа для онлайн‑кассы, подписок и маркетплейсов. Используйте 3‑D Secure Беларусбанк, аккуратно настраивайте вебхуки Беларусбанк и тестируйте все кейсы в sandbox Беларусбанк. Далее:

начните с Основ интеграции;
подготовьте план тестов в Sandbox;
заложите безопасность и 3DS по гайду PCI DSS и 3‑D Secure.

Готовы внедрять эквайринг Беларусбанк API или хотите сравнить варианты? Перейдите по ссылкам из статьи и соберите оптимальную архитектуру под ваш продукт.

Получить CloudPayments бесплатно