درگاه پرداخت اینترنتی

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

فرآیند پرداخت بر روی درگاه‌های اینترنتی 4 مرحله دارد :

ساخت پرداخت : مشخصات پرداختی که می خواهد انجام شود را مانند مبلغ پرداخت و redirectUrl که آدرسی از سایت شماست که کاربر پس از پرداخت باید به آن هدایت شود را مشخص می کنید و در قبال آن یک code دریافت می کنید
هدایت به درگاه : کاربر را بهمراه کدی که در مرحله قبلی دریافت شده است به آدرس درگاه redirect
برگشت از درگاه بانکی (تکمیل فرایند پرداخت) : پس از اینکه پرداخت توسط کاربر انجام شد، کاربر را به همراه یک refid که کد تراکنش است به آدرس redirectUrl شما ارسال می کنیم و شما باید از طرف سرور خودتان آن شماره پرداخت را تایید کنید
تایید پرداخت در این مرحله باید refid را به همراه مبلغ تراکنش به متد تایید پرداخت ارسال کرده و فرایند پرداخت را نهایی نمایید

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

ذخیره شناسه لاگ پی‌پینگ برای پشتیبانی بهتر

در هر درخواست REST که به پی‌پینگ ارسال می‌کنید در پاسخ هر کدام هدری با نام X-PayPingRequest-ID وجود دارد که در صورت ذخیره کردن این شناسه در دیتابیس خود می‌توانید در صورت وجود مشکل با دادن این شناسه به پشتیبانی فنی بهتر کمک کنید. نمونه آن در عکس زیر در POSTMAN نشان داده شده است.

1. ساخت پرداخت

برای ساخت پرداخت می‌بایست از متد POST /v2/pay استفاده کنید.
به کمک این متد می‌توانید برای هر پرداخت یک کد پرداخت ایجاد کنید. فراخوانی این متد برای شما کدی یکتا تولید می‌کند.
به زبان ساده تر، هر پرداختی که توسط شما ساخته می‌شود یک "کد پرداخت" به آن اختصاص پیدا می‌کند که شما با همان کد، کاربر را به درگاه هدایت می‌نمایید.
شما می‌بایست برای همه پرداخت‌ها کد را سمت خود ذخیره بفرمایید. ما با این کد، پرداخت شما را شناسایی می‌کنیم.

ساختار ارسال توکن: (Bearer TOKEN)
آدرس swagger
آدرس مستند

curl -X POST \
  https://api.payping.ir/v2/pay \
  -H 'Accept: application/json' \
  -H 'Authorization: bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "payerName": "نام پرداخت کننده - اختیاری", 
  "amount": 100,
  "payerIdentity": "شماره تلفن یا ایمیل پرداخت کننده - اختیاری",
  "returnUrl": "آدرس url شما که پس از پرداخت کاربر به آن فرستاده می‌شود بهمراه refid",
  "description": "توضیح پرداخت - اختیاری",
  "clientRefId": "یک رشته یکتا که پس از پرداخت بهمراه refid بصورت querystring برای شما ارسال می‌شود"
}'

در پاسخ این متد code را دریافت می‌کنید

{
"code": "xxxx"
}

این کد ، "کد پرداخت" شما در پی‌پینگ می‌باشد.


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

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

2. هدایت کاربر به درگاه

برای ورود به درگاه بانک، کدی که در مرحله قبل دریافت کرده‌اید را بصورت زیر در URL اضافه کنید و کاربر را به آدرس زیر Redirect کنید.

https://api.payping.ir/v2/pay/gotoipg/{code}

3. برگشت از درگاه بانکی (تکمیل فرایند پرداخت)

پس از پرداخت، اطلاعات پرداخت به آدرس returnUrl که در مرحله اول (ساخت پرداخت) مشخص شده است در بدنه درخواست بصورت زیر فرستاده می‌شود :‌

curl --location --request POST 'returnUrl' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code=' \
--data-urlencode 'refid=' \
--data-urlencode 'clientrefid=' \
--data-urlencode 'cardnumber=' \
--data-urlencode 'cardhashpan='

Refid مقداری است که برای تایید پرداخت (متد Verify) باید از آن استفاده کرد.

4. تایید پرداخت

شما با استفاده از متد POST /v2/pay/verify و ارسال refid پرداخت را تایید می‌کنید.
در نظر داشته باشید در صورتی‌که این متد تا 15 دقیقه پس از پرداخت فراخوانی نشود، پرداخت باطل شده و مبلغ به حساب پرداخت‌کننده باز خواهد گشت.

curl -X POST /https://api.payping.ir/v2/pay/verify \
  -H 'Accept: application/json' \
  -H 'Authorization: bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "refId": "string",
  "amount": int
}'

در پاسخ این متد ViewModel زیر را دریافت می‌کنید

{
    "amount": مبلغ,
    "cardNumber": شماره کارت ماسک شده,
    "cardHashPan": مقدار شماره کارت هش شده,
}

پاسخ کد 200 به منزله "موفقیت در تایید پرداخت" است.




چنانچه پس از فراخوانی وریفای، از سمت پی‌پینگ پاسخی دریافت نشد، وریفای را برای همین پرداخت در زمان دیگری فراخوانی نمایید.


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

* برای دریافت نمونه کد Laravel ، لطفا اینجا کلیک فرمایید.

* برای دریافت نمونه کد به زبان PHP ، لطفا اینجا کلیک فرمایید.

* برای دریافت نمونه کد به زبان C#(.Net) ، لطفا اینجا کلیک کنید.

* برای دریافت SDK، زبان موردنظر خود اینجا کلیک کنید.

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

به روز شده در: 27/07/2021