لوگوی پي اكسا

PAYEXA IPG API

راهنمای ساده اتصال درگاه برای پذيرنده

برای راه اندازی فقط این مسیر را جلو بروید: اول درخواست پرداخت بسازید، بعد callback را بگیرید، و در آخر verify بزنید تا پرداخت نهایی شود. نمونه کد هر مرحله هم پایین صفحه آماده کپی است.

REST JSON API Header Auth cURL / JS / Python / PHP Callback + Verify Flow

Quick Start

API Key را بگیرید، request را بزنید و لینک یا authority پرداخت را به کاربر نشان دهید.

Operational Rule

callback فقط خبر پرداخت است. ثبت نهایی سفارش را فقط بعد از verify انجام دهید.

Production Safety

قبل از استفاده واقعی، callback را روی HTTPS بگذارید و لاگ و timeout را فعال کنید.

AUTH HEADER

X-API-KEY

در درخواست های اصلی باید این هدر را همراه با Content-Type بفرستید.

FINALIZATION

Callback → Verify

بعد از callback، یک verify بزنید تا مطمئن شوید پرداخت واقعا موفق شده است.

آزمایشگاه تست و دسترسی به افزونه ها و ابزارها

برای استفاده از سامانه پرداخت آزمایشی، به جای نشانی pay.pexn.ir از نشانی sandbox.pexn.ir استفاده کنید و در فرآیند تست نیز به جای توکن اصلی، توکن PAYEXA را در درخواست های خود قرار دهید.

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

ورود به آزمایشگاه پی اکسا مشاهده افزونه ها و ابزارها

1) نمای کلی جریان اتصال

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

01

ایجاد سفارش در سیستم خودتان

اول سفارش را در سیستم خودتان با وضعیت pending ذخیره کنید.

02

آماده کردن هدرهای لازم

قبل از ارسال درخواست، هدرهای Content-Type و X-API-KEY را تنظیم کنید.

03

ارسال درخواست به payment/request

مبلغ و callback_url را بفرستید و authority یا اطلاعات پرداخت را بگیرید.

04

هدایت کاربر به صفحه پرداخت

بعد از دریافت authority از پاسخ مرحله 3، کاربر را به آدرس https://pay.pexn.ir/startPay?authority={authority} بفرستید.

05

دریافت callback

بعد از پرداخت، callback را دریافت کنید و سفارش را هنوز نهایی نکنید.

06

Verify قطعی در سمت سرور

بعد از callback، verify را از سمت سرور بزنید. اگر موفق بود سفارش را نهایی کنید.

2) هدرهای لازم

برای درخواست های اصلی این دو هدر را بفرستید.

Content-Type: application/json
X-API-KEY: <merchant_api_key>
Header ضروری توضیح
Content-Type بله برای ارسال JSON این مقدار باید application/json باشد.
X-API-KEY بله کلید پذيرنده برای احراز هویت. این مقدار را فقط در سمت سرور نگه دارید.
  • کلید API را در frontend یا اپ موبایل hardcode نکنید.
  • در محیط واقعی، درخواست های سروری را با timeout و logging اجرا کنید.

3) ساخت درخواست پرداخت

POST

برای شروع پرداخت، این endpoint را بزنید. بعد از گرفتن authority، کاربر را به صفحه پرداخت خودتان هدایت کنید.

https://pay.pexn.ir/v1/payment/request
فیلد نوع الزام توضیح
amount number بله مبلغ اصلی سفارش.
callback_url string بله آدرسی که بعد از پرداخت، نتیجه به آن برگردانده می شود.
meta.order_ref string پیشنهادی شناسه سفارش شما. بهتر است یکتا باشد.
  • بايد order_ref برای هر سفارش یکتا باشد.
  • كيف پول پذيرنده حتما بايد شارژ كافي داشته باشد.
  • اگر پذيرنده فعال نباشد، درخواست رد می شود.

نمونه کدها (قابل کپی)

curl -X POST "https://pay.pexn.ir/v1/payment/request" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "amount": 250000,
    "callback_url": "https://merchant.example.com/payexa/callback",
    "meta": {"order_ref": "INV-1001"}
  }'

4) هدایت کاربر به پرداخت یا ربات تلگرام

URL

