API شبکهٔ پذیرنده › پذیرنده
ثبت پذیرنده
/merchant-network-api/v1/merchantsپذیرنده و کاربر مالکش را ثبت میکند و شناسهٔ رینگپی و یک لینک ورود یکبارمصرف برمیگرداند. اگر کاربری با این موبایل در رینگپی باشد همان مالک میشود، وگرنه ساخته میشود.
پذیرنده با وضعیت registered ساخته میشود و تا فعال نشود نمیتواند پرداخت بگیرد.
curl -X POST "$RINGPAY_BASE_URL/merchant-network-api/v1/merchants" \
-H "Authorization: Bearer $RINGPAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"external_id": "shop-1",
"title": "فروشگاه نمونه",
"owner_mobile": "+989121234567",
"logo_url": "https://shop.example.com/logo.png"
}'{
"expires_at": "2026-11-02T09:02:00Z",
"login_url": "https://panel.ring.ir/home?login_token=…",
"merchant_id": "86Rf07xd4z"
}پارامترها
external_idstringالزامیشناسهٔ پذیرنده در سامانهٔ شما؛ در شبکهٔ شما یکتاست. حداکثر 128 نویسه.
titlestringالزامینام کسبوکار، همان که مشتری در صفحهٔ پرداخت میبیند. حداکثر 200 نویسه.
owner_mobilestringالزامیموبایل مالک با قالب E.164. پیش از فرستادن، آن را با کد یکبارمصرف در سامانهٔ خودتان تأیید کنید.
descriptionstringتوضیح کوتاه دربارهٔ کسبوکار. حداکثر 1000 نویسه.
linkstringلینک خود پذیرنده؛ مثلاً سایتش. حداکثر 2048 نویسه.
logo_urlstringآدرس لوگو. حداکثر 2048 نویسه.
پاسخ
201 برای پذیرندهٔ تازه. تکرار درخواست با همان external_id و همان owner_mobile چیزی را تغییر نمیدهد و همان پذیرنده را با لینک تازه و 200 برمیگرداند؛ برای تغییر پروفایل از بهروزرسانی پذیرنده استفاده کنید. موبایل دیگر 409 owner_mobile_mismatch میگیرد و لینکی برنمیگردد.
login_url لینک یکبارمصرف ورود مالک به پنل پذیرنده است و تا expires_at، یعنی دو دقیقه، اعتبار دارد. همان لحظه کاربر را به آن بفرستید و لینک را ذخیره یا پیامک نکنید.
خطاها
کدهای مشترک و رفتار هر کد در خطاها آمده.
invalid_request400بدنه یا پارامترها نامعتبرند؛ مثلاً مبلغ صفر، موبایل بدون قالب E.164،
callback_urlبدون https یاcursorساختگی.invalid_access_key401کلید فرستاده نشده، نامعتبر است، منقضی شده یا باطل شده.
access_denied403کلید دسترسی این API را ندارد (
gateway_accessبرای درگاه،merchant_accessبرای پذیرندهها)، یا درخواست از IPی بیرون از فهرست مجاز کلید آمده.owner_mobile_mismatch409این
external_idقبلاً با موبایل مالک دیگری ثبت شده.internal_error500خطای رینگپی. کمی بعد همان درخواست را تکرار کنید.