مستندات API

شروع سریع

چهار کار تا اولین پرداخت تأییدشده فاصله دارید. ترتیب مهم است: پیامک بانک شاهدِ پرداخت است، پس تا فورواردر وصل نشود هیچ فاکتوری خودکار تأیید نمی‌شود.

1. ۰۱

   حساب پذیرنده بسازید

   در صفحه ثبت‌نام شماره موبایل و گذرواژه را وارد کنید. حساب در وضعیت «در انتظار تأیید» ساخته می‌شود و تا تأیید مدیر، درخواست‌های API با کد ACCOUNT_PENDING_APPROVAL رد می‌شوند.

2. ۰۲

   کلید API بگیرید

   پس از تأیید، از پنل پذیرنده → کلیدهای API کلید بسازید. کلید یک‌بار و فقط یک‌بار نشان داده می‌شود؛ فقط هش آن ذخیره است. اگر گم شد، همان کلید را بچرخانید.

3. ۰۳

   کارت مقصد را ثبت کنید

   در پنل پذیرنده → کارت‌ها شماره کارتی که پول به آن واریز می‌شود را اضافه کنید. بدون کارت فعال، ساخت فاکتور با کد CARD_REQUIRED رد می‌شود. شماره کارت مشتری هرگز ذخیره نمی‌شود.

4. ۰۴

   فورواردر پیامک را وصل کنید

   روی گوشی اندرویدی که پیامک بانک را می‌گیرد، برنامه فورواردر را به POST /sms وصل کنید — راهنمای کامل. تا این مرحله انجام نشود، مبلغ واریز می‌شود ولی فاکتور تأیید نمی‌شود.

احراز هویت

کلید را در هدر X-API-Key بفرستید. هدر Authorization: Bearer <key> هم پذیرفته می‌شود، چون بعضی برنامه‌های فورواردر فقط یکی از این دو را می‌توانند تنظیم کنند.

شکل کلید

کلید از پیشوند محیط، یک شناسه ۱۲ نویسه‌ای و یک راز ۳۲ نویسه‌ای ساخته می‌شود: sk_live_ به‌علاوه ۴۴ نویسه. کلید کامل تنها در لحظه ساخت نمایش داده می‌شود و در پایگاه‌داده فقط HMAC آن با یک فلفل نگه داشته می‌شود — یعنی حتی مدیر سامانه هم نمی‌تواند کلید شما را بخواند.

دو محیط

دسترسی‌ها

هر کلید فهرست دسترسی مشخصی دارد. اگر کلیدی دسترسی یک اندپوینت را نداشته باشد، پاسخ INSUFFICIENT_SCOPE با کد ۴۰۳ است.

هر کلید می‌تواند فهرست IP مجاز داشته باشد. اگر فهرست خالی نباشد، درخواست از هر IP دیگری با IP_NOT_ALLOWED رد می‌شود — و این بررسی پیش از هر کار دیگری انجام می‌شود.

ساخت پرداخت

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

{
  "amount": 359000,                    // تومان — مبلغ سفارش، عدد صحیح
  "description": "سفارش ۱۲۳۴",          // روی صفحه پرداخت دیده می‌شود
  "customCallback": "https://shop.example.com/pay/cb",
  "returnUrl": "https://shop.example.com/orders/1234",
  "metadata": { "orderId": "1234" },      // در وب‌هوک برمی‌گردد
  "expiresInMinutes": 30,
  "feeMode": "CUSTOMER",               // چه کسی کارمزد را می‌دهد
  "cardId": "card_01J8XK..."           // اختیاری
}

فیلدها

{
  "success": true,
  "paymentId": "pay_01J8XK4M2Q",
  "invoiceId": "inv_01J8XK4M2Q",
  "paymentUrl": "https://steve-gate.ir/pay/inv_01J8XK4M2Q",
  "amount": 363706,          // مبلغ قابل پرداخت، نه مبلغ سفارش
  "amountRial": 3637060,
  "status": "pending",
  "expiresAt": "2026-09-22T09:41:07.000Z",
  "payment": {
    "originalAmount": 359000,     // همان مبلغی که فرستادید
    "fee": 3000,
    "baseAmount": 362000,       // originalAmount + fee
    "uniqueSuffix": 1706,       // پسوند یکتا
    "payableAmount": 363706,     // baseAmount + uniqueSuffix
    "payableAmountRial": 3637060,
    "testMode": false
  }
}

