NexPal IPG

مستندات درگاه پرداخت

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

شروع پیاده‌سازی مشاهده چرخه پرداخت

نسخه v1

فرمت داده application/json

واحد مبلغ ریال

Base URL https://nexpal.io/api/v1

امنیت درخواست

احراز هویت

کلید اختصاصی کسب و کار یا همان API KEY پس از تایید درگاه در پنل نکس پال قابل مشاهده و یا بازتولید توسط شما است و در همه ی سرویس‌های پرداخت می‌بایست در بدنه درخواست ارسال گردد.

محل ارسال	نام دقیق	نوع	قانون
بدنه JSON	`apiKey`	`string`	الزامی، حداکثر ۶۴ کاراکتر؛ متعلق به کسب‌وکار تاییدشده
هدر	`Content-Type`	`string`	`application/json` برای ارسال صحیح بدنه JSON

کلید API فقط در سرور

درخواست‌های NexPal را از backend پذیرنده ارسال کنید. کلید را در JavaScript مرورگر، اپلیکیشن قابل مهندسی معکوس یا مخزن Git قرار ندهید و در صورت افشا آن را تعویض کنید. HTTPS برای جلوگیری از افشای بدنه درخواست ضروری است.

نمای کلی

چرخه پرداخت

۱ساخت پرداختدریافت token و payUrl

۲انتقال خریدارباز کردن payUrl

۳Callbackبازگشت مرورگر

۴استعلامدر صورت نیاز

۵Verifyتایید نهایی

۶تراکنش نهاییثبت سفارش به‌صورت idempotent

به کال بک (Call back) مرورگر اکتفا نکنید و برای دریافت نتیجه نهایی تراکنش حتما از endpoint استعلام تراکنش یا وریفای (تایید) تراکنش استفاده کنید.

مرحله اول

ساخت پرداخت

درخواست پرداخت می‌سازد و پس از تایید PSP مورد نظر، لینک پرداخت را در پاسخ بازمیگرداند.

POST /api/v1/payment/create

پارامترهای درخواست (جدول اسکرول می‌شود)

نام پارامتر	نوع داده	الزامی	توضیحات	قوانین	نمونه
`apiKey`	`string`	الزامی	کلید اختصاصی کسب‌وکار تاییدشده	حداکثر ۶۴ کاراکتر	`YOUR_API_KEY`
`idempotencyKey`	`string`	الزامی	کلید یکتای ساخت تراکنش (مانند: UUID)	حداکثر ۱۲۸ کاراکتر؛ برای retry همان payload ثابت بماند	`pay_order_78421_v1`
`amount`	`integer`	الزامی	مبلغ پرداخت به ریال	حداقل ۲۰٬۰۰۰ و حداکثر ۴،۰۰۰،۰۰۰،۰۰۰ ریال	`250000`
`terminalNumber`	`string`	اختیاری	انتخاب یک ترمینال خاص متعلق به کسب‌وکار	حداکثر ۶۴ کاراکتر؛ ترمینال باید فعال و پشتیبانی‌شده باشد	`12345678`
`callbackUrl`	`string (URL)`	الزامی	آدرس بازگشت مرورگر خریدار	آدرس کال بک می‌بایست همان دامنه یا ساب دامنه تایید شده کسب و کار باشد	`https://merchant.example/payment/callback`
`description`	`string`	اختیاری	شرح پرداخت	حداکثر ۲۵۵ کاراکتر	`خرید سفارش ۷۸۴۲۱`
`invoiceId`	`string`	الزامی	شناسه فاکتور پذیرنده	حداکثر ۶۴ کاراکتر؛ برای هر کسب‌وکار یکتا	`INV-78421`
`pans`	`string`	اختیاری	شماره کارت ها	ارسال یک یا چند شماره کارت (جدا شده با کاما)	`6037991234567890,6104991234567890`
`mobile`	`string`	اختیاری	شماره موبایل پرداخت‌کننده	شماره موبایل معتبر ۱۱ رقمی	`09123456789`
`email`	`string (email)`	اختیاری	ایمیل پرداخت‌کننده	ایمیل معتبر؛ حداکثر ۲۵۵ کاراکتر؛ به حروف کوچک تبدیل می‌شود	`buyer@example.com`
`nationalCode`	`string`	اختیاری	کد ملی پرداخت‌کننده	دقیقاً ۱۰ رقم؛ الگوی `^\d{10}$`	`0012345678`

