1

خدا نام به

الفراپ Soap سرویس وب فنی مستندات

59 مهر

1,0,0 نسخه

توضیحات نگارنده تاریخ نسخه

اولیه نسخه الفراپ توسعه تیم 49 آبان 0,1

فراپال به ها url تغییر فراپال توسعه تیم 49مهر 0,1,0

2

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

به نیازی و شد خواهد داده تشخیص پذیرنده مرچنت کد روی از الفراپ توسط خودکار صورت به ها درگاه

. بود نخواهد جداگانه های پالگین و ها ماژول نوشتن و تهیه

فایل از cURLو Restful سرویس وب از استفاده برای . باشد می NuSOAPو SOAP طریق از سرویس وب از استفاده برای مستندات این

. نمایید استفاده مربوطه راهنمای

فایل بررسی هاست از میتوانید ماژول این بودن فعال بررسی جهت . باشد فعال شما هاست روی بر SOAP ماژول باید SOAP از استفاده برای

. نمایید استفاده است موجود فراپال های ماژول لیست در که

فراخوانی نمایید خود ی برنامه فایل در را NuSoap به مربوط ی کتابخانه باید هستید NuSOAP از استفاده به مایل که صورتی در همچنین

.

. گرفت خواهد انجام Https امنیتی پروتکل امن بستر در اطالعاتی تبادالت تمام و بوده SSL گواهینامه داری فراپال سایت : تذکر

کارت شماره( خریدار مالی اطالعات از کدام هیچ و گرفت خواهند انجام شاپرک مجموعه زیر های سایت در نیز بانکی های تراکنش تمامی

صورت انجام کشور های بانک صفحات در عملیات بلکه شد نخواهد استفاده فراپال سایت در ) کارت انقضای تاریخ و CVV , دوم رمز , پذیرنده

. نمایید دقت Shaparak.ir آدرس به , خود کارت اطالعات کردن وارد حین در حتما . میپذیرد

: آدرس اتصال به وبسرویس -

https://farapal.com/services/soap?wsdl

3

PaymentRequest متد :پرداخت درخواست -

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

های ویژگی دارای که باشد می PaymentRequestInput کالس از شی یک paymentRequest :متد ورودی پارامترهای

. است زیر

توضیحات نوع نام

SandBox Boolean تست های تراکنش برای

MerchantCode String درگاه کد یا مرچنت

PriceValue Double ریال به تراکنش مبلغ ReturnUrl String بانک از بازگشت آدرس

