# اتصال فروشگاه لاراولی به RamaPay

**نسخه ۱٫۲ · ۲۷ سپتامبر ۲۰۲۶**

[ثبت‌نام پذیرنده](https://pay.ramalife.ir/panel/mobile/register) · [ورود پذیرنده](https://pay.ramalife.ir/panel/mobile/login)

## مسیر پذیرندگی

۱. مدیر فروشگاه با موبایل و کد ملی ثبت‌نام و کد یک‌بارمصرف را تأیید می‌کند.
۲. مشخصات حقوقی، دامنهٔ 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 و نرخ ۶۰ درخواست در دقیقه است.

```json
{
  "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 بدون تغییر در سایت لاراول.


---

# RamaPay — دستور اتصال و عملیات سفارش (نسخهٔ پیشنهادی ۲)

## تلاش‌های پرداخت

`invoice_id` شناسهٔ **تلاش پرداخت** است، نه شناسهٔ ثابت سفارش فروشگاه. برای هر کلیک تازهٔ مشتری روی «پرداخت»، یک UUID جدید بسازید و به‌عنوان `invoice_id` به `POST /v1/payments` بفرستید. در پایگاه دادهٔ فروشگاه، `order_id` ثابت، `invoice_id` تلاش، `payment_id` برگشتی و `checkout_url` همان پاسخ را کنار هم نگه دارید. فقط همان `checkout_url` را استفاده کنید. تلاش مجدد شبکه برای *همان* درخواست و همان `invoice_id` باید همان نتیجه را بدهد؛ تلاش تازهٔ کاربر باید `invoice_id` تازه داشته باشد. نشست صفحهٔ پرداخت ۱۵ دقیقه اعتبار دارد، اما نباید سفارش فروشگاه را ۱۵ دقیقه برای ایجاد تلاش جدید قفل کند.

پیش از ایجاد تلاش تازه، وضعیت تلاش‌های قبلی همان سفارش را از `GET /v1/payments/{payment_id}` بررسی کنید. اگر هرکدام `settled` است، سفارش را دوباره به پرداخت نفرستید. اگر وضعیت `pending`, `verifying`, `settling` یا `review` است، از تحویل سفارش جلوگیری کنید و برای استعلام یا رسیدگی مشخص نگه دارید؛ ایجاد تلاش تازه، احتمال پرداخت دوباره را حذف نمی‌کند. با callback و webhook هم‌زمان، تغییر سفارش به paid و تحویل باید داخل تراکنش دیتابیس و حداکثر یک‌بار انجام شود. `payment_id` موفق باید یکتا باشد. تطبیق `invoice_id`, مبلغ و `merchant_id` الزامی است. پاسخ مرورگر به‌تنهایی سند پرداخت نیست.

کنترل نرخ سرور برای هر پذیرنده تا ۱۲۰ درخواست در ثانیه و ۱۲۰۰ در دقیقه است؛ پاسخ 429 با `Retry-After: 1` ممکن است. این سقف تضمین ظرفیت بانک یا درگاه نیست و در سمت فروشگاه صف/بازآزمایی محدود لازم است.

## اطلاعات سفارش و صفحه پرداخت

برای پرداخت اعتباری، موبایل واقعی خریدار و اقلام واقعی (نام، شناسه کالا، تعداد، مبلغ ریالی و دسته/نوع مطابق API) را با سفارش بفرستید. هیچ‌یک از `sellerId`, `supplierId`, `commissionType` یا درصد کارمزد از سایت پذیرنده درخواست نشود. RamaPay کدهای مربوط به ارائه‌دهنده را فقط در سرور مدیریت می‌کند؛ بدون شناسهٔ تأییدشدهٔ قراردادی، روش اعتباری نمایش داده نمی‌شود. روش‌های نقدی زیر یک گزینهٔ واحد دیده می‌شوند. تغییر روش‌های فعال و ظاهر صفحه در سرور RamaPay انجام می‌شود.

## اعلام لغو و توقف تسویه

اگر سفارش در فروشگاه لغو شد، سایت فروشگاه بلافاصله با همان احراز امضای API به `POST /v1/payments/{payment_id}/merchant-cancellation` درخواست بزند:

```json
{"invoice_id":"شناسه دقیق تلاش پرداخت","reason":"لغو سفارش توسط مشتری پس از ثبت درخواست"}
```

شناسهٔ تلاش باید با همان پرداخت تطبیق کند. پاسخ `settlement_hold=true` یعنی پرداخت از *برآورد قابل تسویه* کنار گذاشته و برای مدیرکل فهرست شده است. این پاسخ به معنی استرداد وجه یا برگشت تراکنش بانکی نیست. اگر پول واقعاً دریافت شده باشد، استرداد باید جداگانه با ارائه‌دهنده تأیید و در دفتر مالی ثبت شود. مدیرکل فهرست را در `/panel/merchant-cancellations` می‌بیند و فقط با دلیل ثبت‌شده می‌تواند توقف را رفع کند. تماس ناموفق با API لغو را در فروشگاه برای retry امن صف کنید؛ تا پاسخ معتبر نگرفته‌اید، توقف تسویه را قطعی فرض نکنید.

## امضای درخواست

طبق نسخهٔ فعلی RamaPay: `X-API-Key`, `X-Timestamp`, `X-Nonce`, `X-Signature`. امضا HMAC-SHA256 روی `timestamp + '.' + nonce + '.' + raw_body` با secret پذیرنده است؛ برای GET بدنهٔ خالی و برای POST بایت‌های دقیق JSON ارسال‌شده. nonce در هر تلاش تازه منحصر‌به‌فرد باشد. کلید و secret فقط در سمت سرور فروشگاه نگهداری شوند.

## تست پذیرش

۱. دو درخواست شبکه با یک `invoice_id` و دادهٔ یکسان → یک `payment_id`؛ کلیک تازه با `invoice_id` تازه → تلاش تازه. ۲. ۱۰۰ سفارش مستقل در یک ثانیه → پاسخ‌های معتبر یا 429 با retry کنترل‌شده و بدون تحویل دوباره. ۳. callback هم‌زمان/تکراری → paid و تحویل فقط یک‌بار. ۴. لغو قبل/بعد از پرداخت → اعلام در پنل مدیر و توقف برآورد تسویه، بدون اعلام استرداد جعلی. ۵. روش جدید در RamaPay → نمایش در سفارش تازهٔ همان پذیرنده بدون تغییر کد سایت.