چرا مبلغ با مبلغ سفارش یکی نیست

سه عدد در پاسخ هست و رابطه‌شان همیشه برقرار است:

پسوند یکتا همان چیزی است که این فاکتور را از هر فاکتور زنده دیگری جدا می‌کند. یک ایندکس یکتا در پایگاه‌داده تضمین می‌کند در هر لحظه فقط یک فاکتور فعال هر مبلغی را داشته باشد؛ پس اگر دو درخواست همزمان بیایند، یکی پسوند دیگری را نمی‌گیرد. به همین دلیل پسوند در پاسخ برگردانده می‌شود: همان رقمی است که روی صفحه پرداخت و در پیامک بانک باید دیده شود.

خطاها

یکتاسازی درخواست

کلید یکتاسازی از شناسه سفارش خودتان بسازید — نه یک رشته تصادفی. اگر پاسخ گم شود، تایم‌اوت بخورد یا سرور شما وسط کار ری‌استارت شود، ارسال دوباره همان فاکتور اول را برمی‌گرداند، نه فاکتور دوم. پاسخ تکرارشده هدر Idempotent-Replay: true دارد.

Idempotency-Key: order_1234
# ارسال دوباره همان درخواست → همان invoiceId
Idempotent-Replay: true

کلیدها ۲۴ ساعت نگه داشته می‌شوند. اگر کلید نفرستید، درخواست کار می‌کند اما هر بار فاکتور تازه‌ای می‌سازد — که با یک دکمه «تلاش دوباره» در سمت شما به دو فاکتور زنده ختم می‌شود.

کارت‌های مقصد

کارت‌هایی که پول به آن‌ها واریز می‌شود. فقط شکل ماسک‌شده برگردانده می‌شود؛ شماره کامل هیچ‌وقت از این اندپوینت بیرون نمی‌آید.

{
  "success": true,
  "cards": [{
    "id": "card_01J8XK...",
    "masked": "6104-****-****-3456",
    "title": "کارت اصلی",
    "bankName": "بانک ملت",
    "isDefault": true
  }]
}

وضعیت حساب

دفعه اول این را صدا بزنید. اگر جواب می‌دهد، احراز هویت، دسترسی‌ها و وضعیت حساب درست است و آنچه مانده از فهرست کارهای باقی‌مانده پیداست.

{
  "success": true,
  "merchant": {
    "merchantCode": "SP-1042",
    "displayName": "فروشگاه نمونه",
    "accountStatus": "ACTIVE",
    "environment": "live"
  },
  "sms": {
    "pipelineConnected": true,      // آیا پیامکی در ۲۴ ساعت گذشته رسیده
    "verifiedAt": "2026-09-20T09:12:00.000Z",
    "webhookUrl": "https://steve-gate.ir/sms"
  },
  "wallet": { "availableBalance": 147000, "reservedBalance": 0 },
  "setup": {
    "completionPercent": 87,
    "ready": false,
    "remainingSteps": [
      { "key": "sms_test", "title": "آزمایش خط پیامک" }
    ]
  }
}

setup.remainingSteps نام کارهای باقی‌مانده را می‌دهد، نه تعدادشان. پذیرنده‌ای که به او بگویید «۳ کار مانده» تازه باید برود پیدایشان کند.

کیف پول

موجودی کیف پول. کارمزد از اینجا کسر می‌شود، پس اگر حالت کارمزد MERCHANT باشد موجودی، سقف تعداد فاکتورهایی است که می‌توانید بسازید.

{
  "wallet": {
    "balance": 147000,
    "availableBalance": 147000,   // balance - reservedBalance
    "reservedBalance": 0,       // رزرو‌شده برای فاکتورهای در جریان
    "totalDeposited": 150000,
    "totalFeesPaid": 3000,
    "currency": "IRT"
  }
}

availableBalance = balance - reservedBalance و در زمان خواندن محاسبه می‌شود. پولی که برای فاکتور زنده MERCHANT رزرو شده، دو بار خرج نمی‌شود.

شمارش تراکنش‌ها