بعد از اینکه در پاسخ مرحله 3 مقدار authority را گرفتید، اگر در وب کار می کنید کاربر را به صفحه پرداخت بفرستید و اگر در ربات تلگرام کار می کنید او را به deep link ربات پی اکسا هدایت کنید.

https://pay.pexn.ir/startPay?authority={authority} https://t.me/payexa_bot?start=pay_{authority}
  • مقدار {authority} باید از پاسخ موفق مرحله 3 خوانده شود.
  • این URL را فقط برای هدایت کاربر استفاده کنید. این endpoint را از سمت سرور نزنید.
  • برای شروع پرداخت داخل ربات تلگرام از deep link ربات پی اکسا با فرمت https://t.me/payexa_bot?start=pay_{authority} استفاده کنید.
https://pay.pexn.ir/startPay?authority={مقدار دريافتي در مرحله ٣}
https://t.me/payexa_bot?start=pay_{مقدار دريافتي authority در مرحله ٣}

5) وریفای تراکنش

POST

بعد از callback، این endpoint را بزنید. اگر پاسخ موفق بود، سفارش را نهایی کنید.

https://pay.pexn.ir/v1/payment/verify

200 - SUCCESS

پرداخت موفق است و می توانید سفارش را ثبت نهایی کنید.

201 - SUCCESS (ALREADY VERIFIED)

یعنی verify قبلا با موفقیت انجام شده است. این پاسخ برای فراخوانی های تکراری برمی گردد و سفارش جدیدی نباید با آن نهایی شود.

400 - INVALID_TOKEN

توکن اشتباه است یا به این سفارش مربوط نیست.

409 - NOT_SETTLED

پرداخت هنوز نهایی نشده است. کمی بعد دوباره verify بزنید.

404 - NOT_FOUND

این سفارش پیدا نشد یا برای این پذيرنده نیست.

  • verify را فقط از سمت سرور خودتان اجرا کنید.
  • نکته مقدار token در verify همان amount_unique دریافتی از مرحله /request است.
  • اگر verify برای یک سفارش بیش از یک بار صدا زده شود، فقط بار اول کد 200 می گیرید و دفعات بعدی کد 201 برمی گردد.
  • برای ثبت نهایی سفارش مشتری فقط پاسخ 200 را معیار قرار دهید.
  • اگر 409 گرفتید، چند لحظه بعد دوباره تلاش کنید.
  • قبل از success کردن سفارش، نتیجه verify را ذخیره کنید.

نمونه کدهای Verify

curl -X POST "https://pay.pexn.ir/v1/payment/verify" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -d '{
    "order_id": "ORD-AB12CD34EF56",
    "token": "249500"
  }'

6) استعلام وضعیت تراکنش

GET

اگر فقط می خواهید وضعیت فعلی سفارش را ببینید، از این endpoint استفاده کنید. برای ثبت نهایی همچنان verify مهم است.

/v1/payment/status?order_id=...
{
  "status": "PENDING",
  "paid_at": null
}
  • از status برای نمایش وضعیت به کاربر یا مانیتورینگ استفاده کنید.
  • برای نهایی کردن سفارش، status به تنهایی کافی نیست.

7) چک لیست امنیتی

قبل از استفاده واقعی این چند مورد را بررسی کنید.

Transport

callback را فقط روی HTTPS قرار دهید.

Abuse Control

برای callback محدودیت درخواست بگذارید و اگر می توانید IP یا secret را هم بررسی کنید.

Observability

callback و verify را با order_id و amount در لاگ ذخیره کنید.

  • برای verify timeout بگذارید.
  • API Key را فقط در env یا secret manager نگه دارید.
  • در callback بررسی کنید که سفارش قبلا success نشده باشد.

کدهای خطای عمومی API

این خطاها در بیشتر endpointهای API ممکن است برگردند.

کد معنی نمونه
400 Bad Request فیلد اجباری مثل card_id ارسال نشده
401 Unauthorized JWT/API Key ارسال نشده یا نامعتبر
402 Payment Required موجودی کیف پول برای کارمزد کافی نیست
403 Forbidden دسترسی مجاز نیست (مثل نقش غیرادمین)
404 Not Found موجودیت یافت نشد
409 Conflict تداخل داده (مثل تراکنش تکراری)
422 Unprocessable Entity خطای اعتبارسنجی ورودی
429 Too Many Requests عبور از Rate Limit
500 Internal Server Error خطای داخلی سرور
PAYEXA ASSISTANT

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