‏API درگاه › صورت‌حساب

ساخت صورت‌حساب

OpenAPI
POST/gateway-api/v1/invoices

یک صورت‌حساب با مبلغ ثابت برای پذیرندهٔ فعال شبکهٔ شما می‌سازد و pay_url برمی‌گرداند. مشتری را به pay_url بفرستید تا روش پرداختش را انتخاب کند و بپردازد. لینک پرداخت تا payment_due_at، یعنی یک ساعت، اعتبار دارد.

POST /gateway-api/v1/invoices
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"
  }'
Response 201 · 200
{
  "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_mismatch422

    merchant_id و external_id به یک پذیرنده نمی‌رسند.

  • internal_error500

    خطای رینگ‌پی. کمی بعد همان درخواست را تکرار کنید.

صفحه‌ها

endpointها