تکمیل پرداخت رمزارزی توسط مشتری فقط آغاز فرایند پرداخت است. وب‌سایت یا اپلیکیشن شما هنوز باید نتیجه را تأیید کند، سفارش درست را به‌روزرسانی کند، به مشتری اطلاع دهد و مشخص کند که آیا انجام سفارش می‌تواند آغاز شود یا نه. وب‌هوک‌های OxaPay با ارسال مستقیم به‌روزرسانی‌های وضعیت پرداخت به سرور شما، این کارها را ممکن می‌کنند.
یکپارچه‌سازی قابل‌اعتماد وب‌هوک چیزی فراتر از دریافت یک اعلان است. چنین یکپارچه‌سازی‌ای اصالت کال‌بک را بررسی می‌کند، آن را به پرداخت درست نسبت می‌دهد، دریافت تکراری را به‌شکلی ایمن مدیریت می‌کند و هنگام تأخیر یا ابهام در اطلاعات، وضعیت را استعلام می‌گیرد. این راهنما فرایند کامل را با زبانی کاربردی برای صاحبان کسب‌وکار، تیم‌های محصول و توسعه‌دهندگان توضیح می‌دهد.
وب‌هوک OxaPay چه کاری انجام می‌دهد؟
وب‌هوک پیامی میان دو سرور است که یک رویداد آن را فعال می‌کند. به‌جای اینکه سیستم شما مرتب بپرسد آیا وضعیت پرداخت تغییر کرده است، OxaPay هنگام در دسترس قرار گرفتن اطلاعات جدید پرداخت، یک کال‌بک JSON را به نشانی HTTPS ارائه‌شده از سوی شما می‌فرستد.
اپلیکیشن شما سپس می‌تواند از این به‌روزرسانی تأییدشده برای تغییر وضعیت سفارش، فعال‌کردن سرویس، ارسال تأییدیه یا ایجاد رکوردی برای تطبیق تراکنش‌ها. این قابلیت به‌ویژه مفید است، چون پرداخت رمزارزی ممکن است پیش از رسیدن به نتیجه نهایی کسب‌وکار، چندین وضعیت را پشت سر بگذارد.
صفحه بازگشت مرورگر نباید مدرک انجام پرداخت تلقی شود. مشتری ممکن است صفحه را ببندد، اتصالش قطع شود یا به URL بازگشت مراجعه کند، بی‌آنکه پرداخت به وضعیت لازم رسیده باشد. تصمیم برای انجام سفارش باید بر اساس اطلاعات پرداختی باشد که در سمت سرور تأیید شده‌اند.
چه زمانی کسب‌وکار شما به وب‌هوک پرداخت نیاز دارد؟
وب‌هوک سفارشی زمانی بیشترین ارزش را دارد که نتیجه یک پرداخت باید به‌طور خودکار اقدام دیگری را فعال کند. نمونه‌های رایج عبارت‌اند از:
- تغییر وضعیت سفارش فروشگاه اینترنتی از «در انتظار» به «آماده انجام»؛
- فعال‌کردن حساب SaaS یا تمدید اشتراک؛
- ارسال تأییدیه پرداخت از طریق ایمیل، پیامک یا پیام درون‌برنامه‌ای؛
- به‌روزرسانی موجودی، CRM، حسابداری یا سیستم‌های گزارش‌دهی داخلی؛
- هشدار به تیم عملیات وقتی پرداخت کمتر از مبلغ موردنیاز باشد یا منقضی شده باشدیا به هر دلیل دیگری نیاز به بررسی داشته باشد.
اگر از یک افزونه پرداختپشتیبانی‌شده استفاده می‌کنید، ممکن است بخش زیادی از این منطق از قبل در یکپارچه‌سازی وجود داشته باشد. اگر فقط گاهی Payment Links and review them manually, you may not need a custom endpoint. یکپارچه‌سازی مستقیم API and custom platforms usually benefit the most.
جریان کاری وب‌هوک OxaPay چگونه است؟
- Your system creates or identifies a payment and stores OxaPay’s
track_idwith your own order or customer reference. - مشتری پرداخت را ارسال می‌کند و وضعیت آن در جریان پردازش توسط OxaPay تغییر می‌کند.
- OxaPay یک کال‌بک JSON امضاشده به URL کال‌بک تنظیم‌شده شما می‌فرستد.
- سرور شما پیش از اعتماد به پیام، امضای آن را تأیید می‌کند.
- سرور شما کال‌بک را به رکورد درست متصل می‌کند و اطلاعات مهم پرداخت را اعتبارسنجی می‌کند.
- اپلیکیشن شما رویداد را ثبت می‌کند، هر اقدام تجاری تأییدشده را فقط یک بار انجام می‌دهد و پاسخ HTTP موفق برمی‌گرداند.
این تفکیک مهم است. وب‌هوک به‌روزرسانی پرداخت را تحویل می‌دهد، اما تصمیم‌گیری درباره معنای آن برای سفارش، حساب، ارسال کالا یا ثبت در دفترکل همچنان بر عهده اپلیکیشن شماست.
پیش از شروع
پیش از اتصال کال‌بک، موارد زیر را آماده کنید:
- اندپوینت HTTPS عمومی و قابل‌دسترسی که درخواست‌های HTTP POST را بپذیرد؛
- دسترسی سمت سرور به اطلاعات احراز هویت پذیرنده OxaPay که به‌طور امن نگهداری شوند و هرگز در کد مرورگر افشا نشوند؛
- رکوردی در پایگاه داده که شناسه OxaPay یعنی
track_idwith your own order, invoice, or user ID; - قوانین روشن برای اینکه کدام وضعیت‌های پرداخت می‌توانند انجام سفارش، اعطای دسترسی، بازپرداخت، ارسال اعلان یا بررسی دستی را فعال کنند؛
- ثبت لاگ و پایشی که خطاهای تحویل، خطاهای اعتبارسنجی و تغییرات غیرمنتظره وضعیت را آشکار کند.
اگر برای یکپارچه‌سازی گسترده‌تری برنامه‌ریزی می‌کنید، از چک‌لیست یکپارچه‌سازی پرداخت رمزارزی to review keys, payment methods, callbacks, testing, and go-live controls together.
نحوه راه‌اندازی وب‌هوک‌های OxaPay
قوانین وضعیت پرداخت را مشخص کنید
پیش از نوشتن هندلر تصمیم بگیرید کسب‌وکار شما برای هر وضعیت پرداخت before writing the handler. A notification that a payment has started is not the same as a completed payment. Underpaid, expired, refunded, or other exception states may require a different action or a manual review.
فقط انتقال میان وضعیت‌هایی را مجاز بدانید که مستند و موردانتظار هستند. برای مثال، سفارشی که قبلاً انجام شده نباید صرفاً به دلیل تحویل دوباره همان کال‌بک، مجدداً انجام شود.
یک اندپوینت کال‌بک امن بسازید
یک مسیر HTTPS اختصاصی در بک‌اند خود ایجاد کنید؛ برای مثال https://example.com/webhooks/oxapay. این مسیر باید درخواست‌های POST را بپذیرد، بدنه خام درخواست را برای تأیید امضا در دسترس نگه دارد و روش‌های پشتیبانی‌نشده یا درخواست‌های نامعتبر را رد کند.
وظیفه این هندلر را محدود نگه دارید. نخستین کار آن تأیید کال‌بک و ثبت پایدار آن است. کارهای زمان‌بر، مانند ارسال ایمیل، به‌روزرسانی چند سیستم خارجی یا تولید گزارش، می‌توانند پس از پذیرش رویداد به صف پردازش پس‌زمینه منتقل شوند.
URL کال‌بک را به OxaPay ارائه دهید
URL کال‌بک را به جریان پرداخت مرتبط در OxaPay اضافه کنید. بسته به محصول یا روش یکپارچه‌سازی، این URL ممکن است در درخواست پرداخت یا در تنظیمات مربوط به پذیرنده ارائه شود. برای جزئیات، به مستندات وب‌هوک OxaPay for the exact field and behavior of the service you are implementing.
در هر محیط، از یک URL ثابت استفاده کنید. اندپوینت‌های آزمایشی و عملیاتی را جدا نگه دارید تا رویدادهای آزمایشی نتوانند سفارش‌های واقعی را تغییر دهند.
پیش از اعتماد به کال‌بک، امضا را تأیید کنید
طبق مستندات OxaPay، امضای HMAC-SHA512 از داده خام POST و با استفاده از کلید API پذیرنده به‌عنوان راز مشترک تولید می‌شود. سرور شما باید امضای موردانتظار را از بدنه خامِ تغییریافته‌نشده محاسبه و با امضای همراه کال‌بک مقایسه کند.
اگر تأیید امضا ناموفق بود، درخواست را رد کنید. در صورت پشتیبانی فریم‌ورک، از مقایسه با زمان اجرای ثابت استفاده کنید و هرگز کلید API پذیرنده یا سایر اطلاعات محرمانه را لاگ نکنید. تجزیه JSON و سریال‌سازی مجدد آن پیش از محاسبه HMAC می‌تواند فاصله‌ها یا ترتیب فیلدها را تغییر دهد و باعث ردشدن امضای معتبر شود. مرجع تأیید کال‌بک explains the broader security model.
پرداخت را تطبیق و اعتبارسنجی کنید
امضای معتبر منبع پیام را تأیید می‌کند، اما اپلیکیشن شما همچنان باید داده‌های تجاری را اعتبارسنجی کند. شناسه track_id to a known payment record, confirm the relevant order or customer reference, compare the expected amount and currency where applicable, and check that the new state is allowed from the current state.
اجازه ندهید پرداخت ناشناخته، مبلغ غیرمنتظره یا انتقال نامعتبر وضعیت به‌طور خودکار انجام سفارش را فعال کند. رویداد را برای بررسی ثبت کنید و اطلاعات فعلی پرداخت را از طریق API تأیید کنید.
هر رویداد را به‌صورت بدون اثر تکراری پردازش کنید
ممکن است وب‌هوک چند بار تحویل داده شود. هندلر شما باید با دریافت چندباره یک به‌روزرسانی پرداخت، همان نتیجه نهایی را ایجاد کند. یک کلید پایدار برای رویداد یا وضعیت پرداخت ذخیره کنید و پیش از ارسال ایمیل، اعطای دسترسی، تغییر موجودی یا ثبت حسابداری آن را بررسی کنید.
خاصیت Idempotency باعث می‌شود تحویل تکراری به یک تلاش مجدد بی‌ضرر تبدیل شود، نه ارسال تکراری کالا، تمدید چندباره اشتراک یا ثبت مضاعف در دفترکل.
رویداد را ثبت کنید و سریع پاسخ دهید
پس از موفقیت در تأیید درخواست، کال‌بک و نتیجه اعتبارسنجی آن را ذخیره کنید و سپس پاسخ HTTP با کد 200 with the expected ok response. If downstream work may take time, place it in a queue and respond after durable receipt rather than making the sender wait for the entire business workflow.
اگر سرور نمی‌تواند رویداد را به‌شکلی ایمن ثبت کند، پاسخ خطا برگردانید و علت را بررسی کنید. کال‌بکی را تأیید نکنید که بعداً بی‌سروصدا کنار گذاشته شود.
کل چرخه عمر پرداخت را آزمایش کنید
به آزمایش یک کال‌بک موفق بسنده نکنید. وضعیت‌ها و استثناهای احتمالی را پوشش دهید؛ از جمله پرداخت با تأخیر، پرداخت ناکافی، انقضا، تحویل تکراری، امضای نامعتبر و مقادیر ناشناخته track_id values, temporary database failure, and recovery after downtime.
هم نتیجه فنی و هم نتیجه تجاری را بررسی کنید. ممکن است اندپوینت 200 OK while the wrong order is updated or the customer receives two confirmations. A complete test follows the event from OxaPay through your database, queue, customer message, fulfillment logic, and audit trail.
وب‌هوک‌ها را همراه با استعلام وضعیت به‌کار ببرید
وب‌هوک و استعلام وضعیت از طریق API دو بخش متفاوت از یک مسئله را حل می‌کنند. وب‌هوک نشانه‌ای سریع فراهم می‌کند. درخواست وضعیت، مسیر بازیابی معتبری است برای زمانی که کال‌بک دیر برسد، دریافت نشود، خارج از ترتیب پردازش شود یا پس از قطعی محلی وضعیت آن نامشخص بماند.
| روش | بهترین کاربرد | محدودیت عملیاتی |
|---|---|---|
| کال‌بک وب‌هوک | واکنش سریع به تغییر وضعیت پرداخت | تحویل ممکن است با تأخیر انجام شود، تکرار شود یا موقتاً در دسترس نباشد |
| درخواست اطلاعات پرداخت | بازیابی، تطبیق تراکنش‌ها و تأیید وضعیت فعلی | سیستم شما باید زمان استعلام را تعیین کند و از درخواست‌های مکرر غیرضروری پرهیز کند |
For important payment flows, schedule reconciliation for records that remain pending too long or have not received an expected update. OxaPay’s Payment Information API can be used to retrieve the current payment details by the documented identifier.
کاربردهای عملی وب‌هوک
سفارش‌های فروشگاهی
تا وقتی پرداخت در جریان است، وضعیت سفارش را «در انتظار» نگه دارید. پس از رسیدن به وضعیت تکمیل تأییدشده، موجودی را طبق قوانین کسب‌وکار رزرو یا آزاد کنید، سفارش را فقط یک بار به مرحله انجام ببرید و تأییدیه‌ای برای مشتری بفرستید.
SaaS و دسترسی دیجیتال
حساب را فقط پس از نتیجه پرداخت تأییدشده فعال کنید یا دسترسی را تمدید کنید. دوره پرداخت یا تغییر سطح دسترسی را ثبت کنید تا کال‌بک تکراری همان مزیت را دوباره اعطا نکند.
امور مالی و تطبیق حساب‌ها
رویدادهای پرداخت را به ردپای حسابرسی اضافه و به فاکتور داخلی متصل کنید. وضعیت‌های استثنا می‌توانند وارد صف بررسی شوند، درحالی‌که استعلام‌های زمان‌بندی‌شده، پرداخت‌های حل‌نشده را تطبیق می‌دهند.
ارتباط با مشتری
پیام‌ها را بر اساس نتیجه فرایند تجاری بدون اثر تکراری ارسال کنید، نه مستقیماً با هر کال‌بک ورودی. این کار جلوی ایمیل‌های تکراری یا پیام‌های متناقض را هنگام گذر پرداخت از چند وضعیت می‌گیرد.
اشتباهات رایج در کار با وب‌هوک
- اعتماد به صفحه بازگشت: use verified server-side payment information instead of a browser redirect.
- تأیید JSON با قالب‌بندی مجدد: calculate the HMAC from the original raw request body.
- افشای کلید پذیرنده: keep signing credentials in protected server-side storage.
- فرض منحصربه‌فرد بودن هر کال‌بک: make every business action idempotent.
- انجام کار بیش از حد پیش از پاسخ: durably record the event, queue slow work, and respond promptly.
- پذیرش هر تغییر وضعیت: enforce a controlled payment state model.
- اتکای صرف به تحویل: use payment information requests for recovery and reconciliation.
- ثبت اطلاعات حساس در لاگ: retain useful identifiers and validation results without storing secrets unnecessarily.
عیب‌یابی وب‌هوک‌های OxaPay
| نشانه مشکل | چه چیزی را بررسی کنید؟ |
|---|---|
| هیچ کال‌بکی دریافت نمی‌شود | URL کال‌بک، دسترسی عمومی از طریق HTTPS، قوانین فایروال، محیط و لاگ‌های مربوط به آن پرداخت را بررسی کنید. |
| تأیید امضا ناموفق است | از بایت‌های خام درخواست، کلید API درست پذیرنده، روش مستند HMAC-SHA512 و مقایسه دقیق استفاده کنید. |
| همان اقدام دو بار انجام می‌شود | کلید Idempotency را بررسی کنید و مطمئن شوید اقدامات تجاری پیش از تکرار، ثبت شده‌اند. |
| کال‌بک پاسخ خطا برمی‌گرداند | تجزیه درخواست، دسترس‌پذیری پایگاه داده، سلامت صف، خطاهای اپلیکیشن و زمان پاسخ را بررسی کنید. |
| وضعیت محلی اشتباه به نظر می‌رسد | اطلاعات فعلی پرداخت را استعلام بگیرید، شناسه‌ها و تاریخچه وضعیت را مقایسه کنید و سپس رکورد محلی را تطبیق دهید. |
چک‌لیست راه‌اندازی عملیاتی وب‌هوک OxaPay
- کال‌بک محیط عملیاتی از HTTPS استفاده می‌کند و از اینترنت عمومی در دسترس است.
- بدنه خام درخواست تا پایان تأیید HMAC-SHA512 نگهداری می‌شود.
- کلید API پذیرنده امن ذخیره می‌شود و هرگز در کد سمت کاربر یا لاگ‌ها ظاهر نمی‌شود.
- هر کال‌بک به پرداخت شناخته‌شده‌ای متصل و با داده‌های تجاری موردانتظار اعتبارسنجی می‌شود.
- انتقال‌های مجاز میان وضعیت‌های پرداخت مستند و اعمال می‌شوند.
- کال‌بک‌های تکراری نمی‌توانند انجام سفارش، اعطای دسترسی، اعلان‌ها یا ثبت‌های حسابداری را تکرار کنند.
- رویدادها و نتایج اعتبارسنجی بدون اطلاعات حساس غیرضروری لاگ می‌شوند.
- پرداخت‌های با تأخیر یا نامشخص را می‌توان از طریق Payment Information API تطبیق داد.
- پایش، تیم را از خطای امضا، خطای پردازش و بزرگ‌شدن صف‌ها آگاه می‌کند.
- کل جریان کاری پیش از وابستگی پرداخت‌های واقعی مشتریان به آن آزمایش شده است.
گام بعدی چیست؟
ابتدا اقدام تجاری مجاز برای هر وضعیت پرداخت را تعریف کنید. سپس یک اندپوینت امن بسازید که پیش از اجرای کارهای بعدی، کال‌بک‌ها را تأیید، ثبت و از نظر تکراری‌بودن بررسی کند. در پایان، مسیر استعلام وضعیت و تطبیق را اضافه کنید تا خرابی موقت تحویل یا سیستم، سفارشی را برای همیشه بلاتکلیف نگذارد.
برای آشنایی عمیق‌تر با وضعیت‌های پرداخت، تحویل و معماری بازیابی، مقاله پایش بلادرنگ در سیستم‌های پرداخت بلاک‌چینیرا بخوانید. توسعه‌دهندگان باید مستندات فعلی وب‌هوک OxaPay as the implementation source of truth.