رفتار idempotency

درصورت ارسال مجدد (ساخت مجدد) یک پرداخت با اطلاعات قبلی و همان idempotencyKey ، نکس پال، همان تراکنش قبلی ساخته شده را باز می گرداند. چنانچه idempotencyKey تکراری ارسال گردد ولی بدنه درخواست متفاوت باشد خطای code: 20 دریافت خواهید کرد. چنانچه فقط invoiceId تکراری باشد خطای code: 19 دریافت خواهید کرد.

پاسخ موفق

code100

کد موفقیت برنامه

descriptionstring

در موفقیت مقدار Success

tokenstring

توکن NexPal؛ برای transaction و verify نگه‌داری شود

invoiceIdstring

شناسه فاکتور ارسال‌شده

amountinteger

مبلغ به ریال

payUrlstring (URL)

آدرس انتقال خریدار

خطاهای این سرویس

HTTP Status	Code	English Message	توضیحات
400	13	`Amount is invalid`	مبلغ integer نیست یا بیرون بازه مجاز است.
400	14	`InvoiceId is invalid`	شناسه فاکتور خالی یا طول آن بیش از ۶۴ است.
400	15	`Mobile number is invalid`	موبایل از اعتبارسنجی DTO یا PSP عبور نکرده است.
400	16	`Pans are invalid`	شماره کارت ها نامعتبر است یا PSP آن را نپذیرفته است.
400	17	`NationalCode is invalid`	کد ملی ۱۰ رقمی نیست یا PSP آن را نپذیرفته است.
400	18	`Callback URL is invalid`	URL یا دامنه Callback با قواعد کسب‌وکار سازگار نیست.
409	19	`InvoiceId is duplicated`	invoiceId قبلاً برای این کسب‌وکار استفاده شده است.
409	20	`Idempotency key is duplicated`	کلید idempotency با درخواست قبلی سازگار نیست.
400 / 404	21	`Terminal not found`	terminalNumber نامعتبر است یا ترمینال فعال و پشتیبانی‌شده پیدا نشد.
401 / 403	30	`Api key is invalid`	کلید معتبر/یکتا برای کسب‌وکار تاییدشده نیست یا وب‌سایت کسب‌وکار قابل استفاده نیست.
400 / 429 / 500 / 502 / 503	33	`Other error`	سایر خطاهای validation، محدودیت درخواست، PSP یا خطای داخلی که عمومی‌سازی شده‌اند.

شکل پاسخ خطا

{
  "code": 19,
  "description": "InvoiceId is duplicated"
}

نمونه درخواست

پاسخ مورد انتظار · HTTP 201

{
  "code": 100,
  "description": "Success",
  "token": "AbC12+xYz890",
  "invoiceId": "INV-78421",
  "amount": 250000,
  "payUrl": "https://psp.example/pay/example-token"
}

مرحله دوم

انتقال به صفحه پرداخت

آدرس انتقال در فیلد payUrl پاسخ ساخت پرداخت قرار دارد. سرور پذیرنده باید token را کنار سفارش و invoiceId ذخیره کند و فقط داده لازم برای انتقال را به frontend خود بدهد.

۱

در backend پذیرنده

ساخت پرداخت با apiKey، ذخیره token و برگرداندن payUrl به کلاینت.

۲

در frontend پذیرنده

انتقال مرورگر به مقدار معتبر payUrl بدون دریافت یا مشاهده API key.

