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


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

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

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

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

در این راهنما

پیش از شروع

برای استفاده از پرداخت تسهیمی، این موارد را در نظر داشته باشید:

  • همه ذی‌نفعان باید حساب پی‌پینگ داشته باشند. در غیر این صورت، کد خطای 116 دریافت می‌کنید.
  • برای هر پرداخت باید حداقل دو سهم تعریف شود و مبلغ هیچ سهمی نمی‌تواند صفر باشد.
  • پرداخت تسهیمی را باید با توکن حساب کاربری خودتان ایجاد کنید. اگر خودتان نیز یکی از ذی‌نفعان هستید، شناسه کاربری خود را هم در فهرست سهم‌ها قرار دهید.
  • نشانی بازگشت (returnUrl) باید با https شروع شود و دامنه آن با دامنه ثبت‌شده در پنل پی‌پینگ یکسان باشد.

سهم‌ها را به‌صورت مبلغ مشخص کنید

در پرداخت تسهیمی، سهم هر ذی‌نفع به‌صورت مبلغ ارسال می‌شود، نه درصد.

برای مثال، اگر مبلغ کل پرداخت ۱۰۰٬۰۰۰ تومان باشد و بخواهید ۱۰ درصد به ذی‌نفع اول و ۹۰ درصد به ذی‌نفع دوم اختصاص دهید، باید دو سهم به مبلغ‌های ۱۰٬۰۰۰ تومان و ۹۰٬۰۰۰ تومان ارسال کنید.

مجموع سهم‌ها باید دقیقاً با مبلغ کل پرداخت برابر باشد؛ در غیر این صورت، کد خطای 138 دریافت خواهید کرد.

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

فرایند پرداخت تسهیمی در چهار مرحله انجام می‌شود:

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

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

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

برای ایجاد پرداخت تسهیمی از متد زیر استفاده کنید:

POST /v3/pay/shared

جزئیات کامل این متد در مستندات API پی‌پینگ در دسترس است.

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

curl -X POST "https://api.payping.ir/v3/pay/shared" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "returnUrl": "https://your-site.com/payment/callback",
    "clientRefId": "order-2002",
    "items": [
      {
        "userIdentity": "09121111111",
        "amount": 90000,
        "description": "seller share"
      },
      {
        "userIdentity": "09122222222",
        "amount": 10000,
        "description": "marketplace commission"
      }
    ]
  }'
پیاده‌سازی پرداخت تسهیمی پی‌پینگ در Postman

تصویر ۱: نمونه فراخوانی متد POST /v3/pay/shared در Postman

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

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

این متد پارامتر جداگانه‌ای برای مبلغ کل ندارد؛ مبلغ پرداخت از مجموع amountهای موجود در items محاسبه می‌شود.

پاسخ ایجاد پرداخت

نمونه پاسخ:

{
  "paymentCode": "pmnt-9x3c7vqz",
  "url": "https://api.payping.ir/v3/pay/start/pmnt-9x3c7vqz",
  "amount": 100000,
  "payerWage": 0,
  "businessWage": 0,
  "gatewayAmount": 100000,
  "paypingVat": 0
}

paymentCode کد یکتای پرداخت و url نشانی هدایت پرداخت‌کننده به درگاه است. مقدار amount نیز مجموع مبلغ سهم‌های تعریف‌شده را نشان می‌دهد.

مقدارهای paymentCode و clientRefId را در پایگاه داده خود ذخیره کنید تا در مراحل بعد بتوانید تراکنش را شناسایی و تطبیق دهید.

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

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

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

ساختار این نشانی به شکل زیر است:

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

مرحله ۳: دریافت نتیجه پرداخت

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

نمونه اطلاعات دریافتی:

status=1
errorCode=
data={
  "clientRefId": "order-2002",
  "paymentCode": "pmnt-9x3c7vqz",
  "paymentRefId": 173190789,
  "amount": 100000,
  "gatewayAmount": 100000,
  "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": 173190789,
  "paymentCode": "pmnt-9x3c7vqz",
  "amount": 100000
}

نمونه پاسخ:

{
  "amount": 100000,
  "gatewayAmount": 100000,
  "paymentRefId": 173190789,
  "code": "pmnt-9x3c7vqz",
  "clientRefId": "order-2002",
  "cardNumber": "621986******4321",
  "cardHashPan": "9f86d0818...",
  "payedDate": "2026-10-14T11:05:00",
  "payerWage": 0,
  "businessWage": 0,
  "paypingVat": 0,
  "sharedPaymentItems": [
    {
      "userIdentity": "09121111111",
      "amount": 90000,
      "paymentCode": "pmnt-a1b2c3d4"
    },
    {
      "userIdentity": "09122222222",
      "amount": 10000,
      "paymentCode": "pmnt-e5f6g7h8"
    }
  ]
}

در sharedPaymentItems برای هر ذی‌نفع یک رکورد نمایش داده می‌شود که شامل موارد زیر است:

  • userIdentity: شناسه ذی‌نفع
  • amount: مبلغ سهم
  • paymentCode: کد پرداخت اختصاص‌یافته به سهم

وضعیت پاسخ Verify

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

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

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

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

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

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

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



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

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

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