ایجاد پرداخت

ساخت پرداخت و هدایت مشتری.

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

POST/api/v1/payments

پارامترها

نام	نوع	توضیح
`amount`الزامی	integer	مبلغ به ریال (عدد صحیح). باید در بازه حداقل و حداکثر مجاز درگاه باشد.
`callback_url`الزامی	string (url)	آدرس بازگشت مشتری. در هر دو حالت آزمایشی و عملیاتی باید https و روی دامنه تأییدشده درگاه (یا زیردامنه آن) باشد. فقط در حالت آزمایشی localhost و 127.0.0.1 هم پذیرفته می‌شوند.
`merchant_reference`	string ≤ 64	شناسه سفارش شما؛ برای هر درگاه و حالت یکتاست و از ثبت دوباره یک سفارش جلوگیری می‌کند.
`description`	string ≤ 255	توضیح قابل نمایش به مشتری در صفحه پرداخت.
`mobile`	string	موبایل مشتری (اختیاری)؛ برخی بانک‌ها برای نمایش کارت‌های ذخیره‌شده از آن استفاده می‌کنند.
`email`	string	ایمیل مشتری (اختیاری).
`customer_name`	string ≤ 120	نام مشتری (اختیاری).
`metadata`	object	حداکثر ۲۰ کلید با مقدار رشته، عدد یا بولی؛ در پاسخ‌ها و وب‌هوک‌ها برگردانده می‌شود.

هدرها

نام	نوع	توضیح
`Idempotency-Key`	string 8–128	توصیه‌شده. تکرار امن درخواست؛ جزئیات.

bash

curl -X POST https://api.sheypay.ir/api/v1/payments \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-create-1" \
  -d '{
    "amount": 1500000,
    "callback_url": "https://shop.example.ir/payment/callback",
    "merchant_reference": "ORDER-1042-1",
    "description": "خرید سفارش ۱۰۴۲",
    "mobile": "09121234567"
  }'

پاسخ

json

{
  "payment": {
    "id": "0199a4f2-6c1e-7d0a-9b1e-3f2a5c8d1e47",
    "status": "created",
    "mode": "test",
    "amount": 1500000,
    "fee": 0,
    "refunded_amount": 0,
    "currency": "IRR",
    "merchant_reference": "ORDER-1042-1",
    "tracking_code": "10000123",
    "reference_id": null,
    "rrn": null,
    "card_pan": null,
    "description": "خرید سفارش ۱۰۴۲",
    "metadata": {},
    "failure": null,
    "created_at": "2026-10-03T08:00:00.000Z",
    "paid_at": null,
    "verified_at": null,
    "verify_deadline_at": null,
    "expires_at": "2026-10-03T08:20:00.000Z",
    "settlement_status": "not_applicable"
  },
  "payment_url": "https://sheypay.ir/pay/k3Jd…"
}

مشتری را به payment_url هدایت کنید. پرداخت تا expires_at (به‌طور پیش‌فرض ۲۰ دقیقه) معتبر است.

وضعیت‌های پرداخت

created	ایجاد شده؛ مشتری هنوز به بانک نرفته
initiated / redirected	توکن از بانک گرفته شده / مشتری در صفحه بانک است
pending	نتیجه بانک نامشخص است؛ به‌صورت خودکار استعلام می‌شود
successful	وجه از مشتری دریافت شده؛ منتظر verify شما
verified	تأیید شده و قابل تسویه
settled	تسویه شده
failed / expired / cancelled	ناموفق، منقضی یا لغو شده
reversed	برگشت خورده (به کارت مشتری بازگشته)
refunded / partially_refunded	کامل یا بخشی از مبلغ مسترد شده

خطاهای رایج

400 amount_out_of_range — جزئیات شامل min_amount و max_amount است.
400 callback_domain_mismatch — آدرس بازگشت روی دامنه تأییدشده نیست.
409 already_exists — پرداختی با همین merchant_reference وجود دارد.