پیاده‌سازی خرید حضوری

سوپر اپلیکیشن مهراد

این سند راهنمای پیاده‌سازی خرید حضوری برای توسعه‌دهندگان پذیرنده است؛ حالتی که مشتری به صورت فیزیکی در فروشگاه حاضر است و با اپلیکیشن مهراد پرداخت می‌کند.

معرفی خرید حضوریCopy Anchor Link

در جریان آنلاین (بخش مستندات سفارش) مشتری در سایت پذیرنده سبد خرید می‌سازد و برای پرداخت به مهراد هدایت می‌شود.

در خرید حضوری سبد خرید و مرورگری در کار نیست؛ مشتری روبه‌روی صندوق ایستاده است. بنابراین:

1. پذیرنده اقلام خرید را ثبت می‌کند و یک خرید حضوری (Order Draft) می‌سازد.
2. مهراد یک کد پیگیری ۸ رقمی و یک لینک پرداخت برمی‌گرداند که پذیرنده آن را به شکل QR یا عدد به مشتری نشان می‌دهد.
3. مشتری در اپلیکیشن مهراد کد را وارد یا QR را اسکن می‌کند، خرید را باز می‌کند و از دارایی‌های خود پرداخت می‌کند.
4. پذیرنده پرداخت را تأیید (Verify) می‌کند و مبلغ برای او نهایی می‌شود.

تفاوت کلیدی با جریان آنلاین: در خرید حضوری، پذیرنده هیچ‌گاه authority (ID تلاش پرداخت) را دریافت نمی‌کند، چون پرداخت در دستگاه مشتری انجام می‌شود. به همین دلیل تأیید پرداخت با order_id انجام می‌شود، نه با authority.

مرحلهٔ ۳ کاملاً توسط اپلیکیشن مهراد انجام می‌شود و پیاده‌سازی آن بر عهدهٔ پذیرنده نیست.

روش‌های استفادهCopy Anchor Link

خرید حضوری به دو روش قابل استفاده است:

استفاده از پنل پذیرندهCopy Anchor Link

در پنل پذیرنده، سرویس، اقلام خرید، هزینه‌های جانبی، تخفیف و در صورت نیاز توضیح سفارش وارد می‌شود. مبلغ نهایی و ID سفارش به‌صورت خودکار توسط پنل محاسبه و تولید می‌شوند. پس از ساخت خرید، پنل QR، کد پیگیری ۸ رقمی و زمان انقضای خرید را نمایش می‌دهد. پس از پرداخت مشتری، تأیید پرداخت از صفحهٔ جزئیات همان سفارش در بخش سفارش‌های حضوری پنل انجام می‌شود.

این روش به هیچ پیاده‌سازی API نیاز ندارد؛ قواعد مبلغ، مهلت‌ها و چرخهٔ عمر سفارش که در ادامه آمده است در این روش نیز برقرار است.

یکپارچه‌سازی با سیستم فروشگاهی پذیرندهCopy Anchor Link

ادامهٔ این سند برای تیم‌هایی است که ساخت خرید و تأیید پرداخت را از سیستم فروشگاهی خود انجام می‌دهند. این ارتباط سرور-به-سرور است و با token اپلیکیشن پذیرنده انجام می‌شود.

هر دو endpoint با token اپلیکیشن پذیرنده در header Authorization فراخوانی می‌شوند؛ نحوهٔ دریافت token در مستندات ارتباط پذیرندگان آمده است.

پیش‌نیازهاCopy Anchor Link

برای یکپارچه‌سازی با سیستم فروشگاهی، موارد زیر لازم است:

• حساب پذیرنده فعال در مهراد.
• client_id و client_secret اپلیکیشن پذیرنده برای دریافت token.
• service_id یکی از سرویس‌های فعال حساب پذیرنده؛ این مقدار برای ساخت خرید الزامی است و باید از اطلاعات پیکربندی یکپارچه‌سازی دریافت شود.
• امکان تولید و نمایش QR یا نمایش کد ۸ رقمی به مشتری.
• یک ID یکتا برای هر سفارش در سیستم پذیرنده (external_order_id).

مرحله ۱ — ساخت خرید حضوریCopy Anchor Link

Authentication: token اپلیکیشن پذیرنده در header Authorization.

