VPOS.am Webhooks: رویدادهای پرداخت امضاشده

Webhooks

X-VPOS-Signature را روی request body اصلی بررسی کنید، event id را ذخیره کنید، سریعاً 2xx برگردانید و تحویل تکراری را به‌صورت idempotent پردازش کنید.

نسخه

API v1

آخرین بازبینی

۲۵ شهریور ۱۴۰۵

وضعیت

قرارداد منتشر شده

نمای کلی

قرارداد عمومی webhook در VPOS.am رویداد امضاشده payment.status_changed را با وضعیت پرداخت تأییدشده در سمت سرور تحویل می‌دهد.

HTTP / HMAC

قرارداد امضا

پیش از پردازش payload یا تغییر وضعیت کسب‌وکار، HMAC دارای timestamp را روی بدنه خام درخواست بررسی کنید.

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	`۵ دقیقه`
مهلت تحویل	`۵ ثانیه`
حداکثر تلاش پیش‌فرض	`۸ تلاش`
برنامه تلاش مجدد	`نمایی از ۳۰ ثانیه، با سقف ۱ ساعت`
تأیید دریافت	`یک پاسخ 2xx را سریع برگردانید`
چرخش راز	`هدر می‌تواند چند مقدار v1 داشته باشد. رویداد را فقط وقتی بپذیرید که دست‌کم یکی با راز فعلی یا راز مهلت‌دار منقضی‌نشده مطابقت داشته باشد.`
پردازش	`امضا را بررسی کنید، event id را ذخیره کنید و سپس side effectها را در صف قرار دهید.`

قرارداد عمومی event

در حال حاضر فقط payment.status_changed به‌صورت عمومی مستند شده است. fiscalStatus بخشی از data.payment است، اما به معنی وجود eventهای عمومی جداگانه برای fiscal یا reconciliation نیست.

Signature و تحویل مجدد

با merchant webhook secret مقدار HMAC-SHA256 را برای <timestamp>.<raw_request_body> محاسبه کنید، timestamp قدیمی را رد کنید و downstream actions را از طریق queue ایمن و idempotent انجام دهید.

نحوه استفاده از این صفحه

Webhooks به هماهنگ شدن سناریوی پرداخت میان مالک کسب‌وکار، تیم توسعه و عملیات کمک می‌کند. پیش از راه‌اندازی باید کانال فروش، مسیر provider، مسئول webhook، بررسی وضعیت و پشتیبانی مشتری پس از پرداخت مشخص شود.