خروجی این اندپوینت همان اعدادی است که در پنل پذیرنده می‌بینید، پس اگر عددی در پنل و در گزارش داخلی شما یکی نیست، یکی از این دو مرز بازه را جور دیگری حساب می‌کند.

{
  "range": "today",
  "from": "2026-09-21T20:30:00.000Z",   // نیمه‌شب تهران، به UTC
  "counts": {
    "total": 42, "successful": 38, "pending": 3,
    "expired": 1, "failed": 0, "manualReview": 0
  },
  "amounts": { "volume": 13842000, "fees": 114000 },
  "successRate": 90.5,
  "averagePaymentSeconds": 214,
  "lifetime": { "total": 1840, "successRate": 97.3 }
}

پیامک بانک

این اندپوینت قلب سامانه است: تنها مسیر نوشتن در موتور تطبیق. درگاه کارت را نمی‌خواند و به هیچ API بانکی وصل نیست — شاهدِ پرداخت، پیامکی است که بانک به گوشی شما می‌فرستد. پس اگر این مرحله وصل نشود، هیچ پرداختی خودکار تأیید نمی‌شود.

curl -X POST https://steve-gate.ir/sms \
  -H "X-API-Key: sk_live_" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "واریز ۳۶۳٬۷۰۶ تومان به کارت 6104337890123456 شماره پیگیری ۸۴۲۱۹۰۳۳۱",
    "sender": "BANKMELLI",
    "deviceId": "shop-phone-1"
  }'

راه‌اندازی فورواردر پیامک روی اندروید

روی گوشی اندرویدی که پیامک بانک را می‌گیرد، برنامه‌ای لازم است که پیامک را هنگام رسیدن به آدرس این سامانه بفرستد. راهنمای زیر برای برنامه SMS Forwarder است؛ هر برنامه دیگری که بتواند درخواست HTTP با هدر دلخواه بفرستد هم کار می‌کند، فقط نام منوها فرق می‌کند.

قبل از شروع، از پنل پذیرنده → کلیدهای API یک کلید بسازید که دسترسی sms:write داشته باشد، و از پنل پذیرنده → پیامک آدرس وبهوک را بردارید. در تمام مراحل زیر کلمه «Next» همان دکمه پایین صفحه در برنامه است.

1. ۰۱

   یک فیلتر تازه بسازید

   در برنامه به بخش Filters بروید و یک فیلتر جدید بسازید. هر فیلتر در این برنامه یعنی «اگر پیامکی با این شرط رسید، این کار را بکن» — پس این فیلتر نقش «قانون واریز بانکی» را بازی می‌کند.

2. ۰۲

   شرط فیلتر را روی پیامک‌های دریافتی بگذارید

   در بخش شرط فیلتر، گزینه Incoming SMS/RCS را انتخاب کنید تا فیلتر فقط روی پیامک‌های رسیده کار کند، نه پیامک‌های ارسالی خودتان.

3. ۰۳

   وبهوک را در بخش Where to forward اضافه کنید

   در بخش Where to forward روی Add بزنید و از گزینه‌های موجود URL را انتخاب کنید. اینجاست که برنامه یاد می‌گیرد پیامک را به کجا بفرستد.

4. ۰۴

   روش و آدرس را تنظیم کنید

   گزینه Request Type را روی POST بگذارید و در فیلد Enter URL این آدرس را وارد کنید:
   https://steve-gate.ir/sms

5. ۰۵

   هدر X-Api-Key را اضافه کنید

   در همان صفحه، بخش Header را باز کنید، روی Add بزنید و کلید API خودتان را بگذارید:
   نام هدر: X-Api-Key — مقدار: کلید کامل sk_live_… یا sk_test_… از پنل شما.
   بدون این هدر درخواست با کد UNAUTHENTICATED رد می‌شود.

6. ۰۶

   بدنه را روی Json بگذارید و این مقدار را کپی کنید

   بخش Body را روی Json قرار دهید و دقیقاً همین مقدار را کپی و پیست کنید. آکولادهای داخل رشته‌ها متغیرهای خود برنامه‌اند و هنگام ارسال با متن واقعی پیامک جایگزین می‌شوند — ترجمه یا فارسی‌کردن آن‌ها را انجام ندهید:

   JSONبدنه فورواردرکپی

   {
     "msg": "{msg}",
     "time": "{time}",
     "filter-name": "{filter-name}",
     "in-number": "{in-number}",
     "in-sim": "{in-sim}"
   }

