برای پیاده سازی درگاه بانک پاسارگاد نیاز به اطلاعات زیر دارید که باید از سمت بانک به شما ارائه بشه :

• merchant code : کد فروشگاه یا کدی که از سمت بانک به فروشنده اختصاص می یابد و حین تراکنش فروشگاه را با آن کد می شناسند.
• terminal code : کد ترمینال یا کدی که از سمت بانک به فروشنده اختصاص می یابد و حین تراکنش از آن استفاده می شود.
• private key : یک قطعه xml که کد نشان از هویت فروشنده دارد و در طی تراکنش به وسیله آن و امضای دیجیتالی که تولید می شود احراز هویت فروشنده انجام می گردد.

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

• amount : مبلغ فاکتور که باید در زمان تراکنش و همچنین تایید یکی باشد.
• Invoice Number (iN) : شماره فاکتور که باید به ازای هر تراکنش از سمت فروشگاه شما منحصر به فرد باشد و همچنین باید توسط شما ساخته شود.
• Invoice Date (iD) : تاریخ فاکتور که باید توسط شما ساخته شود. این تاریخ می تواند با فرمت های مختلفی باشد ولی بهتر این است تا به صورت timpstamp از آن استفاده کنید و در زمان برگشت به فرمت دلخواه در بیاورید.
• refrence id (tref) : کد رهگیری که در زمان برگشت کاربر به ازای تراکنش موفق یا ناموفق توسط بانک به ما برگشت داده می شود.
• redirect Address : آدرس برگشت از درگاه بانکی به وب سایت. این آدرس در تمامی مراحل بده بستون بین وب سایت ما و بانک مورد استفاده قرار می گیرد.

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

کتابخانه های لازم برای فراخوانی در فایل ها

سه فایل برای فراخوانی در پروژه خود نیاز دارید که دو تای آن هارا باید در پروژه include کنید. هر کدام از فایل ها حاوی یه سری توابع هستند که در حین پیاده سازی درگاه از اون ها استفاده می کنیم.

• RSAProcessor.class.php : این فایل شامل یک کلاس است که متدهایی برای رمزنگاری و تولید امضا و همچنین اعتبار سنجی کلید خصوصی (private_key) می باشد.
• rsa.class.php : این فایل در فایل RSAProcessor.class.php فراخوانی شده است.
• parser.php : این فایل شامل دوتابع است که ما حین ارسال و دریافت اطلاعات از آن استفاده می کنیم. تابع post2https برای ارسال پارامتر ها و تابع makeXMLTree برای این که خروجی که بانک به ما میده در قالب xml هست و برای تبدیلش به نوع آرایه از این تابع استفاده می کنیم.(این توابع در زمان تایید صحت تراکنش مرحله اول و دوم استفاده می شود یعنی ارسال اطلاعات بدون جابجایی کاربر)

نکته : اگر در جایی دیگر از پروژه فایل های کتابخانه ها فراخوانی شده بود به وسیله توابع function_exists  و class_exists و defined از برخورد توابع ، کلاس ها ، ثوابت در کتابخانه هایی که بانک در اختیار شما قرار می دهد خودداری کنید.

شمای کلی استفاده از درگاه بانک پاسارگاد

شمای کلی درگاه متشکل از سه گام که گام اول ارسال کاربر به درگاه و بازگشت آن به همراه اطلاعات تراکنش است و گام دوم یا تایید تراکنش مرحله اول و گام سوم تایید تراکنش مرحله دوم نامیده می شود.

تایید تراکنش مرحله اول به وسیله اطلاعات تراکنش می باشد و مرحله دوم به وسیله اطلاعات و امضا . جزئیات کامل ارسال و دریافت اطلاعات را در کدهای پایین می توانید مشاهده کنید.

تراکنش در مرحله اول اتفاق می افته و سایر گام ها برای تایید صحت تراکنش است.

کاربر تنها در مرحله اول درگیر تراکنش (جا به جایی بین وب سایت و درگاه بانک و انجام تراکنش خرید) و در دو مرحله بعد درگیر نمیشه.

گام اول ) ارسال کاربر به درگاه بانک

