VPOS.am Webhooks: signed payment events

Webhooks

შეამოწმეთ X-VPOS-Signature საწყისი request body-ით, შეინახეთ event id, სწრაფად დააბრუნეთ 2xx და repeated delivery დაამუშავეთ idempotent-ად.

ვერსია

API v1

ბოლო შემოწმება

16 სექ. 2026

სტატუსი

კონტრაქტი გამოქვეყნებულია

მიმოხილვა

VPOS.am-ის საჯარო webhook contract აწვდის ხელმოწერილ payment.status_changed event-ს server-side დადასტურებული payment status-ით.

HTTP / HMAC

ხელმოწერის კონტრაქტი

Payload-ის დამუშავებამდე ან ბიზნეს-სტატუსის შეცვლამდე გადაამოწმეთ timestamp-იანი 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-ები რიგში ჩასვით.`

საჯარო event contract

ამჟამად საჯაროდ დოკუმენტირებულია მხოლოდ payment.status_changed. fiscalStatus შედის data.payment-ში, მაგრამ არ ნიშნავს ცალკე საჯარო fiscal ან reconciliation events-ის არსებობას.

Signature და repeated delivery

Merchant webhook secret-ით გამოთვალეთ HMAC-SHA256 <timestamp>.<raw_request_body>-ისთვის, უარყავით მოძველებული timestamp და downstream actions შეასრულეთ idempotent queue-ით.

როგორ გამოვიყენოთ ეს გვერდი

Webhooks ეხმარება ბიზნესის მფლობელს, დეველოპერს და ოპერაციულ გუნდს ერთ payment scenario-ზე შეთანხმებაში. გაშვებამდე უნდა დაფიქსირდეს sales channel, provider route, webhook-ის პასუხისმგებელი, status verification და customer support flow. ასევე საჭიროა test payment-ის, refund-ის და reconciliation-ის შედეგების ერთად გადამოწმება.