Հանրային API անվտանգ payment integrations-ի համար:

Quick start

Նվազագույն ինտեգրացիան ունի երեք server-side մաս. ստեղծել payment session, buyer-ին redirect անել hosted checkout, հետո final status-ը հաստատել status lookup-ով կամ 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"
    }
  }'

Browser return URL-ը payment proof չէ: Դա միայն UI event է: Fulfillment-ը պետք է սպասի server-side verification-ի կամ signed webhook event-ի:

CMS եւ Tilda onboarding

CMS channels-ի համար, օրինակ Tilda, WooCommerce, OpenCart կամ CS-Cart, VPOS.am-ը պետք է մնա server-side payment layer: Website-ը ստանում է միայն channel settings եւ public redirect URLs, իսկ bank provider secrets-ը մնում է VPOS.am runtime-ում:

• Tilda-ի համար VPOS.am-ը գեներացնում է merchant login, HMAC secret եւ Universal payment gateway checkout URL. Bank ClientID, login եւ password-ը Tilda-ում չեն մուտքագրվում:
• Live mode-ից առաջ operator-ը ստուգում է website readiness, signed checkout payloads, provider route mapping, callback handling եւ sandbox test payment:
• Production switch-ը մնում է controlled operator action merchant contract, provider route եւ test evidence confirmation-ից հետո:

Endpoints

Webhooks

Webhook delivery-ն կարգավորվում է յուրաքանչյուր merchant-ի համար onboarding-ի ընթացքում: Ձեր endpoint-ը պետք է verify անի HMAC signature-ը, պահի event id-ն, արագ պատասխանի եւ business side effects-ը տեղափոխի 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>: HMAC-SHA256-ը հաշվվում է <timestamp>.<raw_request_body> string-ի վրա merchant webhook secret-ով, հին timestamps-ը պետք է մերժվեն:

Idempotency

Օգտագործեք Idempotency-Key retryable operations-ի համար, օրինակ payment-session creation: Պահեք key-ը order-ի եւ payment attempt-ի հետ: Network retry-ն չպետք է ստեղծի երկրորդ payable order կամ invoice:

• Օգտագործեք deterministic key յուրաքանչյուր order payment attempt-ի համար, ոչ թե random key յուրաքանչյուր retry-ի համար:
• Տարբեր user-initiated attempts-ի համար պահեք տարբեր keys:
• Միասին log արեք VPOS payment id, merchant order id, amount եւ currency:

Errors

Security rules

• Երբեք մի բացեք merchant bearer tokens, webhook secrets կամ provider credentials frontend code-ում:
• Օգտագործեք միայն HTTPS եւ verify արեք server certificates backend clients-ում:
• Payment-ը final համարեք միայն server-side status confirmation-ից հետո:
• Validate արեք amount, currency եւ merchant order id մինչ order, CRM կամ ERP state փոփոխելը:
• Պահեք webhook event ids եւ reject արեք duplicate side effects:
• Log արեք failed signature checks եւ unexpected status transitions առանց unnecessary personal data պահելու:

Այս public page-ը դիտավորյալ չի ներառում production tokens, internal console routes, private provider callbacks, database details կամ bank credentials:

Access request

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: