مستندات توسعهدهندگان
هر درخواست باید هدر Authorization: Bearer <api_key> را همراه داشته باشد. کلید API مخصوص مرچنت را در بخش مدیریت پذیرندهها میبینید.
بدنه درخواست را میتوانید با application/json، application/x-www-form-urlencoded یا multipart/form-data بفرستید. پاسخهای موفق JSON هستند و فیلدها مستقیماً در ریشه پاسخ قرار میگیرند.
ثبت درخواست پرداخت
با فرستادن یک درخواست POST به این مسیر، مبلغ ثبت میشود و لینک امن آغاز پرداخت را برای کاربر تحویل میگیرید.
متد
POST
نشانی
/api/v1/payment/request
هدر
Authorization: Bearer api_key
انقضا لینک
15 دقیقه
مبلغ باید بین 1 تا 5000 USDT باشد. لینک پرداخت هم تا 15 دقیقه اعتبار دارد.
پارامترها
| نام | نوع | وضعیت | توضیحات |
|---|---|---|---|
| amount | عدد (USDT) | الزامی | باید بین 1 تا 5000 باشد. |
| callback_url | رشته (url) | الزامی | آدرسی از سایت پذیرنده که رمزپال اطلاعات پرداخت را به آن میفرستد. |
| order_id | رشته | اختیاری | شناسه سفارش جلوی ثبت تکراری را میگیرد؛ اگر پرداخت فعال یا تکمیلشدهای با این شناسه وجود داشته باشد، پاسخ ۴۲۲ با پیام `this payment exists` برمیگردد. |
| language | رشته | اختیاری | صفحه پرداخت سهزبانه است و از فارسی، انگلیسی و عربی پشتیبانی میکند. برای زبان دلخواه یکی از مقدارهای `fa`، `en`، `ar` یا `arabic` را بفرستید. |
پاسخهای ممکن
| کد | بدنه | شرح |
|---|---|---|
| ۲۰۰ |
success true، payment_id، redirect_url
|
پرداخت ثبت شده است و redirect_url با امضای معتبر در پاسخ برمیگردد. |
| ۴۰۱ |
{'message': 'Unauthorized'}
|
هدر Authorization فرستاده نشده است یا کلید API اعتبار ندارد. |
| ۴۲۲ |
{'message': 'this payment exists'}
|
یکی از مقدارهای فرستادهشده معتبر نیست یا سفارش تکراری است. |
نمونه پاسخ موفق
{
"success": true,
"payment_id": "pay_1234567890",
"redirect_url": "https://your-domain/payments/start/pay_1234567890?signature=..."
}
بازگشت نتیجه به سایت شما (Callback)
وقتی وضعیت پرداخت به PAID رسید، رمزپال یک درخواست GET به callback_url میفرستد. شناسه پرداخت و سفارش هم همراه آن است تا سرور شما تراکنش را ثبت کند یا رخداد لازم را انجام دهد. اگر callback به هر دلیل به مقصد نرسد، مبلغ خودکار به پرداختکننده برنمیگردد. در این حالت، پذیرنده باید پرداخت را در بخش تراکنشهای پنل پیگیری کند؛ وضعیت PAID یعنی پرداختکننده مبلغ را کامل واریز کرده است.
اگر callback_url از قبل query string داشته باشد، رمزپال پارامترهای callback را بدون حذف پارامترهای موجود به آن اضافه میکند. برای نتیجه قطعی، پس از دریافت callback حتماً endpoint تأیید پرداخت را فراخوانی کنید و فقط پاسخ VERIFIED را معتبر بدانید.
پارامترهای ارسالی به callback
نمونه درخواست GET که به callback_url ارسال میشود
GET https://merchant.example/callback?payment_id=pay_1234567890&order_id=order-4587&success=true
تایید پرداخت
این مسیر وضعیت پرداخت را بررسی میکند. اگر همهچیز درست باشد، وضعیت به VERIFIED میرسد و شناسههای تراکنش هم در پاسخ برمیگردند.
متد
POST
نشانی
/api/v1/payment/verify
هدر
Authorization: Bearer api_key
پارامترهای بدنه
| نام | نوع | وضعیت | توضیحات |
|---|---|---|---|
| payment_id | رشته | الزامی | شناسه عمومی پرداخت (pay_...) که از درخواست اولیه دریافت کردهاید. |
| amount | عدد | الزامی | باید دقیقاً با مبلغ پرداختی ثبتشده برابر باشد. |
پاسخهای ممکن
| کد | بدنه | شرح |
|---|---|---|
| ۲۰۰ |
success true، status، payment_id، order_id، amount، tx_ids
|
پرداخت تأیید شده است و شناسههای تراکنش برمیگردند. |
| ۴۰۱ |
{'message': 'Unauthorized'}
|
هدر Authorization فرستاده نشده است یا کلید API اعتبار ندارد. |
| ۴۲۲ |
{'message': 'payment not completed'} یا {'message': 'amount mismatch'}
|
یا پرداخت هنوز کامل نشده است، یا مبلغ فرستادهشده با مبلغ ثبتشده یکی نیست. |
| ۴۰۴ |
{'message': 'payment not found'}
|
پرداختی با این شناسه پیدا نشد. |
نمونه پاسخ موفق
{
"success": true,
"status": "VERIFIED",
"payment_id": "pay_1234567890",
"order_id": "order-4587",
"amount": 125.5,
"tx_ids": [
"0x123456789abcdef"
]
}
اگر شناسه تراکنش ثبت شده باشد، داخل آرایه tx_ids میآید.
وضعیتهای پرداخت
هر پرداخت در یکی از وضعیتهای زیر قرار میگیرد. هنگام تأیید هم کافی است فیلد status را ببینید تا بدانید ماجرا در چه مرحلهای است.
پرداخت که کامل شد، وضعیت نهایی به VERIFIED میرسد و شناسههای تراکنش بلاکچینی را در خروجی tx_ids میبینید.