VPOS.am Webhooks: қолтаңбаланған төлем оқиғалары

Webhooks

X-VPOS-Signature-ді бастапқы request body бойынша тексеріңіз, event id сақтаңыз, 2xx жауабын тез қайтарыңыз және қайталанған жеткізуді idempotent өңдеңіз.

Нұсқа

API v1

Соңғы тексеру

2026 ж. 16 қыр.

Күй

Келісім жарияланды

Шолу

VPOS.am ашық webhook contract сервер растаған төлем статусымен қолтаңбаланған payment.status_changed оқиғасын жеткізеді.

HTTP / HMAC

Қолтаңба келісімі

Payload талдауынан немесе бизнес күйін өзгертуден бұрын уақыт белгісі бар 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 минут`
Жеткізу таймауты	`5 секунд`
Әдепкі максималды әрекет саны	`8 әрекет`
Қайталау кестесі	`30 секундтан экспоненциалды, ең көбі 1 сағат`
Растау	`2xx жауабын жылдам қайтарыңыз`
Құпияны ротациялау	`Тақырып бірнеше v1 мәнін қамтуы мүмкін. Оқиғаны кемінде бір мән ағымдағы немесе мерзімі өтпеген grace құпиясына сәйкес келсе ғана қабылдаңыз.`
Өңдеу	`Қолтаңбаны тексеріп, event id сақтаңыз, содан кейін side effect әрекеттерін кезекке қойыңыз.`

Ашық оқиға contract-ы

Қазір тек payment.status_changed ашық түрде құжатталған. fiscalStatus data.payment құрамына кіреді, бірақ бөлек ашық fiscal немесе reconciliation events бар екенін білдірмейді.

Қолтаңба және қайта жеткізу

Merchant webhook secret көмегімен <timestamp>.<raw_request_body> үшін HMAC-SHA256 есептеңіз, ескірген timestamp-ті қабылдамаңыз және downstream әрекеттерін idempotent queue арқылы орындаңыз.

Бетті қалай қолдану керек

Webhooks бизнес иесі, әзірлеуші және операциялық командаға бір төлем сценарийін келісуге көмектеседі. Іске қосу алдында sales channel, provider route, webhook жауаптысы, status verification және клиент қолдауы бекітілуі керек.