# سرویس درگاه پرداخت

وب سرویس درگاه پرداخت شبکه پرداخت پی به شما این اجازه رو میده که وب سایت یا پلتفرم تون رو به شبکه بانکی کشور وصل کنید و درگاه پرداخت داشته باشید. برای اتصال به درگاه و انجام تراکنش چهار مرحله وجود داره که به شرح زیر هستش :

# مرحله اول : ارسال دیتا

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

method: Post 
URL: https://pay.ir/pg/send 

# پارامترهای مجاز

نام فیلد نوع توضیحات
api String API Key دریافتی از پنل کاربری شما که بعد از تایید درخواست درگاه صادر میشه
amount Integer مبلغ تراکنش به صورت ریال و بدون رقم اعشار. بزرگتر یا مساوی 10,000 ریال
redirect String آدرس بازگشتی که باید به صورت urlencode ارسال بشه و باید با آدرس درگاه پرداخت تایید شده در شبکه پرداخت پی در یک ادرس باشه
mobile String شماره موبایل ( اختیاری ، جهت نمایش شماره کارت Mask شده روی درگاه )
factorNumber String شماره فاکتور شما ( اختیاری )
description String توضیحات تراکنش ( اختیاری ، حداکثر 255 کاراکتر )
validCardNumber String اعلام شماره کارت مجاز برای انجام تراکنش ( اختیاری، بصورت عددی (لاتین) و چسبیده بهم در 16 رقم. مثال 6219861012345678 )

# مرحله دوم : انتقال کاربر به صفحه پرداخت

در صورتی که در مرحله ارسال دیتا ، اطلاعات ارسالی شما درست باشه در پاسخ دو مقدار status و token رو دریافت میکنید و می بایست کابر رو به شیوه زیر به درگاه ریدایرکت کنید. برای اینکار باید توکن دریافت شده در مرحله قبل رو {token} دریافت کردید رو در اخر ادرس زیر قرار بدید و کاربر رو به URL ایجاد شده ریدایرکت کنید. اگر موارد رو درست انجام بدید چند ثانیه بعد صفحه پرداخت وجه رو میتونید ببینید.

method: Get
URL: https://pay.ir/pg/{token}

نکته

بعد از اینکه توکن رو اخر url قرار دادید و یه لینک ایجاد کردید حتما باید کاربر رو به آدرس ایجاد شده ریدایرکت کنید. اگر کاربر رو با متد Post به لینک ایجاد شده ارسال کنید با خطا مواجه میشید. فراموش نکنید در این مرحله کاربر حتما باید به لینک ایجاد شده ریدایرکت بشه.

# مرحله سوم : بازگشت به سایت پذیرنده

مرحله سوم زمانی انجام میشه که کاربر از درگاه پرداخت بر میگرده. در این مرحله با توجه به نتیجه و وضعیت تراکنش، کاربر رو به آدرس کالبکی که در مرحله اول با پارامتر redirect ارسال کرده بودید هدایت میکنیم. در این مرحله دیتاهای موجود رو با متد Get باید بخونید و در دیتابیس تون ذخیره کنید.

method: Get
URL:  https://Your-CallBack-URL?status={transaction_status}&token={token}

نکته

اگر مقدار پارامتر status برابر 1 بود یعنی تراکنش موفقه و باید مرحله چهارم ( وریفای تراکنش ) رو حتما انجام بدید. درصورتی که تراکنش رو وریفای نکنید بعد از ۳۰ دقیقه به حساب مبدا برگشت میخوره.

# مرحله چهارم : وریفای تراکنش

در مرحله قبل گفتیم که اگر مقدار فیلد status برابر عدد 1 بود حتما این مرحله رو انجام بدید و تراکنش رو وریفای کنید.

method: Post 
URL: https://pay.ir/pg/verify 

# پارامترهای مجاز