InvoiceNumber String باشد تکراری نباید( فاکتور شماره(

PaymenterName String کننده پرداخت نام PaymenterEmail String کننده پرداخت الکترونیکی پست

PaymenterMobile String کننده پرداخت موبایل شماره

PluginName String پالگین نام PaymentNote String پرداخت توضیحات CustomQuery Array متد از استفاده با بانک از برگشت در و تراکنش انجام از بعد که پارامترهایی از ای آرایه

GET شود می ارسال شما توسط شده تعیین آدرس به CustomPost Array متد از استفاده با بانک از برگشت در و تراکنش انجام از بعد که پارامترهایی از ای آرایه

POST شود می ارسال شما توسط شده تعیین آدرس به

ExtraAccountNumbers Array تراکنش از ها آن سهم درصد و کاربران های حساب شماره از ای آرایه Bank String هستید درگاه پنل در شده تنظیم بانک تغییر به مایل که صورتی در نظر مورد بانک کد

MerchantCode و PriceValue و ReturnUrl و InvoiceNumber هستند الزامی.

SandBox : که است کافی دولوپر حالت و نویسان برنامه برای استفاده مورد تست حالت فعالسازی برای SandBox صورت به را true وارد

کردن وارد به نیازی SandBox حالت از استفاده صورت در . است false با برابر پیشفرض صورت به صورت این غیر در . نمایید

. باشد نمی صحیح مرچنت

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

. نمایید استفاده http://localhost از IP بجای

4

PluginName :برای فراپال پرداخت درگاه پالگین در مثال بعنوان . دارید را الفراپ وبسرویس به اتصال قصد که است ماژولی یا پالگین نام

میزان آمار و گزارش آوردن دست به جهت فقط قسمت این . میکنیم وارد Woocommerce صورت به را PluginName مقدار , ووکامرس

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

PaymenterEmail :باید شدن وارد صورت در ولی . نشود وارد میتواند و هست اختیاری پارامتر یک که باشد می کننده پرداخت ایمیل

. شود وارد صحیح صورت به حتما

: ایمیل سنجی اعتبار PHP کد نمونه

preg_match("/([\w\-]+\@[\w\-]+\.[\w\-]+)/",$Email)

یا

<?php $Email = "john.doe@example.com;" if (!filter_var($Email, FILTER_VALIDATE_EMAIL) === false){ echo("$Email is a valid email address"); } else { echo("$Email is not a valid email address"); } ?>

PaymenterMobile :اطالع تنظیمات , خود الفراپ کاربری حساب داخل از میتواند پذیرنده که باشد می کننده پرداخت موبایل شماره

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

خواهد مواجه خطا با شود وارد ... و منزل تلفن شماره صورت به اگر و . شود وارد موبایل صورت به حتما باید شدن وارد صورت در ولی . نشود

. شد

: موبایل سنجی اعتبار PHP کد نمونه

preg_match('/^09[0-9]{9}/i', $Mobile)

مقدار زیر صورت به باید , باشند می آرایه صورت به که ExtraAccountNumbers و CustomQuery , CustomPost پارامترهای

Key^Value. : شوند دهی

( : PHP زبان) مثال

‘CustomQuery’ => array( ‘key1^value1’, ‘key2^value2’ , …… );

5

و CustomQuery آرگومان 2, ( Session) ها سشن از استفاده از جلوگیری و ها تراکنش امنیت افزایش برای الفراپ توسعه تیم

CustomPost متدهای طریق از را بانک از بازگشت از بعد استفاده برای نیاز مورد مقادیر تا است کرده تعبیه را GET یا POST و ارسال

. نمایید دریافت

خواهیم ذکر را مورد دو این از استفاده نحوه ادامه در . باشد می دهنده توسعه عهده به و اختیاری کامال GET یا POST های متد بین انتخاب

. کرد

CustomQuery :نماییم استفاده درگاه به ارسال هنگام در زیر آرایه از اگر مثال بعنوان :

‘CustomQuery’ => array( ‘key1^value1’, ‘key2^value2’ );

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

$_GET[‘key1’] == value1

$_GET[‘key2’] == value2

…...

" از استفاده ) . نمایید استفاده زیر کد از میتوانید دارید را ها متغیر از استفاده قصد ها value یا key برای که صورتی در همچنین

( ’ بجای

‘CustomQuery’ => array( "$key1^$value1", "$key2^$value2" );

CustomPost : متد از استفاده برای POST کرد خواهیم عمل صورت همان به دقیقا نیز :

‘CustomPost’=> array(‘key1^value1’, ‘key2^value2’);

$_POST[‘key1’] == value1

$_POST [‘key2’] == value2

…...

ExtraAccountNumbers :باشید می فراپال کاربری حساب چندین بین خود های درآمد از درصدی تقسیم به مایل که صورتی در

. باشید می کاربری حساب 9 حداکثر حاضر حال در متغیر این ظرفیت . نمایید استفاده متغیر این از میتوانید

FG1002 کاربری حساب به را درصد FG1001 , 21 کاربری حساب به را خود تراکنش از درصد 01 میخواهید که کنید فرض مثال بعنوان

های حساب به را خود موجودی از درصد 01 با برابر 01 + 21 + 01 شما صورت این در . دهید انتقال FG1003 حساب به را درصد 01 و

6

به را ExtraAccountNumbers آرایه باید پس . شد خواهد منتقل شما حساب به مانده باقی درصد 91 و داد خواهید انتقال دیگران

. شد خواهد واریز و محاسبه خودکار شما سهم . نمایید وارد را خود حساب شماره و سهم نباید که کنید دقت . نمایید وارد زیر صورت

‘ExtraAccountNumbers’ => array( "FG1001^10", "FG1001^20 , "FG1001^30 );

رو روبه خطا با وبسرویس طرف از صورت این غیر در باشد 011 با مساوی یا کوچکتر شده وارد های درصد مجموع بایست می همچنین

. شد خواهید

Bank :میشود تقاضا وی از پیشفرض عامل بانک یک , مینماید درگاه اخذ درخواست به اقدام الفراپ درگاه پنل طریق از پذیرنده که هنگامی

ویرایش طریق از البته) نماید می انتخاب خود درخواستی درگاه برای مرجع بانک بعنوان را بانک یک موجود های بانک بین از هم پذیرنده و

هدایت تراکنش عملیات انجام برای بانک آن به ها پالگین و ها ماژول توسط نیز کننده پرداخت (. بود خواهد بانک این تغییر به قادر هم درگاه

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

این . هستند بانک هر کدهای مقادیر این . کنید دهی مقدار پرداخت درخواست متد در Bank ورودی به میتوانید باشید خود های ماژول و ها

لیست قرارداد طرف های بانک شدن زیاد یا کم امکان به توجه با ... . و MellatBank , ParsianBank , SamanBank : از عبارتند ها کد

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

. شود خوانده پذیرنده کاربری تنظیمات از تا دهید قرار خالی

: paymentRequest متد خروجی پارامترهای

ن

توضیحات نوع نام

Status Integer وضعیت کد

Token String پرداخت توکن کد

درگاه به را Token مقدار باید که است شده انجام موفقیت با پرداخت درخواست عملیات باشد 0 با برابر Status مقدار که صورتی در

خطاها جدول در آن شرح و شود می برگردانده وضعیت کد عنوان به منفی عدد یک صورت این غیر در , نمایید ارسال فراپال پرداخت

.است شده درج

: الفراپ درگاه پرداخت آدرس

https://farapal.com/services/payment/{Token}

( :Sandbox مقدار بودن True صورت در )ال فراپ درگاه تست آدرس

https://farapal.com/services/payment_test/{Token}

7

PaymentVerify متد : پرداخت اعتبارسنجی -

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

.است زیر های ویژگی دارای که باشد می PaymentVerifyInput کالس از شی یکpaymentVerify : متد ورودی پارامترهای

توضیحات نوع نام

توضیحات نوع نام

MerchantCode String درگاه مرچنت

Token Double لایر به تراکنش مبلغ

SandBox Boolean تست های تراکنش برای

Token : این .اید داده انجام را تراکنش آن با و اید کرده دریافت پرداخت درخواست متد از استفاده با و اول مرحله در که است مقداری

بعنوان بایست می را مقدار این . است دریافت قابل و میگردد ارسال پذیرنده سایت به پرداخت از بازگشت از بعد POST متد طریق از مقدار

. دهید نمایش کننده پرداخت به بعدی های پیگیری برای تراکنش کد

SandBox :باشد نمی آن دهی مقدار به نیازی نیست تست حالت از استفاده عدم صورت در و بوده اختیاری پیشفرض صورت به مقدار این

. دهید قرار true برابر را SandBox مقدار باید و بود خواهد اجباری , بود شده انجام تست صورت به تراکنش صورتیکه در ولی

یابی دست قالب POST متد طریق از خودکار صورت به SandBox متغیر شود انجام تست صورت به تراکنش که صورتی در است ذکر قابل

POST['SandBox']_$ : است

PHP کد نمونه

array( 'SandBox' => ! empty($_POST['SandBox']), 'MerchantCode' => $MerchantCode, 'Token' => $Token )

توضیحات نوع نام PaymentVerify : متد خروجی پارامترهای

توضیحات نوع نام

Status Integer وضعیت کد

8

که شود می برگردانده منفی عدد یک صورت این غیر در است شده انجام موفقیت با پرداخت باشد 0 با برابر Status مقدار که صورتی در

.است شده درج خطاها جدول در آن شرح

این که صورتی در و کنید چک را POST['Status']_$ مقدار اول بایست می , پرداخت از بازگشت ابتدای در که کنید دقت : مهم تذکر

از خروجی Status پارامتر باید نیز بار این . نمایید paymentVerify متد طریق از تراکنش صحت بررسی به اقدام , بود 0 با برابر مقدار

. شود گرفته نظر در موفق پرداخت تا باشد 0 با برابر نیز paymentVerify متد

: PaymentRequest - PaymentVerify خطاهای جدول

PaymentRequest - PaymentVerifyجدول خطاهای متد

شرح کد وضعیت

نیست معتبر درخواست نوع -0

نیست معتبر پذیرنده کد مرچنت -2

نیست معتبر فاکتور شماره -3

نیست معتبر مبلغ مقدار -4

نیست معتبر کننده پرداخت الکترونیکی پست -9

نیست معتبر کننده پرداخت موبایل شماره -6

نیستند معتبر Query String فیلدهای -7

نیستند معتبر Post فیلدهای -8

نیست معتبر ها حساب شماره به واریز اطالعات -5

نیست فعال پذیرنده درگاه یا نیست معتبر درگاه کد -01

نیست معتبر پذیرنده درگاه به بازگشت آدرس -00

باشد نمی سایت این برای شده وارد کد مرچنت -02

نیست معتبر کننده درخواست پی آی -03

نیست معتبر عامل بانک -04

دارد وجود بانکی شبکه در مشکلی متاسفانه -09

است اشتباه پرداخت کلید مقدار -06

است نشده تایید بانک توسط و شده استعالم قبال پرداخت -07

است نشده انجام پرداخت -08

است خورده برگشت پرداخت -05

نشد تایید بانک توسط پرداخت -21

نشد واریز بانک توسط پرداخت -20

شد زده برگشت پرداخت -22

نشد دریافت بانک از پاسخی -23

برای حالتی که با حساب فراپال پرداخت انجام ) اطالعات پرداخت کننده معتبر نیست -24

(میشود

9

داده پایگاه در خطا -29

AccountBalance متد : حساب موجودی دریافت-

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

.است زیر های ویژگی دارای که باشد می AccountBalanceInput کالس از شی یک : AccountBalance متد ورودی پارامترهای

توضیحات نوع نام

توضیحات نوع نام

Username String فراپال در شما کاربری نام

WsPassword String سرویس وب رمزعبور

حساب از میتوانید را رمز نوع دو هر . است متفاوت فراپال در شما کاربری حساب عبور رمز با وبسرویس عبور رمز که کنید دقت : تذکر

. نمایید تنظیم خود کاربری

: AccountBalance متد خروجی پارامترهای

توضیحات نوع نام

توضیحات نوع نام

Status Integer وضعیت کد

AccountBalance Double کاربر حساب موجودی

accountBalance متد خطاهای .است شده انجام موفقیت با عملیات , باشد Status 0 مقدار که صورتی در

accountBalance جدول خطاهای متد

شرح کدوضعیت

نوع درخواست معتبر نیست -1

اطالعات کاربری اشتباه است -2