Публичный API для безопасной интеграции платёжных сценариев.

Авторизация и формат запросов

Запросы к API продавца авторизуются с помощью Bearer-токена, привязанного к конкретной установке. Эта серверная привязка определяет продавца, канал, режим, маршрут провайдера и учётные данные; тело запроса не может её переопределить.

Базовый URL

https://api.vpos.am

Авторизация

Authorization: Bearer <merchant_api_token>

Тело запроса

application/json

Версия API

v1

Передавайте учётные данные только по HTTPS с доверенного сервера. Не размещайте токен продавца в браузерной сборке, мобильном приложении или публичных настройках конструктора сайтов.

Быстрый старт

Минимальная интеграция состоит из трёх серверных шагов: создать платёжную сессию, перенаправить покупателя по полученному checkoutUrl, затем подтвердить итоговый статус через API или подписанное Webhook-событие.

1. Создайте платёжную сессию с постоянным значением merchantOrderId и заголовком Idempotency-Key.
2. Перенаправьте покупателя на checkoutUrl, который вернул VPOS.am.
3. Исполняйте заказ только после статуса paid, подтверждённого Webhook-событием или серверным запросом статуса.

Возврат покупателя по returnUrl не подтверждает оплату. Это только событие интерфейса. Выдавать товар или менять статус заказа можно после серверной проверки или подписанного Webhook-события.

Основные методы API

Карточки описывают основной платёжный сценарий продавца. Полный перечень публичных операций и схем приведён в спецификации OpenAPI 3.1.

По этому фильтру методы не найдены.

Webhook-события

Доставка Webhook-событий настраивается отдельно для каждой установки продавца. Ваша конечная точка API должна проверить HMAC-подпись, сохранить идентификатор события, быстро вернуть ответ и передать обработку бизнес-операций в очередь.

{
  "id": "evt_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "type": "payment.status_changed",
  "livemode": false,
  "createdAt": "2026-05-25T08:00:00.000Z",
  "trigger": "provider_callback",
  "data": {
    "payment": {
      "id": "pay_abcdef012345678901",
      "merchantOrderId": "order-1001",
      "provider": "ameriabank_vpos",
      "amountMinor": 15000,
      "currency": "AMD",
      "status": "paid",
      "fiscalStatus": "not_required"
    }
  }
}

Формат заголовка подписи: X-VPOS-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256>. Рассчитайте HMAC-SHA256 для строки <timestamp>.<raw_request_body> с секретом Webhook продавца и применяйте стандартный допуск timestamp в пять минут. Во время ротации секрета заголовок может содержать несколько значений v1; принимайте событие, если любой кандидат безопасно совпал с текущим или ещё действующим секретом переходного периода. Доставка также передаёт X-VPOS-Event-Id, X-VPOS-Event-Type и X-VPOS-Webhook-Timestamp.

Идемпотентность

Используйте Idempotency-Key для повторяемых операций, включая создание платежной сессии. Храните ключ вместе с заказом и попыткой оплаты: повтор сетевого запроса не должен создавать второй счёт или платёж.

• Используйте стабильный ключ для каждой попытки оплаты заказа, а не новый случайный ключ при каждом повторе.
• Для отдельных попыток, запущенных пользователем, создавайте разные ключи.
• Логируйте вместе paymentId, merchantOrderId, amountMinor и currency.

Ошибки

Правила безопасности

• Не раскрывайте Bearer-токен продавца, секрет подписи Webhook и учётные данные провайдера в клиентском коде.
• Используйте только HTTPS и проверяйте сертификаты сервера в серверных клиентах.
• Считайте платёж завершённым только после серверного подтверждения статуса.
• Проверяйте amount, currency и merchantOrderId перед изменением заказа, CRM или ERP.
• Сохраняйте идентификаторы Webhook-событий и исключайте повторное выполнение бизнес-операций.
• Логируйте ошибки проверки подписи и неожиданные переходы статуса без лишних персональных данных.

Эта публичная страница намеренно не содержит рабочие токены, внутренние маршруты консоли, закрытые обратные вызовы провайдеров, сведения о базе данных или банковские учётные данные.

CMS и конструкторы сайтов

Для Tilda, WooCommerce, OpenCart и CS-Cart VPOS.am остаётся техническим серверным интеграционным слоем. Сайт получает только настройки канала и публичные URL перенаправления; учётные данные банка или лицензированного платёжного провайдера хранятся только в защищённой среде VPOS.am.

• Для Tilda VPOS.am выдаёт логин продавца, секрет HMAC и URL оплаты через Universal payment gateway; банковские ClientID, login и password в Tilda не вводятся.
• Перед включением рабочего режима оператор проверяет готовность сайта, подпись данных платёжной формы, привязку маршрута провайдера, обработку обратного вызова и тестовый платёж в песочнице.
• Переход в рабочую среду выполняет оператор только после подтверждения договора продавца с банком или лицензированным платёжным провайдером, маршрута провайдера и результатов тестирования.

Получение доступа

Чтобы запросить пилотный доступ или доступ к рабочей среде, отправьте на info@vpos.am название компании, адрес сайта, тип интеграции, предполагаемый банк или лицензированного платёжного провайдера, валюты, URL обратного вызова и данные технического контактного лица.

Перед выдачей доступа к рабочей среде VPOS.am проверяет данные продавца, владение доменом, безопасность URL обратного вызова, результаты тестового платежа, процессы возврата и сверки, а также ответственных за поддержку.