در این گام ما باید کاربر را به همراه یه سری داده به بانک بفرستیم. در این مرحله ما نیاز داریم تا از یک فرم با متد post و به آدرس https://pep.shaparak.ir/gateway.aspx استفاده کنیم. می تونیم برای این که فرم رو از دید کاربر پنهان کنیم به وسیله جاوا اسکریپت فرم رو submit کنیم.

نکته : اگر قرار باشه یه سری اطلاعات به تنهایی به سروری ارسال بشه میتونید از CURL استفاده کنید اما اگر قصد ارسال اطلاعات بهمراه کاربر رو دارید باید از فرم استفاده کنید.

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

<?php
$merchantCode = ************;
$terminalCode =  ************;
$invoiceNumber = 1234567890;
$invoiceDate = time();
$amount = 1000;
$action = 1003;
$timeStamp = time();
$data = "#" . $merchantCode . "#" . $terminalCode . "#" . $invoiceNumber . "#" . $invoiceDate . "#" . $amount . "#" . $redirectAddress . "#" . $action . "#" . $timeStamp . "#";
$data = sha1($data, true);
$data = sign($data);
$result = base64_encode($data);
?>
<form id="pcp-form2" class="pcp-hidden" method='post' action='https://pep.shaparak.ir/gateway.aspx'>
    <input type='hidden' name='invoiceNumber' value='<?php echo $invoiceNumber ?>' >
    <input type='hidden' name='invoiceDate' value='<?php echo $invoiceDate ?>' >
    <input type='hidden' name='amount' value='<?php echo $amount ?>' >
    <input type='hidden' name='terminalCode' value='<?php echo $terminalCode ?>' >
    <input type='hidden' name='merchantCode' value='<?php echo $merchantCode ?>' >
    <input type='hidden' name='redirectAddress' value='<?php echo $redirectAddress ?>' >
    <input type='hidden' name='timeStamp' value='<?php echo $timeStamp ?>' >
    <input type='hidden' name='action' value='<?php echo $action ?>' >
    <input type='hidden' name='sign' value='<?php echo $result ?>' >
</form>
<script type='text/javascript'> var form = document.forms['pcp-form2'].submit(); </script>

• دقت داشته باشید که amount یا مبلغ فاکتور به ریال می باشد.
• پارامتر action برای تراکنش های خرید برابر 1003 می باشد. (مقدار ثابت)
• invoiceNumber باید توسط شما به صورت منحصر به فرد به ازای هر تراکنش ساخته شود.
• تابع sign که در خط ۱۱ از آن استفاده شده در فایل RSAProcessor.class.php موجود است(فراخوانی فایل الزامی است).
• متغیر $result حکم امضای پایانی شما را دارد.

پس از ارسال کاربر به درگاه و انجام تراکنش کاربر به همراه سه پارامتر tref , iN , iD بازگشت داده می شود به آدرسی که شما در لا به لای پارامتر ها دادید (redirectAddress)

به طور مثال یه چنین لینکی :‌ https://redirecAddress/?tref=636665585264150718&iN=1530941478&iD=1530945380

از اینجا به بعد کاربر همینجا می مونه و فقط ماییم که یه سری اطلاعات رو با بانک تبادل می کنیم.

گام دوم ) تایید صحت تراکنش مرحله اول

همون طور که گفتیم بعد از انجام تراکنش کاربر با سه پارامتر tref , iN , iD بر میگرده. با استفاده از پارامتر tref که در مرحله قبل بانک به ما داد ما میتونیم از نتیجه تراکنش باخبر بشیم. (موفق یا ناموفق بودن تراکنش)

<?php
$fields1 = array('invoiceUID' => $refrence_id);
$result = post2https($fields1, 'https://pep.shaparak.ir/CheckTransactionResult.aspx');
$result_array = makeXMLTree($result);

خوب پاسخ ما در متغیر $result_array ریخته شده که اگر اون رو باز کنیم چنین پارامتر هایی داره