7. ۰۷

   ذخیره کنید

   آیکون سیو را در بالای صفحه، سمت راست، بزنید. تا این مرحله تعریف وبهوک تمام شده است.

8. ۰۸

   تا صفحه Forwarding Conditions 2/2 جلو بروید

   صفحه‌ها را دانه‌دانه با Next جلو بروید تا به صفحه Forwarding Conditions 2/2 برسید. آنجا سیم‌کارتی را که پیامک بانکی به آن می‌رسد انتخاب کنید. اگر هر دو سیم‌کارتتان پیامک بانکی می‌گیرند، گزینه All Numbers را انتخاب کنید.

9. ۰۹

   بقیه گزینه‌ها را دست نزنید

   به هیچ چیز دیگری دست نزنید و فقط Next بزنید تا فرایند ساخت فیلتر تمام شود. در پایان برنامه یک پیام تستی به وبهوک می‌فرستد تا اتصال را بسنجد.

چرا بدنه دقیقاً همین شکل است

هر کلید این JSON به یک مقدار در سامانه نگاشت می‌شود. نام‌ها را عوض نکنید — سامانه نام‌های رایج را می‌شناسد، اما شکل زیر همان چیزی است که خود برنامه تولید می‌کند و کمترین تغییر را لازم دارد:

نام استاندارد وبهوک

تست اتصال

در پنل پذیرنده → پیامک دکمه «تست اتصال» یک پیامک نمونه با یک توکن یک‌ساعته نشان می‌دهد. آن را در برنامه فورواردر به‌جای متن عادی بفرستید؛ اگر رسید، مسیر، کلید و بدنه هر سه درست‌اند و از این پس پیامک‌های واقعی هم می‌رسند. توکن آزمایشی هیچ فاکتوری را تأیید نمی‌کند و فقط اتصال را می‌سنجد.

تطبیق چطور انجام می‌شود

آنچه ممکن است پیش بیاید

قالب ناشناخته یک خطای سرور نیست و درگاه را متوقف نمی‌کند: پیامک ذخیره می‌شود، در لاگ پنل با متن اصلی دیده می‌شود و دستی قابل بررسی است. اگر پیامک‌های واقعی‌تان تجزیه‌نشده ماندند، متن کامل را برای پشتیبانی بفرستید تا قالب بانک اضافه شود.

وقتی پیامک نمی‌رسد

ترتیب این فهرست همان ترتیبی است که یک پیامک در آن حرکت می‌کند. هر مرحله را جدا بسنجید؛ اگر یکی درست کار نکند، مرحله بعد اصلاً اتفاق نمی‌افتد و پنل هیچ خطایی نشان نمی‌دهد، چون هیچ درخواستی به سامانه نرسیده است.

وب‌هوک

وقتی پرداختی قطعی شد، رویداد امضاشده به آدرس شما می‌رود. وبهوک تأیید پرداخت نیست — پرداخت پیش از آن تأیید شده است. اگر سرور شما پایین باشد، پول برنمی‌گردد؛ فقط تحویل دوباره تلاش می‌شود.

رویدادها

هدرها

بررسی امضا

رشته‌ای که امضا می‌شود دقیقاً این است: timestamp + "." + deliveryId + "." + body. بدنه باید خام باشد — اگر آن را پارس و دوباره سریالایز کنید، فاصله‌ها و ترتیب کلیدها عوض می‌شود و بررسی شکست می‌خورد.

const crypto = require('node:crypto');

// خام، بدون تغییر: بدنه باید همان بایتی باشد که امضا شده است
function verify(rawBody, headers, secret) {
  const timestamp = headers['x-stevepay-timestamp'];
  const delivery  = headers['x-stevepay-delivery'];
  const received  = headers['x-stevepay-signature'];   // "v1="

  const expected = 'v1=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${delivery}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

$timestamp = $_SERVER['HTTP_X_STEVEPAY_TIMESTAMP'];
$delivery  = $_SERVER['HTTP_X_STEVEPAY_DELIVERY'];
$received  = $_SERVER['HTTP_X_STEVEPAY_SIGNATURE'];
$raw       = file_get_contents('php://input');   // خام، بدون json_decode

$expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $delivery . $raw, $secret);
if (!hash_equals($expected, $received)) {
    http_response_code(400);
    exit;
}

