شروع سریع

در این راهنما اولین پرداخت آزمایشی را از ابتدا تا verify انجام می‌دهید. هیچ پول واقعی جابه‌جا نمی‌شود.

۱. ساخت حساب و کلید آزمایشی

1. در صفحه ثبت‌نام با شماره موبایل حساب بسازید و حساب پذیرندگی ایجاد کنید.
2. در بخش «تنظیمات»، دامنه سایت خود را اضافه و در «API و درگاه‌ها» درخواست درگاه ثبت کنید.
3. بلافاصله (حتی پیش از تأیید درگاه) کلید sk_test_… بسازید. کلید فقط یک بار نمایش داده می‌شود؛ آن را در متغیر محیطی سرور نگه دارید.

۲. ایجاد پرداخت

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"
  }'

پاسخ 201 شامل شیء payment و payment_url است. شناسه payment.id را کنار سفارش ذخیره کنید و مشتری را به payment_url هدایت کنید.

{
  "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…"
}

۳. پرداخت در صفحه آزمایشی

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

۴. verify در callback

آدرس بازگشت این پارامترها را دارد: payment_id، status (success، pending یا failed)، merchant_reference و tracking_code. این پارامترها فقط راهنما هستند؛ پرداخت را همیشه با verify نهایی کنید.

curl -X POST https://api.sheypay.ir/api/v1/payments/PAYMENT_ID/verify \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1500000 }'

۵. قدم‌های بعدی

• وب‌هوک تنظیم کنید تا از تغییر وضعیت‌ها مطلع شوید.
• هدر Idempotency-Key را به درخواست‌ها اضافه کنید.
• پس از تأیید مدارک، حالت عملیاتی را فعال و کلید sk_live_ را جایگزین کنید.