نام فیلد نوع توضیحات
api String API Key دریافتی از پنل کاربری شما که بعد از تایید درخواست درگاه صادر میشه
token String token دریافت شده از مرحله سوم

مهم

در صورت موفق بودن تراکنش هر بار که درخواست وریفای تراکنش ارسال کنید ما به شما وضعیت موفق رو برمیگردونیم. چون ممکنه در لحظه انجام تراکنش مشکل ارتباطی به وجود بیاد و ما پاسخ صحیح رو هر بار که درخواست کنید به شما اعلام میکنیم. برای پیشگیری از بروز تقلب، حتما باید قبل از ارائه محصول یا خدمات شماره تراکنش ( transId ) رو یکبار در دیتابیس تون جستجو کنید و اگر وجود نداشت خدمات رو ارائه کنید. طبیعتا اگه مقدار transId در دیتابیس تون باشه یعنی این تراکنش قبلا انجام شده و کاربر سعی داره حسابش رو بیشتر شارژ کنه یا بدون پرداخت پول خدمات بگیره که در این حالت می بایست خطا برگردونید و خدماتی ارائه نکنید.

# Test API

جهت تست درگاه در لوکال و بدون نیاز به API Key عملیاتی فقط کافیه بعد از پیاده سازی وب سرویس درگاه پرداخت، مقدار فیلد api رو برابر با عبارت test قرار بدید. همین !

api = test

# نمونه کد PHP

# جدول خطاها

HTTP/1.1 422 Error
{
'0':'درحال حاضر درگاه بانکی قطع شده و مشکل بزودی برطرف می شود',
'-1':'API Key ارسال نمی شود',
'-2':'Token ارسال نمی شود',
'-3':'API Key ارسال شده اشتباه است',
'-4':'امکان انجام تراکنش برای این پذیرنده وجود ندارد',
'-5':'تراکنش با خطا مواجه شده است',
'-6':'تراکنش تکراریست یا قبلا انجام شده',
'-7':'مقدار Token ارسالی اشتباه است',
'-8':'شماره تراکنش ارسالی اشتباه است',
'-9':'زمان مجاز برای انجام تراکنش تمام شده',
'-10':'مبلغ تراکنش ارسال نمی شود',
'-11':'مبلغ تراکنش باید به صورت عددی و با کاراکترهای لاتین باشد',
'-12':'مبلغ تراکنش می بایست عددی بین 10,000 و 500,000,000 ریال باشد',
'-13':'مقدار آدرس بازگشتی ارسال نمی شود',
'-14':'آدرس بازگشتی ارسالی با آدرس درگاه ثبت شده در شبکه پرداخت پی یکسان نیست',
'-15':'امکان وریفای وجود ندارد. این تراکنش پرداخت نشده است',
'-16':'یک یا چند شماره موبایل از اطلاعات پذیرندگان ارسال شده اشتباه است',
'-17':'میزان سهم ارسالی باید بصورت عددی و بین 1 تا 100 باشد',
'-18':'فرمت پذیرندگان صحیح نمی باشد',
'-19':'هر پذیرنده فقط یک سهم میتواند داشته باشد',
'-20':'مجموع سهم پذیرنده ها باید 100 درصد باشد',
'-21':'Reseller ID ارسالی اشتباه است',
'-22':'فرمت یا طول مقادیر ارسالی به درگاه اشتباه است',
'-23':'سوییچ PSP ( درگاه بانک ) قادر به پردازش درخواست نیست. لطفا لحظاتی بعد مجددا تلاش کنید',
'-24':'شماره کارت باید بصورت 16 رقمی، لاتین و چسبیده بهم باشد',
'-25':'امکان استفاده از سرویس در کشور مبدا شما وجود نداره',
'-26':'امکان انجام تراکنش برای این درگاه وجود ندارد',
'-27':'در انتظار تایید درگاه توسط شاپرک',
'-28':'امکان تسهیم تراکنش برای این درگاه وجود ندارد',
}