نمونه انتقال در مرورگر پذیرنده

// payUrl از backend خود پذیرنده دریافت شده است.
window.location.assign(payment.payUrl);

ارجاع خریدار فقط با دامنه مجاز ثبت شده

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

بازگشت خریدار

Callback

PSP ابتدا endpoint داخلی NexPal را فراخوانی می‌کند. NexPal تراکنش را از PSP استعلام می‌گیرد و سپس مرورگر را با HTTP 302 و یک درخواست GET به callbackUrl ثبت‌شده پذیرنده هدایت می‌کند. پارامترها در query string هستند؛

پارامترهای Callback پذیرنده

نام پارامتر	نوع	حضور	توضیحات
`paymentRequestId`	`string`	همیشه	شناسه داخلی درخواست پرداخت NexPal؛ ورودی transaction/verify نیست.
`invoiceId`	`string`	همیشه	شناسه فاکتور ارسال‌شده هنگام ساخت.
`amount`	`string integer`	همیشه	مبلغ به ریال، بدون اعشار.
`status`	`"true" \| "false"`	همیشه	نتیجه مقدماتی استعلام؛ اثبات نهایی پرداخت نیست.
`referenceNumber`	`string`	شرطی	در صورت موجود بودن RRN/reference از رویداد یا استعلام PSP.
`trackId`	`string`	شرطی	فقط وقتی استعلام تازه PSP آن را برگرداند.

نمونه URL بازگشت

https://merchant.example/payment/callback?paymentRequestId=854312901234567890&invoiceId=INV-78421&amount=250000&status=true&referenceNumber=141014267140&trackId=18

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

status=true می‌تواند وضعیت PAID پیش از Verify را نشان دهد. token در Callback ارسال نمی‌شود؛ آن را از پاسخ ساخت پرداخت، در سرور و مرتبط با invoiceId نگه دارید. سپس با همان token استعلام و Verify را انجام دهید و فقط پاسخ code: 100 سرویس Verify را مبنای تحویل کالا یا خدمت قرار دهید.

مرحله اختیاری

دریافت اطلاعات تراکنش

وضعیت تراکنش متعلق به همان کسب‌وکار را با token بررسی می‌کند. پیش از Verify معمولاً پاسخ 12 / pending دریافت می‌شود؛ این endpoint جای Verify را نمی‌گیرد.

POST /api/v1/payment/transaction

پارامترهای درخواست

نام پارامتر	نوع داده	الزامی	قوانین	نمونه
`apiKey`	`string`	الزامی	حداکثر ۶۴ کاراکتر	`YOUR_API_KEY`
`token`	`string`	الزامی	حداکثر ۶۴ کاراکتر؛ توکن پاسخ create	`AbC12+xYz890`

حالت‌های پاسخ

HTTP	Code	Message	معنی	فیلدهای کامل
201	12	`pending`	هنوز پاسخ نهایی قابل ارائه نیست.	خیر؛ فقط code و message
201	100	`verified`	پرداخت با وضعیت VERIFIED یافت شد.	بله
201	200	`CONFIRMED`	پرداخت به وضعیت CONFIRMED رسیده است.	بله

invoicestring

invoiceId ثبت‌شده

referenceNumberstring

شماره مرجع/RRN

maskedCardNumberstring

شماره کارت ماسک‌شده

hashedCardNumberstring

هش شماره کارت

requestDatestring

تاریخ ثبت‌شده از PSP

amountinteger

مبلغ به ریال

descriptionstring

شرح یا رشته خالی

وضعیت‌های داخلی چرخه

این enumها مستقیماً در response این endpoint برگردانده نمی‌شوند، اما رفتار چرخه را تعیین می‌کنند.

CREATEDPENDINGPAIDVERIFYINGVERIFIEDCONFIRMEDREVERSEDREFUNDEDFAILEDEXPIRED

خطاهای این سرویس

