به نام خداوند جان و خرد

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

مرحله اول

ایجاد تراکنش

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

نام	نوع	شرایط	توضیحات
amount	INT or String	اجباری*	مبلغ تراکنش است . باید حتما عدد باشد و بین 500 تا صد میلیون باشد. واحد ارسالی به تومان است.
callBack	URL	اجباری*	آدرس صفحه برگشت از بانک است و باید به صورت url در فرمت صحیح باشد. با https شروع شود.
resNum	INT or String	اجباری*	شماره تراکنش است که شما ایجاد میکنید و باید به صورت یکتا باشد، شما نمیتوانید برای دو تراکنش یک شماره یکتا ارسال کنید. این شماره در برگشت دوباره به شما پاس داده می شود. طول عبارت نباید از 200 کارکتر بیشتر باشد. صرفا لازم نیست عدد باشد. شما هر عبارت یکتایی را می توانید برای مقدار این متغیر در نظر بگیرید.
resNumOption	INT or String	اختیاری	عبارتی اختیاری است که شما در هنگام ایجاد تراکنش به وب سرویس آرتی پی می توانید بفرستید و آرتی در انتهای تراکنش دوباره مقدار را برای شما پاس می دهد. طول عبارت نباید از 200 کارکتر بیشتر باشد. صرفا لازم نیست عدد باشد.
sign	hash	اجباری*	امضای تراکنش است که با کلید خصوصی شما باید ایجاد شود. توضیحات نحوه ایجاد امضا در ادامه ذکر شده است.
phoneNumber	String	اختیاری	شماره تلفن پرداخت کننده است و در فرمت 09…. ارسال می گردد.

توجه

نحوه ایجاد امضا در این مرحله به این صورت است که عبارتی شامل مبلغ تراکنش و آدرس بازگشت و شماره تراکنش ایجاد می کنید و بعد با متد sha 256 و کلید اختصاصی که در اختیار شما قرار گرفته شد خروجی هش را ایجاد می کنید. سه متغیر ذکر شده در عبارت اولیه با # باید از هم جدا شده باشند.

str = amount#callBack#resNum

**** متغیر های ارسالی باید با هدر authorization که مقدار آن باید برابر با api اختصاصی شما باشد ارسال شود.

آدرس وب سرویس ایجاد تراکنش در آرتی پی : https://api.rtpay.ir/ipgNext

مرحله دوم

بازگشت از وب سرویس و ارسال کاربر به بانک

بعد از ارسال پاسخ در یافتی به صورت JSON در متد POST خواهد بود. دو پارمتر که در هر حال برگشت داده می شود متغیر های code و mes هستند. در صورتی که تراکنش به درستی ایجاد شده باشد متغیر code با عدد 200 برگشت داده میشود و پاسخ ارسالی علاوه بر دو متغیر دیفالت که گفته شد دارای یک آرایه به نام data نیر هست که اطلاعات تراکنش را شامل می شود. ای اطلاعات شامل موارد زیر است.

نام	توضیحات
Amount	مبلغ تراکنش که شما فرستادید. به تومان است.
finalAmount	مبلغی است که بعد از پرداخت کاربر و کسر کارمزد به حساب شما در آرتی پی اضافه می شود.
resNum	شماره یکتای تراکنش است که در مرحله قبل ایجاد کرده اید
resNumOption	مقداری است که در مرحله قبل پاس داده اید.
tokenUrl	آدرس پرداخت است که شما باید کاربر را به این آدرس هدایت کنید.

کاربر را به آدرس دریافتی در متغیر tokenUrl در آرایه data هدایت کنید.

 

مرحله سوم

بازگشت از بانک

با توجه با رفتار کاربر در بانک ( پرداخت یا عدم پرداخت )، پارامترهایی با متد GET به آدرسی که در مرحله اول به عنوان آدرس برگشتی تعیین کرده اید ارسال می شود. ای متغیرها عبارتند از:

نام	توضیحات
Status	وضعیت تراکنش است که تنها در صورتی که برابر با OK باشد بدین معناست که تراکنش انجام شده است. سایر مقدار ها به معنای عدم پرداخت کاربر است.
resNum	شماره یکتای تراکنش است که در مرحله اول ایجاد کرده اید
resNumOption	مقداری است که در مرحله اول پاس داده اید.
Amount	مبلغ تراکنش به تومان است.

 

 

مرحله چهارم

تایید تراکنش

پس از دریافت اطلاعات با متد GET در مرحله قبل و در صورتی که Status برابر OK باشد، اطلاعات زیر جهت تایید نهایی تراکنش باید به وب سرویس آرتی پی ارسال شود. ( تا این مرحله هیچ پرداختی تایید نیست)

نام	نوع	توضیحات
amount	INT or String	مبلغ تراکنش به تومان است.
resNum	INT or String	شماره یکتای تراکنش است که در مرحله اول ایجاد کرده اید
sing	hash	امضای تراکنش است که با کلید خصوصی شما باید ایجاد شود. توضیحات نحوه ایجاد امضا در ادامه ذکر شده است.

توجه

نحوه ایجاد امضا در این مرحله به این صورت است که عبارتی شامل مبلغ تراکنش و آدرس بازگشت و شماره تراکنش ایجاد می کنید و بعد با متد sha 256 و کلید اختصاصی که در اختیار شما قرار گرفته شد خروجی هش را ایجاد می کنید. سه متغیر ذکر شده در عبارت اولیه با # باید از هم جدا شده باشند.

str = amount#resNum

** متغیر های ارسالی باید با هدر authorization که مقدار آن باید برابر با api اختصاصی شما باشد ارسال شود.

ارسال تمامی پارامترها الزامی است.

آدرس وب سرویس : https://api.rtpay.ir/verify

 

مرحله پنجم

دریافت نتیجه

پس از ارسال پارامترهای ذکر شده در مرحله قبل، نتیجه درخواست به صورت JSON و در قالب متد پست (POST) به سمت شما ارسال می شود. فارغ از هر نتیجه ای، پاسخ تحت هر شرایطی شامل دو متغیر است. متغیر code و متغیر mes . اگر مقدار متغیر code برابر با 200 باشد، به معنی صحت تراکنش است. در صورتی که تراکنش بدرستی تایید شده باشد متغیر code با مقدار 200 برگشت داده می شود و همچنین پاسخ شامل متغیر دیگری نیز به نام data است. data از نوع آرایه است و اطلاعات تراکنش را شامل می شود. اطلاعات موجود در آرایه data به شرح زیر است:

نام	توضیحات
Amount	مبلغ تراکنش به تومان است.
finalAmount	مبلغی است که به پذیرنده بعد از کسر کارمزد شاپرک و آرتی پی تعلق میگیرد. واحد تومان است.
resNum	شماره یکتای تراکنش است که در مرحله اول ایجاد کرده اید
resNumOption	مقداری است که در مرحله اول به آرتی پی ارسال کرده اید.
trackNum	شماره پیگیری تراکنش در بانک است.
cardPay	کارت پرداخت کننده به صورت ماسک شده است.
date	تاریخ تایید تراکنش در سمت بانک است که به صورت حروف است.
time	تاریخ ایجاد تراکنش در آرتی پی است و به صورت عدد است. (در قالب تابع time)

 

لینک مستندات اتصال به درگاه آرتی پی در گیت هاب