استرداد

برگرداندن کامل یا جزئی وجه.

استرداد کامل یا جزئی یک پرداخت تأییدشده. مجموع استردادها نمی‌تواند از مبلغ پرداخت بیشتر شود.

POST/api/v1/payments/{id}/refunds

پارامترها

نام	نوع	توضیح
`amount`الزامی	integer	مبلغ استرداد به ریال.
`reason`	string ≤ 255	دلیل استرداد.

هدرها

نام	نوع	توضیح
`Idempotency-Key`الزامی	string 8–128	برای استرداد الزامی است تا retry شبکه منجر به استرداد دوباره نشود.

bash

curl -X POST https://api.sheypay.ir/api/v1/payments/PAYMENT_ID/refunds \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-1042-1" \
  -d '{ "amount": 500000, "reason": "مرجوعی کالا" }'

پاسخ

json

{ "refund": { "id": "…", "payment_id": "…", "amount": 500000, "status": "succeeded", … }, "payment": { "status": "partially_refunded", "refunded_amount": 500000, … } }

201: استرداد انجام شد.
202: درخواست به بانک ارسال شد ولی نتیجه هنوز مشخص نیست (refund.status = processing). مبلغ رزرو می‌ماند؛ در صورت موفقیت وب‌هوک payment.refunded ارسال می‌شود و وضعیت را می‌توانید با استعلام پرداخت پیگیری کنید. تکرار با همان Idempotency-Key همین پاسخ را برمی‌گرداند و استرداد دوباره انجام نمی‌شود.

محدودیت‌ها

استرداد فقط برای پرداخت‌های verified، settled یا partially_refunded و در مهلت مجاز (پیش‌فرض ۳۰ روز) ممکن است.
اگر شبکه پرداخت مربوط به آن تراکنش استرداد را پشتیبانی نکند، پاسخ 422 capability_not_supported برمی‌گردد؛ در این حالت از طریق پشتیبانی درخواست استرداد بانکی ثبت کنید.
در زمانی که پرداخت در حال تسویه است، استرداد موقتاً با 409 رد می‌شود.
مبلغ استرداد از موجودی شما کسر می‌شود؛ کارمزد تراکنش اصلی برگردانده نمی‌شود.