HTTP Status	Code	English Message	توضیحات
404	14	`not found`	token برای apiKey تاییدشده پیدا نشد یا PSP تراکنش را نیافت.
403	33	`other error`	بدنه نامعتبر، provider پشتیبانی‌نشده، پاسخ ناسازگار یا خطای عمومی استعلام.

پاسخ در انتظار

{
  "code": 12,
  "message": "pending"
}

نمونه درخواست

پاسخ مورد انتظار · HTTP 201

{
  "code": 100,
  "message": "verified",
  "invoice": "INV-78421",
  "referenceNumber": "141014267140",
  "maskedCardNumber": "610433******2142",
  "hashedCardNumber": "0f6c...d921",
  "requestDate": "2026-08-07 10:24:32.000000000",
  "amount": 250000,
  "description": "خرید سفارش ۷۸۴۲۱"
}

مرحله نهایی پذیرنده

تایید تراکنش

NexPal ابتدا تراکنش را از PSP استعلام می‌کند، invoice و amount را تطبیق می‌دهد، سپس وضعیت را به پذیرنده اعلام می‌کند.

POST /api/v1/payment/verify

پارامترهای درخواست

نام پارامتر	نوع داده	الزامی	قوانین	نمونه
`apiKey`	`string`	الزامی	حداکثر ۶۴ کاراکتر	`YOUR_API_KEY`
`token`	`string`	الزامی	حداکثر ۶۴ کاراکتر؛ توکن پاسخ create	`AbC12+xYz890`

تایید نهایی تراکنش حداکثر تا ۱۵ دقیقه

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

Verify موفق فقط یک بار

نتیجه تایید فقط یکبار بازگردانده می شود، پس از اولین Verify موفق، یا وقتی Verify دیگری در حال اجراست، درخواست بعدی با HTTP 403، code: 13 و پیام دقیق already verified رد می‌شود. وضعیت‌های CONFIRMED، REVERSED و REFUNDED مجددا وریفای نخواهند شد

فیلدهای پاسخ موفق

code100

موفقیت برنامه

messageverified

پیام دقیق موفقیت

invoicestring

فاکتور تطبیق‌داده‌شده

referenceNumberstring

شماره مرجع PSP

maskedCardNumberstring

کارت ماسک‌شده

hashedCardNumberstring

هش کارت از PSP

requestDatestring

تاریخ PSP

amountinteger

مبلغ تطبیق‌داده‌شده، ریال

descriptionstring

شرح یا رشته خالی

خطاهای این سرویس

HTTP Status	Code	English Message	توضیحات
403	13	`already verified`	تایید قبلاً انجام شده، در حال انجام است یا وضعیت قابل تکرار نیست.
404	14	`not found`	token برای apiKey پیدا نشد یا PSP تراکنش را پیدا نکرد.
403	33	`other error`	بدنه نامعتبر، وضعیت غیرقابل تایید، عدم تطابق invoice/amount یا خطای عمومی PSP.

تلاش مجدد پس از تایید

{
  "code": 13,
  "message": "already verified"
}

نمونه درخواست

پاسخ مورد انتظار · HTTP 201

{
  "code": 100,
  "message": "verified",
  "invoice": "INV-78421",
  "referenceNumber": "141014267140",
  "maskedCardNumber": "610433******2142",
  "hashedCardNumber": "0f6c...d921",
  "requestDate": "2026-08-07 10:24:32.000000000",
  "amount": 250000,
  "description": "خرید سفارش ۷۸۴۲۱"
}

عملیات حساس

برگشت از خرید (Reverse)

فقط تراکنش هایی که در وضعیت تایید شده VERIFIED قراردارند قابلیت بازگشت از خرید (برگشت کامل وجه به خریدار) را خواهند داشت.

POST /api/v1/payment/reverese

پنجره Reverse در پیاده‌سازی فعلی

درخواست فقط وقتی پذیرفته می‌شود که وضعیت جاری پرداخت VERIFIED باشد و ۲۰ دقیقه از پرداخت نگذشته باشد.

