Հանրային 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-ի:

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

Signature header format: X-VPOS-Signature: sha256=<hex_hmac_sha256>: HMAC-ը հաշվվում է raw request body-ի վրա merchant webhook secret-ով:

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: