پرداخت ساده | درگاه پرداخت اینترنتی پی‌پینگ


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

توجه: فراخوانی وب‌سرویس‌های پی‌پینگ تنها از سمت سرور امکان‌پذیر است. توکن و سایر اطلاعات احراز هویت را هرگز در سمت کاربر (فرانت‌اند) قرار ندهید.

در این راهنما

فرآیند درگاه پرداخت اینترنتی پی‌پینگ

هر پرداخت در پی‌پینگ چهار مرحله دارد:

  1. ساخت پرداخت: مشخصات پرداخت مانند مبلغ و آدرس بازگشت (returnUrl) را با متد POST /v3/pay ارسال می‌کنید و در پاسخ، paymentCode و آدرس درگاه را دریافت می‌کنید.
  2. هدایت پرداخت‌کننده به درگاه: پرداخت‌کننده را به آدرسی که در پاسخ دریافت کرده‌اید هدایت (Redirect) می‌کنید.
  3. بازگشت از درگاه: پس از پایان پرداخت، پی‌پینگ نتیجه تراکنش را به‌صورت POST به returnUrl شما ارسال می‌کند.
  4. تایید پرداخت: با ارسال اطلاعات تراکنش به متد POST /v3/pay/verify پرداخت را نهایی می‌کنید.

مهم: برای نهایی‌شدن پرداخت، انجام هر چهار مرحله الزامی است. اگر مرحله تایید تا ۱۰ دقیقه پس از پرداخت انجام نشود، تراکنش باطل می‌شود و مبلغ به حساب پرداخت‌کننده بازمی‌گردد.

پیش‌نیازها

  • توکن: برای فراخوانی متدهای پرداخت به توکنی با دسترسی ساخت پرداخت نیاز دارید. ساخت و مدیریت توکن را در راهنمای ایجاد و ویرایش توکن ببینید.
  • گواهی SSL: نشانی بازگشت (returnUrl) باید از پروتکل https استفاده کند و با دامنه وب‌سایت ثبت‌شده در پنل یکسان باشد.

مرحله ۱: ساخت پرداخت

با متد POST /v3/pay یک دستور پرداخت ایجاد کنید. هر پرداختی که می‌سازید یک کد پرداخت یکتا (paymentCode) می‌گیرد و شما با همین کد، پرداخت‌کننده را به درگاه هدایت کنید. جزئیات کامل این متد در مستندات API پی‌پینگ آمده است.

curl -X POST "https://api.payping.ir/v3/pay" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "returnUrl": "https://your-site.com/payment/callback",
    "clientRefId": "order-1001"
  }'
پیاده‌سازی درگاه پرداخت اینترنتی پی‌پینگ در Postman

پارامترهای این متد:

  • amount (اجباری): مبلغ دستور پرداخت به تومان.
  • returnUrl (اجباری): آدرس صفحه‌ای از وب‌سایت شما که پرداخت‌کننده پس از پایان پرداخت به آن بازمی‌گردد.
  • payerIdentity (اختیاری): شماره موبایل یا ایمیل پرداخت‌کننده. اگر شماره موبایل وارد شود، کارت‌های ذخیره‌شده او در درگاه نمایش داده می‌شود.
  • payerName (اختیاری): نام پرداخت‌کننده.
  • description (اختیاری): توضیح پرداخت.
  • clientRefId (اختیاری): شناسه ارجاع پذیرنده؛ رشته‌ای یکتا از سمت شما که پس از پرداخت همراه اطلاعات تراکنش به شما بازگردانده می‌شود و برای پیدا کردن پرداخت در دیتابیس خودتان استفاده می‌شود.
  • isReversible (پیش‌فرض false): اگر true باشد، تا ۳۰ دقیقه پس از تایید پرداخت امکان درخواست بازگشت وجه وجود دارد.

در پاسخ این متد، خروجی زیر را دریافت می‌کنید:

{
  "paymentCode": "pmnt-4o2b8kqz",
  "url": "https://api.payping.ir/v3/pay/start/pmnt-4o2b8kqz",
  "amount": 10000,
  "payerWage": 0,
  "businessWage": 0,
  "gatewayAmount": 10000,
  "paypingVat": 0
}
  • paymentCode: کد یکتای پرداخت. پی‌پینگ پرداخت شما را با این کد شناسایی می‌کند؛ آن را در دیتابیس خود ذخیره کنید.
  • url: آدرس هدایت به درگاه که در مرحله بعد استفاده می‌شود.
  • amount: مبلغ دستور پرداخت.
  • businessWage: مبلغ کارمزد پذیرنده.
  • payerWage: مبلغ کارمزد پرداخت‌کننده.
  • gatewayAmount: مبلغ نهایی پرداخت؛ بسته به سناریوی کارمزد حساب شما ممکن است از مبلغ دستور پرداخت بیشتر باشد.
  • paypingVat: مبلغ مالیات بر ارزش افزوده.

مرحله ۲: هدایت پرداخت‌کننده به درگاه

پرداخت‌کننده را به مقدار url که در پاسخ مرحله قبل دریافت کرده‌اید هدایت کنید. این آدرس معادل ساختار زیر است:

https://api.payping.ir/v3/pay/start/{paymentCode}

مرحله ۳: بازگشت از درگاه

پس از پایان پرداخت، پی‌پینگ اطلاعات تراکنش را به‌صورت POST و با نوع محتوا application/x-www-form-urlencoded به returnUrl شما ارسال می‌کند. بدنه این درخواست سه فیلد دارد:

status=1
errorCode=
data={
  "clientRefId": "order-1001",
  "paymentCode": "pmnt-4o2b8kqz",
  "paymentRefId": 173190456,
  "amount": 10000,
  "gatewayAmount": 10000,
  "cardNumber": "621986******4321",
  "cardHashPan": "9f86d0818..."
}
  • status: وضعیت پرداخت؛ مقدار 1 به معنی موفق و مقدار 0 به معنی ناموفق است.
  • errorCode: در پرداخت ناموفق، کد خطای بازگشتی را نشان می‌دهد و در پرداخت موفق خالی است.
  • data: رشته JSON شامل جزئیات پرداخت:
    • clientRefId: شناسه ارجاع پذیرنده که هنگام ساخت پرداخت ارسال کرده‌اید.
    • paymentCode: کد پرداخت.
    • paymentRefId: کد رهگیری پرداخت که برای فراخوانی متد تایید در مرحله بعد لازم است و تنها در پرداخت موفق ارسال می‌شود.
    • amount و gatewayAmount: مبلغ دستور پرداخت و مبلغ نهایی پرداخت.
    • cardNumber: شماره کارت ماسک‌شده پرداخت‌کننده؛ تنها در پرداخت موفق ارسال می‌شود.
    • cardHashPan: هش شماره کارت پرداخت‌کننده؛ تنها در پرداخت موفق ارسال می‌شود.

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

مرحله ۴: تایید پرداخت

پرداخت را با متد POST /v3/pay/verify نهایی کنید. هر سه پارامتر این متد اجباری است:

{
  "paymentRefId": 173190456,
  "paymentCode": "pmnt-4o2b8kqz",
  "amount": 10000
}

در پاسخ این متد، خروجی زیر را دریافت می‌کنید:

{
  "amount": 10000,
  "gatewayAmount": 10000,
  "paymentRefId": 173190456,
  "code": "pmnt-4o2b8kqz",
  "clientRefId": "order-1001",
  "cardNumber": "621986******4321",
  "cardHashPan": "9f86d0818...",
  "payedDate": "2026-10-14T10:30:00",
  "payerWage": 0,
  "businessWage": 0,
  "paypingVat": 0
}

وضعیت پاسخ Verify

کد وضعیت HTTP 200 OK به‌معنی تأیید موفق پرداخت است.

اگر کد وضعیت HTTP 202 Accepted یا HTTP 502 Bad Gateway دریافت کردید، فرایند تأیید هنوز تکمیل نشده است. در این حالت، پرداخت جدید ایجاد نکنید و متد verify را دوباره فراخوانی کنید.

اگر کد وضعیت HTTP 409 Conflict را همراه با کد 110 در فیلد metaData.code دریافت کردید، تراکنش قبلاً تأیید شده است.

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

