Public API for secure payment integration.

Authentication and request format

Merchant API calls use an installation-scoped bearer token. Its server-side binding selects the merchant, channel, mode, provider route and credential; request bodies cannot override that binding.

Base URL

https://api.vpos.am

Authorization

Authorization: Bearer <merchant_api_token>

Request body

application/json

API version

v1

Send credentials only over HTTPS from a trusted backend. Never place a merchant token in a browser bundle, mobile application or public site-builder setting.

Quick start

A minimal integration has three server-side steps: create a payment session, redirect the buyer to the returned checkoutUrl, and confirm the final status through a signed webhook or status lookup.

1. Create a payment session with a stable merchant order reference and Idempotency-Key.
2. Redirect the buyer to the checkoutUrl returned by VPOS.am.
3. Fulfill the order only after a signed webhook or server-side status lookup confirms paid.

The browser return URL is not proof of payment. Treat it as a user-interface event only. Fulfillment must wait for server-side verification or a signed webhook event.

Core endpoints

These cards cover the primary merchant payment flow. The complete list of public operations and schemas is available in the OpenAPI 3.1 specification.

No endpoints match this filter.

Webhooks

Webhook delivery is configured per merchant installation during onboarding. Your endpoint should verify the HMAC signature, persist the event id, return quickly and process business side effects in a queue.

{
  "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"
    }
  }
}

Signature header format: X-VPOS-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256>. Compute HMAC-SHA256 over <timestamp>.<raw_request_body> with the merchant webhook secret and apply the default five-minute timestamp tolerance. During secret rotation the header may contain multiple v1 values; accept the event when any candidate securely matches a current or still-valid grace-period secret. Delivery also includes X-VPOS-Event-Id, X-VPOS-Event-Type and X-VPOS-Webhook-Timestamp.

Idempotency

Use Idempotency-Key for retryable operations such as payment-session creation. Store the key with the order and payment attempt in your system. A network retry must not create a second payable order or invoice.

• Use a deterministic key per order payment attempt, not a random key for every retry.
• Keep separate keys for separate user-initiated attempts.
• Log paymentId, merchantOrderId, amountMinor, and currency together.

Errors

Security rules

• Never expose merchant bearer tokens, webhook secrets or provider credentials in frontend code.
• Use HTTPS only and verify server certificates in backend clients.
• Accept a payment as final only after server-side status confirmation.
• Validate amount, currency and merchant order id before changing order, CRM or ERP state.
• Store webhook event ids and reject duplicate side effects.
• Log failed signature checks and unexpected status transitions without storing unnecessary personal data.

This public page intentionally does not include production tokens, internal console routes, private provider callbacks, database details or bank credentials.

CMS and site builders

With Tilda, WooCommerce, OpenCart, and CS-Cart, VPOS.am remains the server-side technical integration layer. The site receives only channel settings and public redirect URLs; bank or licensed-provider credentials remain inside the protected VPOS.am runtime.

• Tilda uses a merchant login, HMAC secret and Universal payment gateway checkout URL generated by VPOS.am; bank ClientID, login and password are not entered into Tilda.
• Before live mode, the operator verifies website readiness, signed checkout payloads, provider route mapping, callback handling and a sandbox test payment.
• The production switch remains a controlled operator action after the merchant contract, provider route and test evidence are confirmed.

Request access

To request pilot or production access, email info@vpos.am with your company name, website, integration type, expected bank or licensed payment provider, currencies, callback URL, and technical contact.

Before production access is approved, VPOS.am verifies merchant identity, domain ownership, callback security, test-payment results, refund and reconciliation procedures, and support responsibilities.