StardDevelopersداشبورد

بازپرداخت سفارش

POST/api/v1/orders/{id}/refund
scope: orders:writeاحراز هویت: Bearerlive و test

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

درخواست

ناممحلنوعتوضیح
AuthorizationheaderstringالزامیBearer sk_live_… یا Bearer sk_test_…
idpathstringالزامیکد پیگیری سفارش (ord_… یا کد live)

نمونه

curl -X POST "https://stard-market.ir/api/v1/orders/ord_test_gGToQWxqOw89ssiL/refund" \
  -H "Authorization: Bearer $STARD_API_KEY"
پاسخ — 200
{
  "object": "order",
  "id": "ord_test_9pq3kfjbTmRLfMDR",
  "order_id": null,
  "environment": "test",
  "status": "cancelled",
  "raw_status": "cancelled",
  "title": "⭐ 500 استارز برای @username (test)",
  "product_id": null,
  "product_tag": null,
  "type": "stars",
  "quantity": 500,
  "recipient": "@username",
  "amount": {
    "amount": 2249000,
    "currency": "IRT"
  },
  "paid": {
    "amount": 2249000,
    "currency": "IRT"
  },
  "failure_reason": null,
  "metadata": {
    "invoice": "INV-1042"
  },
  "created_at": "2026-10-02T17:43:22Z",
  "updated_at": "2026-10-02T17:43:22Z"
}
هدرهای پاسخ
content-type: application/json
x-request-id: req_dAlugYNqQS5ouO3hP82I
x-ratelimit-limit: 1000
x-ratelimit-remaining: 996

کاربرد و نکته‌ها

کی به کار می‌آید؟ وقتی سفارشی را ثبت کرده‌ای ولی هنوز انجامش شروع نشده و می‌خواهی پول برگردد؛ مثلاً یوزرنیم گیرنده اشتباه وارد شده یا مشتری فروشگاهت پشیمان شده است.

  1. وضعیت سفارش را با GET /orders/{id} بگیر؛ فقط سفارشی که انجامش شروع نشده خودکار برمی‌گردد.
  2. POST /orders/{id}/refund را بزن. پاسخ همان شیء سفارش با وضعیت تازه است و کل مبلغ به همان کیف پولی که از آن کسر شده بود برمی‌گردد.
  3. نتیجه را با GET /orders/{id}/refund یا وب‌هوک order.* تأیید کن.
  • سفارش انجام‌شده (استارز تحویل‌شده، گیفت ارسال‌شده) خودکار برنمی‌گردد و خطای 409 order_not_refundable می‌دهد؛ برای آن با پشتیبانی تماس بگیر.
  • سفارش بوستی که به پنل تحویل ارسال شده هم خودکار برنمی‌گردد؛ بخش تحویل‌نشده‌ی بوست را خود سیستم خودکار برمی‌گرداند.
  • در محیط test هیچ پول واقعی جابه‌جا نمی‌شود؛ رفتار پاسخ همان live است.

خطاها

HTTPcodeکی
409order_not_refundableانجام سفارش شروع شده یا تمام شده
404order_not_foundسفارش پیدا نشد
403insufficient_scopeکلید scope orders:write را ندارد
401invalid_api_key / missing_api_key / api_key_revoked / api_key_expiredکلید نیامده، نامعتبر، باطل یا منقضی است
429rate_limit_exceededسقف درخواست در دقیقه پر شده؛ بعد از Retry-After ثانیه دوباره بفرست

محدودیت نرخ

پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید (قابل تنظیم در داشبورد). وضعیت در هدرهای X-RateLimit-* برمی‌گردد — جزئیات.