مقادیری که توسط پذیرنده تولید می‌شوندCopy Anchor Link

مقادیری که API تولید می‌کندCopy Anchor Link

draft_id، tracking_code، expires_at و draft_url را API می‌سازد؛ این مقادیر نباید ارسال شوند.

ورودی (Request Body)Copy Anchor Link

این endpoint از فیلد items (ساختار منسوخ جریان آنلاین) پشتیبانی نمی‌کند و اقلام تنها از طریق shipments ثبت می‌شوند؛ فیلد items در صورت ارسال نادیده گرفته می‌شود. اگر shipments ارسال نشود، response آن با کد ۴۲۲ و خطای VALIDATION_ERROR برگردانده می‌شود.

در صورت وجود دو قلم با ID کالا (product.id) و تنوع (variant.id) یکسان در یک request، حتی در مرسوله‌های متفاوت، کل request با خطای DUPLICATE_ORDER_ITEM رد می‌شود.

توجه: services با service_id یکی نیست. service_id سرویس پذیرنده است و services ردیف‌های هزینهٔ جانبی همین سفارش است.

قاعدهٔ مبلغCopy Anchor Link

مقدار amount باید دقیقاً برابر باشد با:

amount = SUM(price × quantity همهٔ اقلام) + SUM(shipments.shipping_fee) + SUM(services.amount) - discount_amount

اگر این تساوی برقرار نباشد request با INVALID_ORDER_AMOUNT رد می‌شود و اگر حاصل صفر یا منفی شود با ORDER_AMOUNT_NOT_POSITIVE.

نمونه requestCopy Anchor Link

{
  "service_id": "2f1b7d6e-2f4e-4a1a-9c22-6f0c0a1d5b31",
  "amount": 3100000,
  "external_order_id": "POS-2026-000184",
  "description": "خرید از شعبه مرکزی",
  "shipments": [
    {
      "id": "S1",
      "shipping_fee": 0,
      "items": [
        {
          "product": {
            "id": "SKU-7781",
            "title": "هدفون بی‌سیم",
            "url": "https://shop.example.com/product/SKU-7781",
            "image": {
              "url": "https://shop.example.com/media/SKU-7781.webp",
              "thumbnail_url": "https://shop.example.com/media/SKU-7781-thumb.webp"
            },
            "variant": {
              "id": "SKU-7781-black",
              "title": "مشکی"
            }
          },
          "price": 1250000,
          "quantity": 2,
          "category": "لوازم جانبی"
        },
        {
          "product": {
            "id": "SKU-1042",
            "title": "کابل USB-C یک متری",
            "url": "https://shop.example.com/product/SKU-1042",
            "image": {
              "url": "https://shop.example.com/media/SKU-1042.webp",
              "thumbnail_url": "https://shop.example.com/media/SKU-1042-thumb.webp"
            },
            "variant": {
              "id": "SKU-1042-white",
              "title": "سفید"
            }
          },
          "price": 150000,
          "quantity": 3,
          "category": "لوازم جانبی"
        }
      ]
    }
  ],
  "services": [
    {
      "title": "نصب",
      "amount": 200000
    },
    {
      "title": "بسته‌بندی",
      "amount": 50000
    }
  ],
  "discount_amount": 100000
}

محاسبهٔ مبلغ این نمونه:

(1250000 × 2) + (150000 × 3) + 0 + (200000 + 50000) - 100000 = 3100000

ResponseCopy Anchor Link

{
  "success": true,
  "data": {
    "draft_id": "9b1c4f52-1f2a-4f33-8a77-2c0b9b0d51aa",
    "tracking_code": "48219307",
    "expires_at": "2026-09-20T10:35:12.480000+00:00",
    "draft_url": "https://pwa.mehrad.app/purchase/9b1c4f52-1f2a-4f33-8a77-2c0b9b0d51aa"
  },
  "meta": null
}

مقادیر قابل ذخیره و نمایشCopy Anchor Link

مقادیر لازم برای ذخیره: draft_id (برای تأیید پرداخت در مرحلهٔ ۳ لازم است) و expires_at.

موارد قابل نمایش به مشتری: مبلغ نهایی، تصویر QR ساخته‌شده از draft_url، کد پیگیری ۸ رقمی به عنوان روش جایگزین، و زمان باقی‌مانده تا انقضا.

