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.

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

Signature header format: X-VPOS-Signature: sha256=<hex_hmac_sha256>. Compute HMAC over the raw request body with the merchant webhook secret.

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.