ایجاد پرداخت، callback و verify
ایجاد پرداخت
POST /v1/payments با هدر Authorization: Bearer sk_….
| فیلد | الزامی | توضیح |
|---|---|---|
amount | بله | ریال، رشته یا عدد صحیح؛ بین ۱۰٬۰۰۰ تا ۱٬۰۰۰٬۰۰۰٬۰۰۰ ریال |
callbackUrl | بله | https؛ اگر در پروژه «میزبان‌های مجاز» تنظیم شده، باید یکی از آن‌ها باشد |
orderId | خیر | شناسه‌ی سفارش شما (تا ۶۴ کاراکتر)؛ در وب‌هوک و verify برمی‌گردد |
description | خیر | متن کوتاه که مشتری روی صفحه‌ی پرداخت می‌بیند |
payerName | خیر | نام مشتری؛ در پنل، صف بررسی و پیام ربات دیده می‌شود |
payerPhone | خیر | موبایل مشتری |
metadata | خیر | تا ۲۰ کلید ساده؛ عیناً برمی‌گردد |
خطاها:
| کد HTTP | error.code | معنی |
|---|---|---|
| 402 | merchant_credit_exhausted | اعتبار فروشنده تمام شده؛ پرداخت جدید ساخته نمی‌شود |
| 503 | no_card_available | کارتی در دسترس نیست (سقف‌ها، دستگاه آفلاین)؛ details.reasons می‌گوید چرا |
| 422 | callback_host_not_allowed | میزبان callback مجاز نیست |
| 401 | unauthorized | کلید نامعتبر |
| 403 | project_inactive / merchant_inactive | پروژه یا فروشنده فعال نیست |
بازگشت مشتری (callback)
بعد از نتیجه، مشتری به callbackUrl هدایت می‌شود با این پارامترها:
https://shop.example.com/varizapp/callback
?varizapp_token=Avz4_43Khv...
&varizapp_status=confirmed
&varizapp_ref=01a0acf1-e835-7ed7-91e8-f25a128276f3
&order_id=ORD-1024
varizapp_status یکی از confirmed، expired، canceled، rejected است، ولی به آن اعتماد نکنید؛ با varizapp_ref (شناسه‌ی پرداخت) verify کنید.
اگر مشتری صفحه را ببندد، callback نمی‌آید؛ وب‌هوک شما را باخبر می‌کند.
verify
POST /v1/payments/{id}/verify — idempotent؛ هر چند بار صدا بزنید همان نتیجه است و alreadyVerified می‌گوید قبلاً verify شده بود.
verified: trueوstatus: confirmed→ سفارش را تکمیل کنید.verified: false→ پرداخت هنوز معلق است یا ناموفق شده (statusرا ببینید). اگرpendingاست، مشتری شاید هنوز واریز نکرده یا پیامک بانک هنوز نرسیده؛ بعداً دوباره verify کنید یا منتظر وب‌هوک بمانید.
وضعیت پرداخت
GET /v1/payments/{id} هر وقت خواستید. GET /v1/payments?orderId=… برای پیدا کردن با شناسه‌ی سفارش.
نام مشتری (payerName)، موبایل و شناسه‌ی کاربرتان را در metadata بفرستید. اگر مشتری مبلغ را اشتباه بزند، در صف بررسی کنار هر پیشنهاد همین‌ها دیده می‌شود و می‌فهمید واریزی مال کیست.
چرخه‌ی عمر
pending ──► confirmed ( تأیید خودکار یا دستی)
│
├──► expired (مهلت تمام شد؛ اگر واریزی دیر برسد، تا پنجره‌ی تطبیق دیرهنگام هنوز confirmed می‌شود)
├──► canceled (مشتری انصراف داد)
└──► rejected (فروشنده رد کرد)
مهلت پرداخت (پیش‌فرض ۱۵ دقیقه) در تنظیمات پروژه است.