پارامترهای درخواست

نام پارامتر	نوع داده	الزامی	قوانین	نمونه
`apiKey`	`string`	الزامی	حداکثر ۶۴ کاراکتر	`YOUR_API_KEY`
`token`	`string`	الزامی	حداکثر ۶۴ کاراکتر؛ توکن پاسخ create	`AbC12+xYz890`

خطاهای این سرویس

HTTP Status	Code	English Message	توضیحات
403	30	`out of allowed time`	بیش از ۲۰ دقیقه از رویداد VERIFIED گذشته است.
502	33	`other error`	token/apiKey پیدا نشد، بدنه نامعتبر، PSP یا provider در دسترس/پشتیبانی‌شده نیست.
400	43	`bad request, transaction is not verified`	پرداخت یا آخرین رویداد در وضعیت VERIFIED نیست؛ شامل تکرار پس از Reverse یا بعد از CONFIRMED.

نمونه درخواست

پاسخ مورد انتظار · HTTP 201

{
  "code": 100,
  "message": "reversed",
  "invoiceId": "INV-78421",
  "amount": 250000
}

مرجع کامل

کدهای پاسخ و خطا

codeهای برنامه در scope هر سرویس معنا دارند و با HTTP status یکسان نیستند؛ برای مثال 13 در create یعنی مبلغ نامعتبر و در verify یعنی قبلاً تایید شده است. جدول زیر هر ۲۵ ترکیب عمومی سرویس/کد پیاده‌سازی فعلی را نگه می‌دارد.

HTTP Status	Code	English Message	توضیحات	سرویس
201	100	`Success`	پرداخت ساخته شد.	Create
400	13	`Amount is invalid`	مبلغ نامعتبر است.	Create
400	14	`InvoiceId is invalid`	شناسه فاکتور نامعتبر است.	Create
400	15	`Mobile number is invalid`	شماره موبایل نامعتبر است.	Create
400	16	`Pans are invalid`	pans نامعتبر است.	Create
400	17	`NationalCode is invalid`	کد ملی نامعتبر است.	Create
400	18	`Callback URL is invalid`	آدرس Callback نامعتبر است.	Create
409	19	`InvoiceId is duplicated`	شناسه فاکتور تکراری است.	Create
409	20	`Idempotency key is duplicated`	کلید idempotency تکراری/ناسازگار است.	Create
400 / 404	21	`Terminal not found`	ترمینال معتبر پیدا نشد.	Create
401 / 403	30	`Api key is invalid`	کلید یا زمینه کسب‌وکار معتبر نیست.	Create
400 / 429 / 500 / 502 / 503	33	`Other error`	خطای عمومی‌سازی‌شده create.	Create
201	12	`pending`	تراکنش هنوز پاسخ نهایی ندارد.	Transaction
404	14	`not found`	تراکنش پیدا نشد.	Transaction
403	33	`other error`	خطای عمومی استعلام.	Transaction
201	100	`verified`	اطلاعات تراکنش VERIFIED برگشت داده شد.	Transaction
201	200	`CONFIRMED`	اطلاعات تراکنش CONFIRMED برگشت داده شد.	Transaction
403	13	`already verified`	Verify قبلاً انجام شده یا در حال انجام است.	Verify
404	14	`not found`	تراکنش پیدا نشد.	Verify
403	33	`other error`	خطای عمومی تایید.	Verify
201	100	`verified`	تراکنش با موفقیت Verify شد.	Verify
403	30	`out of allowed time`	پنجره ۲۰ دقیقه‌ای Reverse پایان یافته است.	Reverse
502	33	`other error`	خطای عمومی برگشت.	Reverse
400	43	`bad request, transaction is not verified`	وضعیت برای Reverse مجاز نیست.	Reverse
201	100	`reversed`	Reverse با موفقیت ثبت شد.	Reverse