VPOS.am Webhooks: signed payment events

Webhooks

Handler-ը պետք է ստուգի X-VPOS-Signature-ը հարցման սկզբնական մարմնի հիման վրա, պահպանի event id-ն, արագ վերադարձնի 2xx և բիզնես գործողությունները կատարի idempotent ձևով։

Տարբերակ

API v1

Վերջին ստուգում

16 սեպ, 2026 թ.

Կարգավիճակ

Պայմանագիրը հրապարակված է

Ընդհանուր նկարագրություն

VPOS.am-ի հանրային webhook պայմանագիրը փոխանցում է սերվերի կողմից հաստատված վճարման կարգավիճակով ստորագրված payment.status_changed իրադարձությունը։

HTTP / HMAC

Ստորագրության պայմանագիր

Մինչ payload-ի մշակումը կամ բիզնես կարգավիճակի փոփոխությունը ստուգեք timestamped HMAC-ը հարցման սկզբնական մարմնի նկատմամբ։

X-VPOS-Event-Id: <event_id>
X-VPOS-Event-Type: payment.status_changed
X-VPOS-Webhook-Timestamp: <unix_timestamp>
X-VPOS-Signature: t=<unix_timestamp>,v1=<current_secret_hmac>[,v1=<grace_secret_hmac>]

signed_payload = <timestamp>.<raw_request_body>
signature = HMAC-SHA256(webhook_secret, signed_payload)

Դաշտ	Պայմանագիր
Վերնագիր	`X-VPOS-Signature`
Ստորագրվող արժեք	`<timestamp>.<raw_request_body>`
Ալգորիթմ	`HMAC-SHA256`
Timestamp-ի թույլատրելի շեղում	`5 րոպե`
Առաքման timeout	`5 վայրկյան`
Փորձերի կանխադրված առավելագույն քանակ	`8 փորձ`
Կրկնափորձերի ժամանակացույց	`Էքսպոնենցիալ՝ 30 վայրկյանից, առավելագույնը 1 ժամ`
Հաստատում	`Արագ վերադարձնել 2xx պատասխան`
Գաղտնիքի ռոտացիա	`Վերնագիրը կարող է պարունակել մի քանի v1 արժեք։ Ընդունեք իրադարձությունը միայն եթե դրանցից առնվազն մեկը համապատասխանում է ընթացիկ կամ դեռ չժամկետանց grace գաղտնիքին։`
Մշակում	`Ստուգել ստորագրությունը, պահել event id-ն, ապա side effect-ները ուղարկել հերթ։`

Հանրային իրադարձության պայմանագիրը

Ներկայիս հանրային merchant պայմանագիրը փաստաթղթավորում է մեկ event type՝ payment.status_changed։ Payload-ի վերին մակարդակը պարունակում է id, type, livemode, createdAt և data դաշտերը, իսկ data.payment-ը՝ վճարման id, merchantOrderId, provider, amountMinor, currency, status և fiscalStatus։

fiscalStatus-ը վճարման projection-ի դաշտ է և առանձին հանրային fiscal կամ reconciliation event-ի խոստում չէ։ Նոր event type-ը հասանելի է համարվում միայն հրապարակված OpenAPI պայմանագրում հայտնվելուց հետո։

Ստորագրության ստուգում

X-VPOS-Signature-ն ունի t=<unix_timestamp>,v1=<hex_hmac_sha256> ձևաչափը։ Ռոտացիայի ժամանակ այն կարող է պարունակել մի քանի v1 արժեք․ event-ը ընդունվում է, եթե թեկնածուներից որևէ մեկը անվտանգ համընկնում է ընթացիկ կամ անցումային շրջանում դեռ գործող գաղտնիքի հետ։ HMAC-SHA256-ը հաշվարկվում է մինչև JSON փոխակերպումը ստացված <timestamp>.<raw_request_body> տողի ճշգրիտ byte-երով։

Անվավեր ստորագրությունը կամ ստանդարտ 5 րոպեանոց թույլատրելի միջակայքից դուրս timestamp-ը պետք է մերժել և գրանցել security log-ում՝ առանց order, invoice կամ CRM status փոխելու։ Առաքումը ներառում է նաև X-VPOS-Event-Id, X-VPOS-Event-Type և X-VPOS-Webhook-Timestamp header-ները։

Կրկնակի առաքում և downstream սխալներ

VPOS.am-ը կարող է նույն event-ը մեկից ավելի անգամ առաքել, ուստի event id-ն և մշակման արդյունքը պետք է պահպանել մինչև side effects սկսելը։ Կրկնակի հարցումը պետք է վերադարձնի անվտանգ 2xx՝ առանց երկրորդ charge, order, receipt կամ CRM action ստեղծելու։

Endpoint-ը պետք է ստանդարտ 5 վայրկյան timeout-ի ընթացքում վերադարձնի 2xx, իսկ CRM, ERP, e-mail և այլ downstream գործողությունները կատարվեն queue-ով։ Լռելյայն VPOS.am-ը կատարում է մինչև 8 փորձ՝ սկսելով 30 վայրկյանից, exponential backoff-ով և առավելագույնը 1 ժամ ընդմիջմամբ։

Հաճախակի հարցեր

Ո՞ր webhook event-ն է ներառված հանրային contract-ում։

Ներկայում հանրային ձևով փաստաթղթավորված է միայն payment.status_changed-ը։ fiscalStatus-ը կարող է լինել data.payment-ի ներսում, սակայն առանձին fiscal և reconciliation events հասանելի չեն, քանի դեռ հրապարակված չեն OpenAPI-ում։

Ինչպե՞ս ստուգել X-VPOS-Signature-ը։

HMAC-SHA256-ը հաշվարկեք <timestamp>.<raw_request_body> տողի ճշգրիտ byte-երով և անվտանգ համեմատեք header-ի բոլոր v1 արժեքների հետ․ ռոտացիայի ժամանակ վավեր է ընթացիկ կամ անցումային շրջանում դեռ գործող գաղտնիքի ցանկացած համընկնում։ Կիրառեք timestamp-ի 5 րոպեանոց միջակայքը և մինչև հաջող ստուգումը order-ը մի փոխեք։