اتصال فروشگاه لاراولی به RamaPay
نسخه ۱٫۲ · ۲۷ سپتامبر ۲۰۲۶
ثبتنام پذیرنده · ورود پذیرنده
مسیر پذیرندگی
۱. مدیر فروشگاه با موبایل و کد ملی ثبتنام و کد یکبارمصرف را تأیید میکند. ۲. مشخصات حقوقی، دامنهٔ HTTPS و اینماد معتبر، IP خروجی سرور سایت، کارت ملی نماینده و دو حساب بانکی مستقل با شماره حساب، نام بانک، شبا، شماره کارت و نام صاحب حساب را در پنل ثبت میکند. تصویر مدرک کسبوکار فعلاً اختیاری است. هر دو حساب باید متعلق به طرف قرارداد باشند؛ استثنای حساب مدیرعامل شرکت فقط پس از بررسی مدیرکل است. ۳. مدیرکل کارمزد و روزهای تسویهٔ هر روش را تعیین میکند. پذیرنده متن قرارداد و پیوست مالی همان نسخه را میپذیرد. مدیرکل هویت، اینماد، حسابها و دامنه را بررسی و سپس فعال میکند. ۴. شناسه و دو کلید اتصال در پنل پذیرنده عرضه میشود. پنجرهٔ دیدن کلید از اولین مشاهده ۲۴ ساعت است؛ پس از آن رمز ذخیرهشده پاک میشود. در صورت گمشدن یا افشا، پذیرنده علت را ثبت میکند؛ مدیرکل پس از بررسی کلید جدید صادر میکند. صدور جدید کلید قبلی را فوراً باطل میکند.
کلیدها فقط روی سرور سایت نگهداری شوند؛ در فرانتاند، لاگ، مخزن Git، فایل عمومی و تیکت قرار نگیرند.
جریان پرداخت ثابت برای هر روش آینده
فروشگاه فقط یک گزینهٔ پرداخت RamaPay دارد. روشهای نقدی و اعتباری زیرمجموعهٔ سایت پذیرنده نیستند. سایر درگاههای همان جریان خرید را در نمایش، شروع پرداخت و callback سروری غیرفعال کنید؛ کیف پول داخلی فقط در صورت توافق جداگانه مستثناست. سرور RamaPay نمیتواند HTML یا کد سرور مستقل فروشگاه را از راه دور بازنویسی یا جلوی درگاه غیرمرتبط آن را بگیرد؛ مغایرت قابل کشف و رسیدگی قراردادی است.
سرور فروشگاه سفارش را قفل، مبلغ را به ریال صحیح محاسبه و POST /v1/payments را فراخوانی میکند. پاسخ payment_id و checkout_url را کنار سفارش ذخیره و مشتری را به همان URL پاسخ هدایت میکند. مشتری در صفحهٔ RamaPay روشهای فعال و مجاز را میبیند. افزودن آداپتور و فعالسازی روش تازه در RamaPay به تغییر اتصال فروشگاه نیاز ندارد. صرف ثبت نام یا توکن یک درگاه بدون اتصال و تأیید عملیاتی آن، روش جدیدی ایجاد نمیکند.
ساخت پرداخت
POST https://pay.ramalife.ir/v1/payments با هدر Content-Type: application/json و:
| هدر | مقدار |
|---|---|
X-API-Key |
کلید صادرشدهٔ این پذیرنده |
X-Timestamp |
ثانیهٔ Unix با اختلاف حداکثر ۳۰۰ ثانیه |
X-Nonce |
رشتهٔ تصادفی یکتای ۱۶ تا ۱۰۰ کاراکتر |
X-Signature |
hex lowercase از HMAC-SHA256(secret, timestamp + "." + nonce + "." + raw_body) |
بایتهای امضاشده و ارسالشده باید دقیقاً یکی باشند. IP مبدا باید همان IP خروجی تأییدشده باشد. حداکثر بدنه ۱۶ KiB و نرخ ۶۰ درخواست در دقیقه است.
{
"invoice_id": "AHURA-12345",
"amount_rials": 1520000,
"return_url": "https://shop.example.ir/payment/ramapay/return",
"gateway": "auto",
"order": {
"mobile": "09123456789",
"cart_id": "AHURA-12345",
"items": [{
"id": "SKU-42", "name": "دریل شارژی", "count": 1,
"unit_amount_rials": 1400000, "category": "TOOLS-DRILL",
"product_type": 1, "brand": "Drawolt"
}],
"shipping_rials": 120000, "tax_rials": 0,
"discount_rials": 0, "external_source_rials": 0
}
}نام هر کالا باید از snapshot واقعی کاتالوگ فروشگاه بیاید؛ مقادیر undefined، null و «تعریف نشده» پذیرفته نیست. سایت supplier_id و commission_type نمیفرستد؛ مدیرکل کد قراردادی تأمینکننده و نوع کمیسیونِ روش اعتباری را در RamaPay تعیین میکند. اطلاعات ناقص کالا را در سایت اصلاح کنید. تا ۴۰ قلم، شناسه/نام/دسته/برند رشتهٔ معتبر و همهٔ مبالغ عدد صحیح ریال باشند. amount_rials = Σ(count × unit_amount_rials) + shipping_rials + tax_rials − external_source_rials و مبلغ سفارش پس از کسر discount_rials است. از ارسال coupon_code با order خودداری کنید. حد پرداخت ۱۲٬۰۰۰ تا ۱۰۰٬۰۰۰٬۰۰۰٬۰۰۰ ریال است. رقم تومان در فروشگاه باید ×۱۰ شود.
دامنهٔ return_url دقیقاً باید دامنهٔ HTTPS تأییدشده باشد. برای هر سفارش invoice_id یکتا بگذارید؛ درخواست مجدد با مبلغ یا سبد متفاوت میتواند ۴۰۹ بدهد. نشست پرداخت ۱۵ دقیقه معتبر است.
آزمون اتصال
GET /v1/merchant/connection با همان چهار هدر، بدنهٔ خالی و امضای timestamp + "." + nonce + "." را فراخوانی کنید. 200 با status=ok و merchant_id مطابق پذیرنده به معنی تأیید کلید، امضا، وضعیت و IP است؛ به معنی تست پرداخت واقعی نیست. 404 از یک شناسهٔ تصادفی را نشانهٔ اتصال موفق فرض نکنید.
بازگشت، وبهوک و استعلام
مرورگر بعد از نمایش نتیجه و شمارش پنج ثانیهای یا کلیک «همین حالا»، به return_url برمیگردد و ramapay_payment_id در query دارد. بازگشت مرورگر بهتنهایی موفقیت نیست. سرور فروشگاه GET /v1/payments/{payment_id} را با همان امضا و بدنهٔ خالی استعلام میکند. فقط status=settled و تطبیق payment_id، invoice_id و amount_rials با رکورد قفلشدهٔ سفارش اجازهٔ paid و تحویل میدهد. paid_amount_rials ممکن است بهعلت کارمزد مشتری بیشتر باشد. پاسخ webhook نیز باید امضای X-RamaPay-Timestamp و X-RamaPay-Signature روی timestamp + "." + raw_body را کنترل و سپس همان استعلام را انجام دهد. callback و webhook همزمان باید idempotent باشند. برای بازگشت وجه، دکمهٔ استرداد آنلاین بدون API و مجوز عملیاتی اختصاصی فعال نکنید.
تغییر کلید، تسویه و خطا
پس از صدور کلید جدید، تنظیمات محرمانهٔ سرور فروشگاه یکبار عوض و اتصال دوباره آزموده میشود؛ این تنها تغییر لازم در رخداد چرخش کلید است. نرخها، کارمزد زودهنگام، تقویم و حسابها را مدیرکل در RamaPay تنظیم میکند. ثبت درخواست تسویهٔ زودتر، کارمزد و خالص همان نسخه را نشان میدهد ولی انتقال وجه فقط پس از تأیید و سند واریز واقعی است. خطاهای ۴۰۱، ۴۰۳، ۴۰۹، ۴۲۲، ۴۲۹ و ۵۰۳ را به ترتیب برای اعتبار، IP، تکرار/تعارض، داده، محدودیت و اختلال بررسی کنید. رازها و مشخصات هویتی را در گزارش خطا چاپ نکنید.
آزمون پذیرش: ثبتنام و OTP، تکمیل پرونده و دو حساب، بررسی مدیر، پذیرش قرارداد، صدور و مشاهدهٔ کلید، اتصال از IP مجاز و رد IP دیگر، ساخت سفارش واقعی، انتخاب نقدی، بازگشت و webhook تکراری، تطبیق settled، نمایش محصول واقعی، و سپس فعال کردن یک روش اعتباری آماده در پنل RamaPay بدون تغییر در سایت لاراول.
تلاش تازهٔ پرداخت و لغو سفارش
شناسهٔ invoice_id برای هر تلاش پرداخت تازه باید منحصربهفرد باشد. شناسهٔ ثابت سفارش فروشگاه را جداگانه نگه دارید. تلاش مجدد شبکه با همان شناسه idempotent است؛ کلیک تازهٔ خریدار شناسهٔ تلاش تازه میخواهد. اعتبار ۱۵ دقیقهٔ صفحه پرداخت، دلیل قفلکردن سفارش فروشگاه نیست. پیش از ساخت تلاش تازه، وضعیت تلاشهای قبلی را استعلام کنید؛ تنها settled با شناسه و مبلغ مطابق، مبنای تحویل سفارش است.
اگر فروشگاه سفارش را لغو کرد، درخواست امضاشده به POST /v1/payments/{payment_id}/merchant-cancellation بفرستد. بدنه شامل invoice_id دقیق همان تلاش و reason (۵ تا ۵۰۰ نویسه) است. نتیجهٔ settlement_hold=true پرداخت را از برآورد تسویه کنار میگذارد و به پنل مدیرکل میفرستد. این اعلام به معنی استرداد بانکی نیست؛ استرداد فقط پس از تأیید ارائهدهنده و ثبت سند معتبر قطعی است.
برای پرداخت اعتباری، کدهای sellerId و supplierId و commissionType سمت سرور RamaPay مدیریت میشوند و از پذیرنده خواسته نمیشوند. روشهای فعال جدید در صفحهٔ پرداخت RamaPay ظاهر میشوند و سایت پذیرنده فقط یک گزینهٔ پرداخت با RamaPay دارد.
آزمون پذیرش: دو فراخوانی همان invoice_id یک payment_id؛ کلیک تازه یک تلاش تازه؛ callback همزمان و تکراری حداکثر یک بار paid/تحویل؛ لغو در پنل مدیر و توقف تسویه؛ 429 با Retry-After برای بار بیش از حد.