array(1) {
  ["resultObj"]=>
  array(11) {
    ["result"]=>
    string(4) "True"
    ["action"]=>
    string(4) "1003"
    ["transactionReferenceID"]=>
    string(18) "636669021984298268"
    ["invoiceNumber"]=>
    string(10) "1531289200"
    ["invoiceDate"]=>
    string(10) "1531289200"
    ["merchantCode"]=>
    string(7) "4447000"
    ["terminalCode"]=>
    string(7) "1624847"
    ["amount"]=>
    string(4) "1000"
    ["traceNumber"]=>
    string(5) "95185"
    ["referenceNumber"]=>
    string(8) "57449637"
    ["transactionDate"]=>
    string(19) "2018/07/11 10:37:41"
  }
}

خوب پس از آرایه resultObj ایندکس result برابر پاسخ تایید تراکنش مرحله اول ماست . توصیه میشه جهت اطمینان سایر موارد نظیر شماره فاکتور رو هم چک کنید.

نکته مهم :‌ در این مرحله شماره فاکتور هم توسط پارامتر GET برگشت داده میشه. این میتونه پلی باشه براتون تا اطلاعات مرحله قبل رو که ثبت کردید بدست بیارید(برای پیاده سازی مراحل بعدی نیاز به اطلاعات خاصی نظیر قیمت دارید).

گام سوم ) تایید صحت تراکنش مرحله سوم

اگر در مرحله قبل صحت تراکنش تایید شد باید برای دومین بار تایید تراکنش رو از بانک بگیریم . برای این کار مجددا یه سری اطلاعات پست می کنیم و اطلاعات رو تحویل می گیریم.

<?php
$fields = array(
   'MerchantCode' => $merchantCode,
   'TerminalCode' => $terminalCode,
   'InvoiceNumber' => $_GET['iN'],
   'InvoiceDate' => $_GET['iD'],
   'amount' => $amount,
   'TimeStamp' => time(),
   'sign' => ''
);
$verifyData = "#" . $fields['MerchantCode'] . "#" . $fields['TerminalCode'] . "#" . $fields['InvoiceNumber'] . "#" . $fields['InvoiceDate'] . "#" . $fields['amount'] . "#" . $fields['TimeStamp'] . "#";
$verifyData = sha1($verifyData, true);
$verifyData = sign($verifyData);
$fields['sign'] = base64_encode($verifyData);
$verifyResult = post2https($fields, 'https://pep.shaparak.ir/VerifyPayment.aspx');
$verifyResult = makeXMLTree($verifyResult);

بعد از پست کردن اطلاعات به آدرس مربوطه اطلاعات بازگشت داده شده توسط بانک در متغیر $verifyResult میریزیم. خروجی که بانک به ما میده در صورت تایید صحت تراکنش به شکل زیر خواهد بود.

array(1) {
  ["actionResult"]=>
  array(2) {
    ["result"]=>
    string(4) "True"
    ["resultMessage"]=>
    string(46) "عملیات با موفقیت انجام شد"
  }
}

طبق خروجی آرایه actionResult ایندکس result برابر با مقدار نتیجه خواهد بود.

در اینجا ما می تونیم ادعا کنیم تراکنش با موفقیت انجام شده.

حین پیاده سازی درگاه نکات زیر را در نظر داشته باشید:

• اطلاعات تراکنش نظیر شماره فاکتور(invoice_number) ، تاریخ فاکتور (invoice_date) ، مبلغ (amount) ، اطلاعات مشتری ، کد رهگیری (reference_id) ، مبلغ پرداختی (amount) را در پایگاه داده ذخیره کنید.
• شماره فاکتور باید یک مقدار منحصر به فرد برای مشتری و تراکنش باشد. می توانید از اطلاعات کاربر هم در این باره (مثلا شناسه کاربری) استفاده کنید.
• در مرحله اول ما کاربر را به همراه اطلاعات میفرستیم که نیاز به فرم داریم ولی در مراحل تایید صحت تراکنش تنها نیاز به ارسال اطلاعات هست که با استفاده از CURL که در تابع post2htts موجود است این کار را می کنیم.
• کد رهگیری (refrence_id) در تمامی درگاه های بانکی کاربرد دارد و در زمان تراکنش های دستگاه پوز هم این مورد را مشاهده می فرمایید.