Public API for safe payment integrations.

Quick start

The minimum integration has three server-side parts: create a payment session, redirect the buyer to hosted checkout, then confirm the final status through status lookup or a signed 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"
    }
  }'

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.

CMS and Tilda onboarding

For CMS channels such as Tilda, WooCommerce, OpenCart or CS-Cart, VPOS.am should be the server-side payment layer. The website receives only channel settings and public redirect URLs; bank provider secrets stay in the 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.

Endpoints

Webhooks

Webhook delivery is configured per merchant 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_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 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 reject stale timestamps.

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 the VPOS payment id, merchant order id, amount 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.

Access request

For pilot or production access, send your company name, website, integration type, expected provider, currencies, callback URL and contact person to info@vpos.am.

Before production, VPOS.am reviews merchant identity, domain ownership, callback security, test payment results, refund and reconciliation process, and support ownership.