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

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

Минимальная интеграция состоит из трех server-side частей: создать платежную сессию, перенаправить покупателя на hosted checkout, затем подтвердить финальный статус через status lookup или подписанный webhook.

curl -X POST https://api.vpos.am/v1/payment-sessions \
  -H "Authorization: Bearer <merchant_api_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-pay-attempt-1" \
  -d '{
    "merchantOrderId": "order-1001",
    "amountMinor": 15000,
    "currency": "AMD",
    "provider": "manual",
    "returnUrl": "https://merchant.example/payments/return",
    "customer": {
      "email": "buyer@example.com",
      "phone": "+37400000000",
      "name": "Test Buyer"
    },
    "metadata": {
      "source": "custom-backend"
    }
  }'

Browser return URL не является доказательством оплаты. Это только UI-событие. Выдача товара или изменение заказа должны ждать server-side verification или подписанного webhook event.

CMS и Tilda onboarding

Для CMS-каналов, включая Tilda, WooCommerce, OpenCart и CS-Cart, VPOS.am должен оставаться server-side платежным слоем. Сайт получает только настройки канала и публичные redirect URL, а банковские реквизиты остаются в runtime VPOS.am.

• Для Tilda vPOS.am генерирует merchant login, HMAC secret и checkout URL для Universal payment gateway; банковские ClientID, login и password не вводятся в Tilda.
• Перед live оператор проверяет готовность сайта, подписанный checkout payload, provider route mapping, callback handling и sandbox test payment.
• Production switch остается контролируемым действием оператора после подтверждения договора merchant, provider route и test evidence.

Endpoints

Webhooks

Webhook delivery настраивается для каждого merchant при onboarding. Ваш endpoint должен проверить HMAC signature, сохранить event id, быстро ответить и перенести бизнес-эффекты в очередь.

{
  "id": "evt_01hxxexample",
  "type": "payment.status_changed",
  "createdAt": "2026-05-25T08:00:00.000Z",
  "data": {
    "payment": {
      "id": "pay_01hxxexample",
      "merchantOrderId": "order-1001",
      "amountMinor": 15000,
      "currency": "AMD",
      "status": "paid"
    }
  }
}

Формат signature header: X-VPOS-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256>. HMAC-SHA256 считается по строке <timestamp>.<raw_request_body> с merchant webhook secret; старые timestamps нужно отклонять.

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

Используйте Idempotency-Key для retryable operations, например создания payment session. Храните ключ вместе с order и payment attempt. Network retry не должен создавать второй payable order или invoice.

• Используйте deterministic key для каждой order payment attempt, а не новый random key на каждый retry.
• Для разных user-initiated attempts используйте разные ключи.
• Логируйте VPOS payment id, merchant order id, amount и currency вместе.

Ошибки

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

• Никогда не раскрывайте merchant bearer tokens, webhook secrets или provider credentials во frontend code.
• Используйте только HTTPS и проверяйте server certificates в backend clients.
• Считайте платеж финальным только после server-side confirmation.
• Проверяйте amount, currency и merchant order id перед изменением order, CRM или ERP state.
• Сохраняйте webhook event ids и не допускайте повторных side effects.
• Логируйте failed signature checks и неожиданные status transitions без лишних персональных данных.

Эта публичная страница намеренно не содержит production tokens, internal console routes, private provider callbacks, database details или bank credentials.

Запрос доступа

Для pilot или production access отправьте company name, website, integration type, expected provider, currencies, callback URL и contact person на info@vpos.am.

Перед production VPOS.am проверяет merchant identity, domain ownership, callback security, test payment results, refund/reconciliation process и support ownership.