از اولین درخواست،
تا پرداخت تأییدشده.

۱. کلید اختصاصی بساز

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

۲. یک پرداخت بساز

برای هر سفارش یک Idempotency-Key ثابت بفرست. تکرار همان درخواست همان پرداخت را برمی‌گرداند؛ تغییر داده با همان کلید خطای 409 دارد.

POST /api/v1/payments
Authorization: Bearer sp_test_YOUR_KEY
Content-Type: application/json
Idempotency-Key: order-1042

{
  "order_id": "1042",
  "title": "Order 1042",
  "amount": 1250000,
  "currency": "IRR",
  "return_url": "https://your-shop.example/orders/1042"
}

پاسخ شامل id، status، amount، expires_at و checkout_url است. خریدار را به checkout_url هدایت کن. پیش از پرداخت، مبلغ سفارش را روی سرور خودت محاسبه کن.

۳. نتیجه را مستقل تأیید کن

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

GET /api/v1/payments/PAYMENT_ID
Authorization: Bearer sp_test_YOUR_KEY

POST /api/v1/payments/PAYMENT_ID/verify
Authorization: Bearer sp_test_YOUR_KEY
Content-Type: application/json

{}

verify پاسخ ذخیره‌شده ارائه‌دهنده آزمایشی را بررسی می‌کند. تا قبل از نتیجه قطعی، verification_pending برمی‌گردد. سفارش پرداخت‌شده دوباره اعتبار نمی‌گیرد.

استرداد، ادامه پرداخت و گزارش

POST /api/v1/payments/PAYMENT_ID/refund
Authorization: Bearer sp_test_YOUR_KEY
Idempotency-Key: refund-order-1042-1
Content-Type: application/json

{ "amount": 100000 }

POST /api/v1/payments/PAYMENT_ID/recover
Authorization: Bearer sp_test_YOUR_KEY
Content-Type: application/json

{}

GET /api/v1/payments?page=1
Authorization: Bearer sp_test_YOUR_KEY

استرداد از موجودی آزاد آزمایشی کم می‌شود. recover برای پرداخت ناموفق، لغوشده یا منقضی، لینک و اعتبار تازه می‌سازد و لینک قبلی را باطل می‌کند. گزارش صفحه‌بندی‌شده در هر صفحه تا ۵۰ پرداخت دارد.

رویداد و وب‌هوک

رویداد نتیجه پرداخت همراه با تراکنش مالی در outbox ثبت می‌شود. worker آن را امضا می‌کند و گیرنده محلی آزمایشی با event_id از ثبت دوباره جلوگیری می‌کند. از پنل می‌توانی خطای گیرنده و بازپخش را آزمایش کنی. ارسال به URL فروشگاه هنوز فعال نیست؛ برای اتصال فعلی از استعلام API استفاده کن.

{
  "id": "evt_…",
  "type": "payment.paid",
  "payment_id": "pay_…",
  "mode": "sandbox",
  "created_at": "…"
}

خطاهای قابل مدیریت