خانه درگاه پرداخت مستندات API مستندات SDK راهنمای استفاده افزونه‌ها

# استرداد وجه

به کمک سرویس استرداد وجه (ریفاند) زرین‌پال، در صورت تغییر یا لغو سفارش مشتریان، واریزی‌های اشتباه یا هرگونه الزامی جهت بازگرداندن وجه به خریدار، تمام مبلغ واریز شده یا حتی بخشی از آن را به صورت آنی یا در سیکل های پایا، خودکار به حساب آن‌ها واریز نمایید.

کالکشن پست من (opens new window)

# شماره تراکنش و مبلغ

برای استفاده از این سرویس، نیاز به اطلاعاتی شامل شماره تراکنش مورد نظر و مبلغ آن است که در قسمت تراکنش‌ها قابل مشاهده است.

# استرداد عادی یا آنی

برای استرداد عادی که مبلغ در سیکل پایای بعد به حساب خریدار باز میگردد :
فیلد method را در ثبت درخواست برابر با PAYA قرار دهید

برای استرداد آنی که مبلغ در همان لحظه به حساب خریدار برمیگردد :
فیلد method را در ثبت درخواست برابر با CARD قرار دهید

# استعلام وضعیت استرداد وجه (Inquiry)

در صورتی که پس از ثبت درخواست استرداد، وضعیت تراکنش در حالت PENDING قرار گرفت ، می‌توانید برای دریافت وضعیت نهایی و قطعی تراکنش، از پرس‌وجوی (Query) استعلام وضعیت استفاده کنید.

# متغیرهای مورد نیاز (Query Variables)

برای استعلام، به شماره تراکنش اصلی و شماره ترمینال درگاه خود نیاز دارید:

  • id: شماره تراکنش (Session ID)
  • terminal_id: شماره ترمینال درگاه
{
  "id": "829492417",
  "terminal_id": "535823"
}

# پرس‌وجوی GraphiQL

می‌توانید از کوئری SessionById زیر برای دریافت وضعیت استفاده کنید. خروجی این کوئری به صورت خلاصه و کاربردی تنظیم شده است:

query SessionById($terminal_id: ID, $id: ID) {
  Session(terminal_id: $terminal_id, id: $id) {
    id
    amount
    status
    terminal {
      id
    }
    timeline {
      refund_status
      refund_amount
      refund_time
    }
  }
}

# پاسخ دریافتی

در پاسخ درخواست استعلام، از سمت زرین‌پال پاسخ زیر شامل اطلاعات پایه تراکنش و تاریخچه استرداد (Timeline) برگردانده می‌شود. شما باید فیلد refund_status را برای اطلاع از وضعیت نهایی چک کنید که می‌تواند شامل وضعیت‌های قطعی مانند SUCCESS یا FAILED باشد.

  • id: شماره تراکنش
  • amount: مبلغ اصلی تراکنش به ریال
  • terminal: اطلاعات ترمینال درگاه
  • timeline: تاریخچه و وضعیت استرداد
  • refund_amount: مبلغ استرداد شده
  • refund_time: تاریخ و زمان ثبت استرداد
  • refund_status: وضعیت فعلی استرداد (مثلاً SUCCESS, PENDING, FAILED)
{
  "data": {
    "Session": [
      {
        "id": "829492417",
        "amount": 10000,
        "status": "PAID",
        "terminal": {
          "id": "535823"
        },
        "timeline": {
          "refund_amount": 10000,
          "refund_time": "2026-02-17T13:35:59+03:30",
          "refund_status": "SUCCESS"
        }
      }
    ]
  }
}

# ثبت درخواست

پس از به دست آوردن شماره تراکنش و مبلغ آن برای ثبت درخواست استرداد وجه از درخواست زیر استفاده کنید:

پارامتر های مورد نیاز

  • session_id شماره تراکنش

  • amount مبلغ ریال (حداقل مبلغ قابل استرداد ۲۰۰۰۰ ریال)

  • description توضیح علت استرداد وجه

  • method متد استرداد وجه

    • PAYA عادی (مبلغ در سیکل بعدی پایا واریز خواهد شد.)

    • CARD آنی (مبلغ آنی واریز می‌شود.)

  • reason دلیل استرداد

    • CUSTOMER_REQUEST درخواست خریدار

    • DUPLICATE_TRANSACTION تراکنش تکراری

    • SUSPICIOUS_TRANSACTION تراکنش مشکوک

    • OTHER سایر

شما می‌توانید در محیط اجرای GraphiQL (opens new window) پرس‌و‌جوهای فوق را تست کنید.





Query Variables برای استرداد عادی 
{
  "session_id": "385404123",
  "amount": 11000,
  "description": "تست سرویس",
  "method": "PAYA" // استرداد عادی
  "reason": "CUSTOMER_REQUEST"
}


mutation AddRefund(
  $session_id: ID!
  $amount: BigInteger!
  $description: String
  $method: InstantPayoutActionTypeEnum
  $reason: RefundReasonEnum
) {
  resource: AddRefund(
    session_id: $session_id
    amount: $amount
    description: $description
    method : $method
    reason: $reason
  ) {
    terminal_id
    id
    amount
    timeline {
      refund_amount
      refund_time
      refund_status
    }
  }
}

Query Variables برای استرداد آنی

{
  "session_id": "385404123",
  "amount": 11000,
  "description": "تست سرویس",
  "method": "CARD" // استرداد آنی
  "reason": "CUSTOMER_REQUEST"
}

# پاسخ دریافتی

در پاسخ درخواست استرداد وجه ثبت شده، از سمت زرین‌پال پاسخ روبرو شامل: شماره تراکنش، مبلغ، شماره ترمینال، تاریخچه پرداخت و بازگشت را دریافت می‌کنید.

  • id شماره تراکنش

  • amount مبلغ پرداخت شده به ریال

  • terminal اطلاعات ترمینال درگاه

  • timeline تاریخچه تراکنش

    • refund_amount مبلغ استرداد

    • refund_time تاریخ ثبت استرداد

    • refund_status وضعیت استرداد


{
  "data": {
    "resource": {
      "terminal_id": "1915487",
      "id": "386426364",
      "amount": 20000,
      "timeline": {
        "refund_amount": 20000,
        "refund_time": "2022-11-02T15:15:37+03:30",
        "refund_status": "PENDING"
      }
    }
  }
}