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 را از سمت سرور بزنید. اگر موفق بود سفارش را نهایی کنید.
3) ساخت درخواست پرداخت
POST
برای شروع پرداخت، این endpoint را بزنید. بعد از گرفتن authority، کاربر را به صفحه پرداخت خودتان هدایت کنید.
https://pay.pexn.ir/v1/payment/request
فیلد
نوع
الزام
توضیح
amount
number
بله
مبلغ اصلی سفارش.
callback_url
string
بله
آدرسی که بعد از پرداخت، نتیجه به آن برگردانده می شود.
meta.order_ref
string
پیشنهادی
شناسه سفارش شما. بهتر است یکتا باشد.
نمونه بدنه درخواست (JSON)
کپی
{
"amount": 250000,
"callback_url": "https://merchant.example.com/payexa/callback",
"meta": {
"order_ref": "INV-1001"
}
}
نمونه پاسخ موفق (201)
کپی
{
"amount_unique": 249111.0,
"authority": "A4DA518F581F49DBF292A77FBE0C9493B",
"card_number": "9999999999999999",
"expire_at": "Fri, 13 Mar 2026 17:50:15 GMT",
"order_id": "ORD-B1066D98EEF31355"
}
بايد order_ref برای هر سفارش یکتا باشد.
كيف پول پذيرنده حتما بايد شارژ كافي داشته باشد.
اگر پذيرنده فعال نباشد، درخواست رد می شود.
نمونه کدها (قابل کپی)
cURL
JavaScript
Python
PHP
کپی
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"}
}'
کپی
const response = await fetch("https://pay.pexn.ir/v1/payment/request", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": process.env.PAYEXA_API_KEY,
},
body: JSON.stringify({
amount: 250000,
callback_url: "https://merchant.example.com/payexa/callback",
meta: { order_ref: "INV-1001" },
}),
});
const data = await response.json();
console.log(data);
کپی
import requests
resp = requests.post(
"https://pay.pexn.ir/v1/payment/request",
headers={
"Content-Type": "application/json",
"X-API-KEY": "YOUR_API_KEY",
},
json={
"amount": 250000,
"callback_url": "https://merchant.example.com/payexa/callback",
"meta": {"order_ref": "INV-1001"},
},
timeout=10,
)
print(resp.status_code)
print(resp.json())
کپی
$payload = [
"amount" => 250000,
"callback_url" => "https://merchant.example.com/payexa/callback",
"meta" => ["order_ref" => "INV-1001"],
];
$ch = curl_init("https://pay.pexn.ir/v1/payment/request");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: YOUR_API_KEY",
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
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
نمونه بدنه وریفای
کپی
{
"order_id": "ORD-AB12CD34EF56",
"token": "249500"
}
نمونه پاسخ موفق (200)
کپی
{
"status": "SUCCESS",
"merchant_verified": true,
"merchant_verified_at": "2026-02-27T11:47:30"
}
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
JavaScript
Python
PHP
کپی
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"
}'
کپی
const response = await fetch("https://pay.pexn.ir/v1/payment/verify", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": process.env.PAYEXA_API_KEY,
},
body: JSON.stringify({
order_id: "ORD-AB12CD34EF56",
token: "249500",
}),
});
const data = await response.json();
console.log(data);
کپی
import requests
resp = requests.post(
"https://pay.pexn.ir/v1/payment/verify",
headers={
"Content-Type": "application/json",
"X-API-KEY": "YOUR_API_KEY",
},
json={
"order_id": "ORD-AB12CD34EF56",
"token": "249500",
},
timeout=10,
)
print(resp.status_code)
print(resp.json())
کپی
$payload = [
"order_id" => "ORD-AB12CD34EF56",
"token" => "249500",
];
$ch = curl_init("https://pay.pexn.ir/v1/payment/verify");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: YOUR_API_KEY",
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
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
خطای داخلی سرور