تلاش دوباره

پاسخ ۲xx یعنی تحویل موفق. هر چیز دیگر — از جمله تغییر مسیر و تایم‌اوت ده‌ثانیه‌ای — ناموفق است و دوباره تلاش می‌شود، با این فاصله‌ها:

هندلر شما باید ایدمپوتنت باشد: یک رویداد ممکن است بیش از یک بار برسد. با X-SteveGate-Delivery دریافت‌های تکراری را تشخیص دهید و بی‌صدا ۲۰۰ برگردانید — برگرداندن خطا، تلاش دوباره را طولانی‌تر می‌کند.

وضعیت هر تحویل، تعداد تلاش‌ها و متن پاسخ سرور شما در پنل پذیرنده → وب‌هوک دیده می‌شود و از همان‌جا می‌توانید تحویل ناموفق را دوباره بفرستید.

قالب خطا

هر خطا یک شکل دارد و کد آن پایدار است: کدها هرگز بازاستفاده نمی‌شوند، پس می‌توانید روی code شرط بگذارید. متن فارسی خواندنی است و ممکن است بهتر شود؛ روی متن شرط نگذارید.

{
  "success": false,
  "code": "INSUFFICIENT_WALLET_BALANCE",
  "message": "موجودی کیف پول برای ساخت فاکتور کافی نیست.",
  "requestId": "req_01J8XM...",
  "details": { "required": 3000, "available": 0 }
}

details فقط جایی می‌آید که بتوان بر اساسش کاری کرد. هیچ‌وقت متن stack trace، نام جدول یا پیام پایگاه‌داده در پاسخ نیست.

خطاهای عمومی

خطاهای فاکتور و پرداخت

خطاهای کیف پول و کارت

محدودیت‌ها

این مقادیر پیش‌فرض سامانه‌اند و مدیر می‌تواند تغییرشان دهد. محدودیت نرخ در پاسخ ۴۲۹ هدر Retry-After با عدد ثانیه می‌فرستد.

نمونه کامل

یک مسیر کامل: سفارش ساخته می‌شود، فاکتور تولید می‌شود، مشتری به صفحه پرداخت می‌رود، و وب‌هوک سفارش را تأیید می‌کند.

const BASE = 'https://steve-gate.ir/api/v1';
const key  = process.env.STEVE_GATE_KEY;

async function createPayment(order) {
  const response = await fetch(BASE + '/payments', {
    method: 'POST',
    headers: {
      'X-API-Key': key,
      'Content-Type': 'application/json',
      // کلید یکتاسازی از شناسه سفارش خودتان: ارسال دوباره فاکتور دوم نمی‌سازد
      'Idempotency-Key': 'order-' + order.id,
    },
    body: JSON.stringify({
      amount: order.total,
      description: 'سفارش ' + order.number,
      returnUrl: 'https://shop.example.com/orders/' + order.id,
      metadata: { orderId: order.id },
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    // کد خطا پایدار است؛ پیام فارسی است و ممکن است تغییر کند
    throw new Error(error.code + ': ' + error.message);
  }

  const data = await response.json();
  // همین آدرس را به مشتری بدهید
  return data.paymentUrl;
}

curl -X POST https://steve-gate.ir/api/v1/payments \
  -H "X-API-Key: sk_live_" \
  -H "Idempotency-Key: order-1234" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 359000, "description": "سفارش ۱۲۳۴" }'

محیط آزمایشی

کلید sk_test_ و کلید sk_live_ را از هم جدا نگه دارید. حساب آزمایشی، فاکتور آزمایشی می‌سازد: کیف پول دست نمی‌خورد و پیامک‌های آزمایشی هرگز فاکتور عملیاتی را تأیید نمی‌کنند.

پشتیبانی

در هر تماس، requestId پاسخ را بفرستید. آن شناسه در لاگ، در رکورد ممیزی و در تراکنش‌های مرتبط ثبت شده است، پس پیگیری بدون پرسیدن «کدام درخواست؟» انجام می‌شود.