API درگاه › صورتحساب
ساخت صورتحساب
/gateway-api/v1/invoicesیک صورتحساب با مبلغ ثابت برای پذیرندهٔ فعال شبکهٔ شما میسازد و pay_url برمیگرداند. مشتری را به pay_url بفرستید تا روش پرداختش را انتخاب کند و بپردازد. لینک پرداخت تا payment_due_at، یعنی یک ساعت، اعتبار دارد.
curl -X POST "$RINGPAY_BASE_URL/gateway-api/v1/invoices" \
-H "Authorization: Bearer $RINGPAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"merchant_id": "khb",
"amount": "4900000",
"payer_mobile": "+989121234567",
"external_order_id": "order-1042",
"callback_url": "https://shop.example/ringpay/return"
}'{
"id": "86Rf07xd4z",
"pay_url": "https://pay.ring.ir/pay?token=…",
"payment_due_at": "2026-11-07T10:00:00Z"
}پارامترها
merchant_idstringدستکم یکیشناسهٔ پذیرنده در رینگپی.
external_idstringدستکم یکیشناسهٔ پذیرنده در سامانهٔ شبکهٔ شما. اگر هر دو را بفرستید باید به یک پذیرنده برسند؛ وگرنه
422 merchant_id_mismatch. حداکثر 128 نویسه.amountstringالزامیمبلغ به ریال، عدد صحیح مثبت بهصورت رشته؛ مثلاً
"4900000".payer_mobilestringالزامیموبایل پرداختکننده با قالب E.164؛ مثلاً
"+989121234567". اگر در رینگپی حساب نداشته باشد ساخته میشود.external_order_idstringالزامیشناسهٔ سفارش در سامانهٔ شما. درخواست تکراری با همین شناسه همان صورتحساب را با
200وpay_urlتازه برمیگرداند؛ با مبلغ یا موبایل دیگر409 invoice_order_conflict. حداکثر 128 نویسه.callback_urlstringالزامیآدرس مطلق https که مشتری پس از پرداخت یا انصراف به آن برمیگردد. بازگشت به سایت را ببینید.
پاسخ
201 برای صورتحساب تازه و 200 برای درخواست تکراری با همان external_order_id. id را کنار سفارش ذخیره کنید؛ برای دریافت صورتحساب و تأیید مصرف لازم است. مشتری را به pay_url بفرستید.
خطاها
کدهای مشترک و رفتار هر کد در خطاها آمده.
invalid_request400بدنه یا پارامترها نامعتبرند؛ مثلاً مبلغ صفر، موبایل بدون قالب E.164،
callback_urlبدون https یاcursorساختگی.invalid_access_key401کلید فرستاده نشده، نامعتبر است، منقضی شده یا باطل شده.
access_denied403کلید دسترسی این API را ندارد (
gateway_accessبرای درگاه،merchant_accessبرای پذیرندهها)، یا درخواست از IPی بیرون از فهرست مجاز کلید آمده.merchant_not_found404پذیرندهای با این شناسه در شبکهٔ شما نیست.
merchant_not_payable409پذیرنده هنوز فعال نشده یا مسدود است و نمیتواند پرداخت بگیرد.
invoice_order_conflict409همین
external_order_idقبلاً با مبلغ یا موبایل دیگری ثبت شده.merchant_id_mismatch422merchant_idوexternal_idبه یک پذیرنده نمیرسند.internal_error500خطای رینگپی. کمی بعد همان درخواست را تکرار کنید.