Публичный 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.

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",
  "payment": {
    "id": "pay_01hxxexample",
    "merchantOrderId": "order-1001",
    "amountMinor": 15000,
    "currency": "AMD",
    "status": "paid"
  }
}

Формат signature header: X-VPOS-Signature: sha256=<hex_hmac_sha256>. HMAC считается по raw request body с merchant webhook secret.

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

Используйте 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.