خرید ساخته‌شده ۵ دقیقه اعتبار دارد. تا وقتی مشتری آن را باز نکرده باشد، هیچ سفارشی ثبت نشده است و پس از انقضا باید خرید جدیدی ساخته شود.

مرحله ۲ — باز کردن خرید و پرداخت توسط مشتریCopy Anchor Link

این مرحله کاملاً در اپلیکیشن مهراد انجام می‌شود و به پیاده‌سازی توسط پذیرنده نیاز ندارد. آنچه پذیرنده باید از این مرحله بداند:

• مشتری با اسکن QR یا وارد کردن کد ۸ رقمی، محتوای خرید (اقلام، خدمات، تخفیف، مبلغ و نام پذیرنده) را می‌بیند.
• با باز شدن خرید توسط مشتری، سفارش با channel = IN_PERSON ساخته می‌شود و order_id آن همان draft_id است. در همین لحظه یک تلاش پرداخت با وضعیت PENDING ایجاد می‌شود.
• هر خرید فقط یک‌بار قابل باز شدن است؛ پس از باز شدن یا انقضا، همان کد یا QR دیگر قابل استفاده نیست.
• با پرداخت موفق، مبلغ از حساب مشتری برداشت و نگهداری می‌شود و وضعیت تلاش پرداخت به PAID تغییر می‌کند. مبلغ تا تأیید پذیرنده برای او نهایی نمی‌شود.
• callback_url اختیاری است. اگر ارسال شود، پس از پرداخت یا لغو مشتری به آن هدایت می‌شود. اگر ارسال نشود، مشتری در اپلیکیشن می‌ماند.

مرحله ۳ — تأیید پرداختCopy Anchor Link

Authentication: token اپلیکیشن پذیرنده در header Authorization.

تأیید پرداخت مرحلهٔ نهایی و الزامی است؛ بدون آن مبلغ برای پذیرنده نهایی نمی‌شود. در خرید حضوری، تأیید با order_id انجام می‌شود.

ورودیCopy Anchor Link

{
  "order_id": "9b1c4f52-1f2a-4f33-8a77-2c0b9b0d51aa",
  "amount": 3100000
}

ResponseCopy Anchor Link

{
  "success": true,
  "data": {
    "ref_id": "5f7d1a30-1c77-4a2b-b6d1-0f3f41f9c5e2",
    "status": "VERIFY_OK",
    "fee": 15500
  },
  "meta": null
}

• status برابر VERIFY_OK یعنی تأیید موفق بوده است.
• ref_id، ID تراکنش نهایی است و برای پیگیری و تطبیق حساب باید ذخیره شود.
• fee کارمزد سامانه برای این تراکنش است.

پس از تأیید موفق: وضعیت سفارش SUCCESS می‌شود، مبلغ برای پذیرنده نهایی می‌گردد و پیامک تأیید خرید برای مشتری ارسال می‌شود.

تشخیص انجام‌شدن پرداختCopy Anchor Link

authority در اختیار پذیرنده نیست؛ وضعیت پرداخت از همین endpoint تأیید مشخص می‌شود:

مبلغ تأییدCopy Anchor Link

مبلغ ارسالی با مبلغ پرداخت‌شده مقایسه می‌شود. اگر این دو برابر نباشند، تأیید با ORDER_AMOUNT_NOT_MATCHED رد می‌شود و تلاش پرداخت باطل می‌شود؛ یعنی دیگر امکان تأیید همان پرداخت وجود ندارد.

اگر سفارش متعلق به پذیرندهٔ دیگری باشد، request با ORDER_MERCHANT_NOT_MATCHED رد می‌شود و پرداخت دست‌نخورده باقی می‌ماند.

محدودیت زمانی تأییدCopy Anchor Link

تأیید باید حداکثر تا ۳۰ دقیقه پس از ایجاد تلاش پرداخت انجام شود. پس از آن پرداخت به صورت خودکار بسته و مبلغ به مشتری بازگردانده می‌شود و وضعیت تلاش پرداخت VERIFY_TIMEOUT خواهد شد.

مرحله ۴ — مدیریت نتیجهٔ نهاییCopy Anchor Link

وضعیت‌هاCopy Anchor Link

وضعیت سفارشCopy Anchor Link

وضعیت تلاش پرداختCopy Anchor Link