مهم: در صورت موفق بودن تایید، صحت مقادیر amount و clientRefId دریافتی در پاسخ verify را نیز با پایگاه داده خود مقایسه کنید و در صورت مغایرت، سفارش را نهایی نکنید.

عملیات‌های تکمیلی

حذف پرداخت

اگر پرداختی ساخته‌اید که دیگر استفاده نمی‌شود، می‌توانید آن را با متد DELETE /v3/pay حذف کنید. بدنه این درخواست فقط یک پارامتر اجباری دارد:

{
  "paymentCode": "pmnt-4o2b8kqz"
}

  • paymentCode (اجباری): کد یکتای پرداختی که هنگام ساخت پرداخت دریافت و در دیتابیس خود ذخیره کرده‌اید.

وضعیت پاسخ حذف پرداخت

کد وضعیت HTTP 204 No Content به‌معنی حذف موفق پرداخت است؛ این پاسخ بدنه ندارد.

اگر تراکنش حداقل یک پرداخت موفق در درگاه داشته باشد، امکان حذف آن وجود ندارد و کد وضعیت HTTP 400 را همراه با کد 129 در فیلد metaData.code دریافت می‌کنید.

بازگشت وجه (Reverse)

با متد POST /v3/pay/reverse می‌توانید مبلغ یک تراکنش موفق و تاییدشده را مستقیما به کارت پرداخت‌کننده بازگردانید. برای ثبت درخواست بازگشت وجه دو شرط باید برقرار باشد:

  • هنگام ساخت پرداخت، پارامتر isReversible را با مقدار true ارسال کرده باشید.
  • درخواست بازگشت وجه حداکثر تا ۳۰ دقیقه پس از تایید موفق پرداخت ثبت شود.

هر دو پارامتر این متد اجباری است:

{
  "paymentCode": "pmnt-4o2b8kqz",
  "paymentRefId": 173190456
}

  • paymentCode (اجباری): کد یکتای پرداخت.
  • paymentRefId (اجباری): کد رهگیری پرداخت که پس از پرداخت موفق، در فیلد data درخواست ارسالی به returnUrl شما قرار گرفته است.

در پاسخ این متد، خروجی زیر را دریافت می‌کنید:

{
  "amount": 10000,
  "gatewayAmount": 10000,
  "paymentRefId": 173190456,
  "code": "pmnt-4o2b8kqz",
  "clientRefId": "order-1001",
  "payerWage": 0,
  "reversedDate": "2026-10-14T10:52:00",
  "sharedPaymentItems": null
}
  • amount: مبلغ اصلی دستور پرداخت.
  • gatewayAmount: مبلغ نهایی بازگردانده‌شده به کارت پرداخت‌کننده.
  • paymentRefId و code: کد رهگیری و کد پرداخت.
  • clientRefId: شناسه ارجاع پذیرنده.
  • payerWage: مبلغ کارمزد پرداخت‌کننده.
  • reversedDate: تاریخ و ساعت بازگشت وجه (به وقت UTC).
  • sharedPaymentItems: اطلاعات تسهیم‌کننده‌ها؛ این فیلد تنها در پرداخت تسهیمی مقدار دارد.

وضعیت پاسخ Reverse

کد وضعیت HTTP 200 OK به‌معنی ثبت موفق درخواست بازگشت وجه است.

اگر تراکنش هنگام ساخت با پارامتر isReversible ساخته نشده باشد، کد وضعیت HTTP 400 را همراه با کد 134 در فیلد metaData.code دریافت می‌کنید و اگر مهلت ۳۰ دقیقه‌ای به پایان رسیده باشد، همان کد وضعیت را با کد 135 دریافت می‌کنید.

نمونه کد و SDK

بررسی کدهای خطا

برای مشاهده توضیحات کدهای خطا در مراحل مختلف پرداخت، به جدول کدهای خطا در مستندات API پی‌پینگ مراجعه کنید.



در صورت داشتن هرگونه سوال و نیاز به راهنمایی ، با پشتیبانی آنلاین سایت پی‌پینگ در ارتباط باشید.

به روز شده در: 1405/07/26

لغو
خیلی ممنون!