# اعتبارسنجی تراکنش (خودکار/غیرخودکار)
در چرخهی پرداخت در زرینپال، پس از اینکه خریدار عملیات پرداخت را در درگاه بانکی انجام میدهد، زرینپال باید از بانک (PSP) استعلام و تأیید بگیرد تا از موفقیت نهایی تراکنش اطمینان حاصل شود. این مرحله را اعتبارسنجی (Verify) نهایی تراکنش مینامیم.
تا زمانی که این اعتبارسنجی انجام نشود، پرداخت بهصورت کامل انجامشده تلقی نمیشود و اگر این مرحله در بازهی زمانی مقرر انجام نگیرد، مبلغ تراکنش به حساب خریدار بازگردانده خواهد شد.
در حالت عادی، این رفتار از طریق تنظیمات درگاه پرداخت در پنل زرینپال قابل کنترل است:
اگر در پنل، اعتبارسنجی خودکار فعال باشد، زرینپال پس از پرداخت موفق، بهصورت خودکار نزد بانک تراکنش را اعتبارسنجی میکند.
اگر اعتبارسنجی غیرخودکار انتخاب شده باشد، آغاز فرآیند اعتبارسنجی بهعهدهی پذیرنده است و باید با فراخوانی متد اعتبارسنجی تراکنش (متد verify در API پرداخت) این مرحله را آغاز کند.
برای کنترل دقیقتر این رفتار در لحظهی پرداخت، میتوانید از پارامتر اختیاری auto_verify در آبجکت metadata در بدنهی درخواست پرداخت استفاده کنید.
# موارد استفاده از metadata.auto_verify
این قابلیت زمانی کاربرد دارد که پذیرنده بخواهد رفتار اعتبارسنجی تراکنش را برای بعضی پرداختها مستقل از تنظیم کلی درگاه کنترل کند؛ مثلاً برای تراکنشهای با مبلغ یا ریسک بالاتر، اعتبارسنجی غیرخودکار را اعمال کند یا برعکس، برخی پرداختهای روتین را خودکار اعتبارسنجی کند. همچنین در سناریوهایی که سایت پذیرنده ممکن است دچار اختلال شود یا خریدار به هر دلیل به آدرس کالبک نرسد، سپردن کنترل کامل اعتبارسنجی تراکنش به خود پذیرنده (از طریق auto_verify=false و فراخوانی متد اعتبارسنجی) کمک میکند از بروز مغایرت و اختلاف بین وضعیت پرداخت در سیستم پذیرنده و زرینپال جلوگیری شود.
در صورت ارسال این پارامتر، مقدار metadata.auto_verify همواره نسبت به تنظیمات درگاه در پنل اولویت دارد و رفتار سیستم بر اساس همین مقدار تعیین میشود.
# نمونه درخواست
- درخواست
curl -X POST \
https://payment.zarinpal.com/pg/v4/payment/request.json \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
"merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"currency": "IRT",
"amount": 10000,
"callback_url": "https://example.com/payment-callback",
"description": "خرید اشتراک",
"metadata": {
"auto_verify": true,
"mobile": "09121234567",
"email": "info@example.com"
}
}'
# رفتار سیستم براساس مقدار metadata.auto_verify
در این بخش رفتار سیستم در سه حالت مختلف مقدار metadata.auto_verify توضیح داده میشود.
# ۱. اگر مقدار true ارسال شود
تراکنش پس از پرداخت موفق، بهصورت خودکار توسط زرینپال نزد بانک اعتبارسنجی میشود.
نیازی به فراخوانی متد اعتبارسنجی تراکنش از سمت پذیرنده نیست.
این حالت معادل فعالبودن اعتبارسنجی خودکار است.
حتی اگر در پنل، اعتبارسنجی خودکار غیرفعال باشد، با ارسال این مقدار، تراکنش بهصورت خودکار اعتبارسنجی خواهد شد.
# ۲. اگر مقدار false ارسال شود
در این حالت، اعتبارسنجی تراکنش بهصورت خودکار انجام نمیشود و سیستم در هیچ مرحلهای بدون دخالت پذیرنده درخواست اعتبارسنجی به PSP ارسال نمیکند.
زرینپال تنها زمانی اعتبارسنجی نهایی تراکنش را نزد PSP انجام میدهد که پذیرنده متد اعتبارسنجی تراکنش را فراخوانی کند.
بهعبارت دیگر، شروع فرآیند اعتبارسنجی نزد PSP وابسته به فراخوانی متد اعتبارسنجی تراکنش از طرف پذیرنده است؛ تا زمانی که این متد فراخوانی نشود، ارتباطی برای اعتبارسنجی با PSP برقرار نخواهد شد.
اگر این فراخوانی در بازهی زمانی مجاز انجام نشود، تراکنش نهایی نشده و مبلغ به حساب خریدار بازگردانده میشود.
این حالت عملاً معادل انتخاب اعتبارسنجی غیرخودکار برای آن تراکنش است، حتی اگر در پنل درگاه، اعتبارسنجی خودکار فعال باشد.
# ۳. اگر پارامتر auto_verify ارسال نشود
در صورتی که پارامتر auto_verify در آبجکت metadata ارسال نشود، رفتار سیستم بر اساس تنظیمات درگاه در پنل زرینپال تعیین میشود:
اگر در پنل، اعتبارسنجی خودکار فعال باشد، تراکنش بهصورت خودکار اعتبارسنجی میشود.
اگر اعتبارسنجی خودکار غیرفعال باشد، پذیرنده باید متد اعتبارسنجی تراکنش را فراخوانی کند تا فرآیند Verify نزد PSP انجام شود.
# نکات مهم
استفاده از پارامتر
auto_verifyفقط در مواردی توصیه میشود که نیاز به کنترل لحظهای رفتار اعتبارسنجی تراکنش وجود داشته باشد.در صورت عدم ارسال این پارامتر، رفتار سیستم کاملاً تابع تنظیمات درگاه شما در پنل زرینپال خواهد بود.
در حالت اعتبارسنجی غیرخودکار، اگر متد اعتبارسنجی تراکنش از سمت پذیرنده در زمان مناسب فراخوانی نشود، پرداخت بازگشت خورده و عملاً از دست میرود.