سفارش‌های این جریان همیشه channel = IN_PERSON دارند و در پنل پذیرنده در بخش سفارش‌های حضوری نمایش داده می‌شوند.

قواعد اعتبارسنجی و محدودیت‌هاCopy Anchor Link

قواعدی که API اعمال می‌کندCopy Anchor Link

محدودیت‌های زمانیCopy Anchor Link

قواعد اعتبارسنجیCopy Anchor Link

در صورت رعایت نشدن هر یک از این موارد، request رد می‌شود:

• shipments ارسال شده باشد.
• مبلغ نهایی با اقلام، shipping_fee مرسوله‌ها، خدمات و تخفیف برابر و بزرگ‌تر از صفر باشد.
• قیمت هر قلم و مبلغ هر خدمت بزرگ‌تر از صفر باشد.
• تعداد هر قلم عدد صحیح و حداقل ۱ باشد.
• shipping_fee و تخفیف منفی نباشد.
• یک کالا با ID و تنوع یکسان بیش از یک‌بار نیامده باشد.
• طول فیلدهای متنی از حداکثر مجاز بیشتر نباشد.

external_order_id هنگام ساخت خرید برای یکتا بودن بررسی نمی‌شود. اثر آن در لحظهٔ باز کردن خرید است: اگر این مقدار به سفارشی پرداخت‌شده تعلق داشته باشد، خرید باز نمی‌شود و اگر به سفارشی پرداخت‌نشده تعلق داشته باشد، پرداخت به همان سفارش قبلی وصل می‌شود و draft_id جدید سفارش تازه‌ای نخواهد ساخت. اگر سفارش پرداخت‌نشده متعلق به مشتری دیگری باشد، خرید باز نمی‌شود.

فهرست خطاهاCopy Anchor Link

اگر request با خطا مواجه شود، response آن کدی غیر از ۲xx دارد و success در آن false است. کد خطا در فیلد error.code و متن قابل نمایش در error.message برگردانده می‌شود. ساختار کامل خطا در بخش مقدمه آمده است. خطاهای مشترک همهٔ endpoint‌ها (VALIDATION_ERROR، FINANCIAL_OPERATIONS_FROZEN و نبود header Authorization) در همان بخش آمده‌اند.

ساخت خرید حضوریCopy Anchor Link

{
  "success": false,
  "error": {
    "code": "SERVICE_NOT_OFFERED_BY_MERCHANT",
    "message": "برای این پذیرنده، سرویس مورد نظر وجود ندارد.",
    "details": null
  }
}

تأیید پرداختCopy Anchor Link

{
  "success": false,
  "error": {
    "code": "ORDER_ATTEMPT_NOT_PAID",
    "message": "برای این سفارش پرداختی انجام نشده است.",
    "details": null
  }
}

سایر خطاهای token اپلیکیشن پذیرنده در مستندات ارتباط پذیرندگان آمده است.

چک‌لیست پیاده‌سازیCopy Anchor Link

• دریافت token اپلیکیشن پذیرنده و مدیریت انقضای آن
• نگهداری service_id سرویس فعال پذیرنده در تنظیمات سیستم فروشگاهی
• تولید external_order_id یکتا برای هر سفارش
• ساخت اقلام، خدمات و تخفیف و محاسبهٔ amount طبق قاعدهٔ مبلغ
• اعتبارسنجی مقادیر پیش از ارسال (تعداد، قیمت، تخفیف)
• فراخوانی POST /gateway/order/draft/request
• ذخیرهٔ draft_id و expires_at از response
• نمایش QR (از draft_url)، کد پیگیری و مبلغ به مشتری
• نمایش زمان باقی‌مانده و ساخت خرید جدید پس از انقضای ۵ دقیقه‌ای
• فراخوانی POST /gateway/order/payment/verify با draft_id به عنوان order_id و مبلغ دقیق
• ذخیرهٔ ref_id و نمایش نتیجهٔ نهایی به مشتری
• مدیریت خطاهای تأیید (ORDER_NOT_FOUND، ORDER_ATTEMPT_NOT_PAID، ORDER_AMOUNT_NOT_MATCHED، ORDER_ALREADY_PAID)
• رعایت مهلت ۳۰ دقیقه‌ای تأیید و مدیریت VERIFY_TIMEOUT