همه چیز درباره پرداخت‌یاری + نحوه انجام تست و نکات فنی و سورس کٌد

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

مقدمه

با گسترش کسب و کارهای آنلاین و افزایش تراکنش های مالی بر روی بستر وب و موبایل، بانک ها و موسسات مالی برای رقابت در این بازار بزرگ و پرسود نیاز به ارائه خدمات جدید به مشتری دارند. مخصوصاً بعد از همه گیری کرونا، پرداخت از طریق اینترنت رشد صعودی عجیبی پیدا کرد که این امر باعث شد تا هم مردم و هم سیاست گذاران، نگاه ویژه ای به ابزارهای پرداخت آنلاین که نیاز به حضور مدیای فیزیکی مثل کارت ندارد، داشته باشند. حالا با این حجم بالا از تراکنش های مالی غیرحضوری، نیاز به بازیگران جدید و تازه نفس در صنعت پرداخت داریم تا ایده های جدید و روش های خلاق را در این زمینه بکار گیرند. در این چند سال گذشته، علاوه بر درگاه های پرداخت اینترنتی یا IPG که بانک ها به کسب و کارها ارائه می‌دادند، درگاه های پرداخت واسط، با سخت گیری کمتر، به صاحبان کسب و کارهای اینترنتی، ابزاری برای دریافت پول به صورت آنلاین از مشتری، ارائه می‌دادند. از 2-3 سال گذشته، طرحی در بانک مرکزی به تصویب رسید تا شرکت های ارائه دهنده درگاه واسط و شرکت های دیگری که علاقه به فعالیت در زمینه پرداخت آنلاین دارند، بتوانند با عقد قرارداد با یک شرکت ارائه دهنده خدمات پرداخت (PSP) به مشتریان یا کاربران خود خدمات پرداخت آنلاین را در قالب سرویس های ارزش افزوده، ارائه کنند.

طبق قوانین بانک مرکزی، شرکت های دارای مجوز پرداخت‌یاری، می‌توانند در بستر وب و موبایل، جایی که به حضور فیزیکی کارت نیازی نیست، خدمات پرداخت ارائه کنند که در نهایت این تراکنش ها از طریق سوئیچ شرکت های PSP پردازش شده و به سمت سوئیچ شاپرک هدایت می‌شوند.

خب بعد از این مقدمه، اگر می‌خواهید در زمینه پرداخت آنلاین کار کنید، شما حتماً نیاز دارید تا مجوز پرداخت‌یاری را از شاپرک دریافت کنید. در این مقاله من می‌خواهم هر آنچه که برای دریافت این مجوز، از عقد قرارداد با شرکت PSP تا پاس کردن آزمون های شاپرک و حتی کدنویسی وب سرویس پرداخت‌یاری شاپرک برای پیاده سازی سرویس های پرداخت‌یاری را مستند کنم. من خودم مدت زیادی درگیر مسائل پرداخت‌یاری در یکی از شرکت ها بودم و به موضوعات، مشکلات و موارد مربوط به تست ها و سرویس های شاپرک تسلط دارم. امیدوارم این نوشته به عنوان مرجعی مناسب برای افرادی که قصد دریافت مجوز پرداخت‌یاری از شرکت شاپرک دارند، مفید باشد.

تعریف واژگان

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

• شرکت PSP : شرکت ارائه دهنده خدمات پرداخت مانند ایران کیش، به‌پرداخت ملت، سامان کیش و ... که درگاه پرداخت الکترونیکی یا دستگاه پوز به پذیرندگان ارائه می‌دهند و مستقیما به سوییچ شاپرک متصل هستند.
• تراکنش : هر پرداختی که توسط یک کاربر از طریق درگاه پرداخت اینترنتی انجام می‌گیرد.
• شناسه پرداخت‌یار یا Payment Facilitator Id : که به اختصار در متن PFID نوشته میشه، شناسه ای است که از طرف شرکت شاپرک به شرکت های پرداخت‌یار به ازای هر PSP اختصاص داده میشه.
• مفهوم TrackingCode : شماره ای که به هر درخواست پرداخت‌یار در PSP اختصاص پیدا میکنه. با این شماره می‌توانید درخواست خود را در وب سرویس PSP پیگیری کنید.
• کٌد ترمینال یا Terminal Id : کدی که به ازی هر ترمینال پذیرندگی (همان IPG) به Merchant شما از طرف PSP اختصاص می یابد.
• مفهوم AcceptorCode : رشته ای 15 کاراکتری که از سمت شاپرک به هر یک از پذیرندگان پشتیبانی شده پرداخت‌یار نسبت داده می‌شود.
• درگاه پرداخت الکترونیک یا IPG : درگاهی که از طریق آن کاربر می‌تواند پرداخت خود را انجام دهد. این درگاه توسط PSP به شما به ازای هر پذیرنده ارائه خواهد شد.
• پذیرنده پشتیبانی شده یا Merchant : پذیرنده ای که اطلاعاتش توسط PSP تایید و در وب سرویس شاپرک ثبت خواهد شد.
• مشتری یا Customer : معمولا این مفهوم برای اطلاعات شخصی یا شرکتی Merchant در وب سرویس های PSP و شاپرک استفاده می‌شود.
• فروشگاه یا Shop : برای اشاره به فروشگاه فیزیکی یا اینترنتی و اطلاعات مربوط به کسب و کار Merchant در وب سرویس های PSP و شاپرک از این مفهوم استفاده می‌شود.

خلاصه روال پرداخت‌یاری

ابتدا با یک شرکت PSP قرارداد همکاری در زمینه پرداخت‌یاری امضاء می‌کنید. هر کدام از شرکت‌های PSP مواردی در قرارداد ذکر می‌کنند که به دقت باید مطالعه کنید. روال به این شکل است که شما باید پذیرنده های خود را ابتدا با وب سرویس شرکت PSP در دیتابیس آن شرکت ثبت کنید و یک TrackingCode از PSP دریافت کنید. بعد از دریافت این کٌد، اطلاعات تکمیلی پذیرنده خود را به همراه کد Merchant که از PSP دریافت کردید از طریق وب سرویس به شاپرک ارسال می‌کنید. اگر اطلاعات پذیرنده از نظر شاپرک مشکلی نداشته باشد، معمولاً پس از چند ساعت تا یک روز نتیجه آن را دریافت می‌کنید و این بار یک کد (AcceptorCode) از شاپرک دریافت می‌کنید. شما از این پس با استفاده از کد شاپرک می‌توانید اطلاعات پذیرنده خود را به روز رسانی کنید و تراکنش های ایجاد شده را با وی تسویه کنید. روال هم به این شکل است که پس از ثبت پذیرنده در PSP و دریافت کد مرچنت، یک درگاه پرداخت آنلاین یا IPG به نام پذیرنده شما سمت PSP ساخته می‌شود. هر تراکنشی که از طریق این درگاه انجام گیرد، از طریق سوئیچ PSP به شاپرک ارسال می‌شود. این درگاه واسط به ظاهر مستقیم است، اما شما به عنوان شرکت پرداخت‌یار، واسط انجام این تراکنش خواهید بود. در انتها شما باید از طریق سرویس FTP شاپرک، تراکنش هایی که از طریق درگاه پذیرنده شما انجام می‌شود، در قالب فایل JSON، روی سرور FTPS شاپرک به صورت روزانه قرار دهید تا شرکت شاپرک با پذیرنده شما به صورت مستقیم تسویه کند.

عقد قرارداد با شرکت PSP

اولین قدم برای پرداخت‌یاری، انتخاب یکی از شرکت های PSP به عنوان سوئیچ واسط پرداخت و عقد قراراداد پرداخت یاری با آن هاست. شما می تونید لیست شرکت های مجاز PSP را در وب سایت رسمی شاپرک به این نشانی مشاهده کنید. البته شما می‌تونید با بیش از یک PSP برای انجام روال پرداخت‌یاری قرارداد ببندید. فقط این نکته را بخاطر بسپارید که به ازای هر PSP باید روال تست پرداخت‌یاری با آن را یک بار از ابتدا تا انتها انجام داده و تست شاپرک را پاس کنید. اول به وب سایت اون شرکت مراجعه کنید و مستندات مربوط به پرداخت‌یاری را بررسی کنید. شرکت PSP معمولاً وب سرویس هایی برای تعریف Merchant و دریافت اطلاعات پایه مربوط به پرداخت‌یاری در اختیار شما قرار می‌دهد. شدیداً توصیه میکنم اولین کارتون بررسی این مستندات باشه. تجربه شخصیم با یکی از PSPها در استفاده از وب سرویس های پرداخت‌یاری و استفاده از سوئیچ اون ها تجربه خوبی نبوده. مواردی که باید به اون ها توجه کنید، نوع وب سرویس ها، مستندات با جزئیات و نحوه پاسخگویی و پشتیبانی از شما در موارد مختلف سرویس های پرداخت‌یاریست. شرکتی را انتخاب کنید که وب سرویس پایدار با تکنولوژی به روز و مستندات کامل ارائه می‌دهد.

تعریف پذیرنده در PSP و پاس کردن تست های PSP

اولین قدم، انجام تست سمت PSP است. هر PSP قبل از اینکه شما را تایید کند، نیاز دارد که شما چند پذیرنده را با اطلاعات واقعی با استفاده از وب سرویسی که به شما ارائه می‌دهد، تعریف کرده و تایید تکمیل بودن اطلاعات پذیرنده و ایجاد IPG را به شما بدهد. برای تعریف پذیرنده، به اطلاعات کاملی از هر پذیرنده نیاز دارید که در مستندات PSP ذکر شده است. علاوه بر آن، قرارداد و فرم های مربوط به پذیرنده که PSP در اختیار شما قرار می‌دهد باید توسط پذیرنده شما پُر، مهر و امضاء شود، و در قالب فایل PDF به درخواست شما Attach شده و ارسال گردد. معمولاً متدی برای استعلام نتیجه درخواست شما در وب سرویس PSP وجود دارد، که با صدا زدن آن می‌توانید از نتیجه درخواست خود اطلاع پیدا کنید. زمانی تایید تست PSP را خواهید داشت که کد مرچنت مربوط به IPG پذیرنده را دریافت و یک تراکنش تستی روی آن بزنید.

روال پرداخت‌یاری شاپرک

پس از پاس کردن تست های شرکت PSP و دریافت کد Merchant پذیرنده ها، نوبت به ثبت اطلاعات آن ها در وب سرویس شاپرک و پاس کردن تست های شاپرک است. اول، به این صفحه از سایت شاپرک برید و آخرین نسخه مستندات مربوط به پرداخت‌یاری را دریافت کنید. مستنداتی که نیاز دارید :

• پروتکل وب سرویس های ثبت و پیگیری درخواست های متقاضیان در سامانه جامع پذیرندگان توسط شرکت های پرداخت یار و پیوست آن
• الزامات فنی فعالیت پرداخت یاران در شبکه پرداخت الکترونیکی کشور (فایل تسویه)
• ضوابط و مقررات قرارداد میان پرداخت یار و پذیرندگان پشتیبانی شده
• ضوابط و مقررات قرارداد میان شرکت ارائه دهنده خدمات پرداخت و پرداخت یار
• فرآیند آغاز به فعالیت پرداخت یاران در شبکه پرداخت الکترونیکی کشور
• الزامات، ضوابط و فرآیند اجرایی فعالیت پرداخت یاران و پذیرندگان پشتیبانی شده در نظام پرداخت کشور

که البته در این صفحه می تونید خلاصه ای از تمام موارد گفته شده در این مستندات + کدهای مورد نیاز ارتباط با وب سرویس های شاپرک، یکجا داشته باشید :)
هرچند پیشنهاد می‌کنم حتماً حداقل یکبار مستندات رسمی شرکت شاپرک درباره پرداخت‌یاری را مطالعه کنید.

وب سرویس شاپرک، 2 متد کلی برای ثبت و پیگیری درخواست پذیرندگان شما ارائه میده. یک متد برای ثبت هر گونه درخواست، و یک متد برای استعلام نتیجه درخواست ها. از اینجای نوشته به بعد، در مورد موارد فنی روال پرداخت‌یاری صحبت خواهیم کرد. اگر فنی نیستید، ادامه نوشته را به یکی از همکاران فنی و برنامه نویس خود بسپارید! سرویس های ارائه شده به صورت RESTful و فراخوانی متدها به صورت POST با Content-Type JSON در BODY درخواست انجام می‌شود. به ابزاری مثل Postman حتما احتیاج خواهید داشت تا تست End-to-End شاپرک را پاس کنید. تجربه من نشان داده که چندین بار باید این درخواست ها را ساخته و ارسال کنید تا نحوه کار با وب سرویس دستتان بیاید! پس از اطمینان از کارکرد درست درخواست هایتان، سراغ نوشتن کٌدها و خودکار سازی این عملیات بروید.

در ابتدای کار، شرکت شاپرک دسترسی شما را به سرور تستی پرداخت‌یاری ایجاد و طی نامه ای رسمی به شرکت شما اعلام خواهد کرد. این دسترسی ها شامل اطلاعات VPN ،نام کاربری و رمز عبور مربوط به وب سرویس، PFID و اطلاعات مربوط به سرور تسویه FTPS خواهد بود. لطفاً و حتماً در حفظ این اطلاعات کوشا باشید! چون این اطلاعات به شکل کاغذی بدست شما خواهد رسید!

موارد امنیتی وب سرویس شاپرک

علاوه بر IP Restriction و ارتباط از طریق تانل امن VPN بین پرداخت‌یار و شاپرک، برای فراخوانی سرویس ها، به ازای هر PFID، یک نام کاربری و کلمه عبور اختصاص می‌یابد که با روش احراز هویت Basic Authentication باید به هدر درخواست های ارسالی، اضافه شود. به این شکل که رشته ای از username:password با فرمت Base64 رمزگذاری شده و در هدر Authorization: Basic هر درخواست ارسال می‌شود.

سرویس اول : ثبت درخواست Merchant

درخواست هایی که به وب سرویس شاپرک خواهید فرستاد یکی از انواع زیر است. نکته ای که باید مد نظر داشته باشید این است که در هر درخواست، تمامی فیلدها به شکل کامل و در قالب فرمت JSON باید ارسال شوند، در غیر این صورت با پیام خطای شاپرک مواجه خواهید شد. همچنین اطلاعاتی که شاپرک از سیستم های مرجع بر اساس کدملی افراد یا شرکت ها استعلام می‌کند به جای اطلاعاتی که فرستاده اید مورد استفاده قرار خواهد گرفت، پس سعی کنید تا جای ممکن فقط فیلدهای Required را در درخواست های خود ارسال کنید(در مستندات مشخص شده که کدام فیلدها اجباری و کدام فیلدها اختیاری است). این موضوع در تمام درخواست های شاپرک به عنوان یک اصل وجود دارد، یعنی اگر کدملی فرد را بفرستید، نام و نام خانوادگی او از طریق سیستم ثبت احوال استعلام و جایگزین دیتای ارسالی شما در این فیلدها خواهد شد!

• ثبت مشتری و فروشگاه : برای تفکیک مفاهیم مشتری و فروشگاه به بخش تعریف واژگان بروید. با این متد شما می‌توانید درخواست ثبت اطلاعات شخصی، شرکتی و اطلاعات مربوط به فروشگاه یا کسب و کار Merchant در شاپرک ایجاد کنید.
• اصلاح اطلاعات : هرگونه تغییر در فیلدهای اطلاعاتی Merchant توسط این نوع درخواست به اطلاع شاپرک می‌رسانید. فقط نکته ای که باید توجه کنید این است که تمامی فیلدها، حتی فیلدهایی که تغییر نکرده اند را باید به همان شکل قبلی ارسال کنید تا این نوع درخواست با موفقیت ثبت گردد.
• تغییر آدرس فروشگاه پذیرندگی : در این نوع درخواست فقط فیلدهای آدرس و اطلاعات تماس مشتری یا فروشگاه قابلیت به روز رسانی دارند و بقیه فیلدها باید به شکل قبل و دست نخورده به شاپرک ارسال شوند.
• فعال سازی مجدد ترمینال : در صورتی که به هر دلیلی، Merchant شما غیرفعال شده باشد، با این نوع درخواست می‌توانید دوباره ترمینال مربوط به او را فعال کنید.

نکته ای که در این درخواست ها باید توجه کنید این است که یکسری اطلاعات پایه برای هر درخواست نیاز دارید، مثل کد صنف پذیرنده یا شهر و استان. این اطلاعات پایه در مستندات تکمیلی شرکت های PSP و شاپرک نوشته شده، مثلا به ازای هر پذیرنده، شما باید کد صنف و کد تکمیلی صنف مربوط به کسب و کار آن را از این مستند و این مستند استخراج کنید، که البته به شکل غیرحرفه ای، این دیتا در فایل PDF قرار دارند (امیدوارم یک جوانمرد فایل JSON آن ها را در گیت هاب قرار دهد!).

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

سرویس دوم : پیگیری وضعیت درخواست ها

متد دوم این وب سرویس برای تعیین وضعیت درخواست هایی که قبلاً ثبت کرده اید، مورد استفاه قرار می‌گیرد. همانطور که قبلا اشاره کردم روال به این شکل است که شما درخواست را ثبت می‌کنید و پس از گذشت زمان (بین چندساعت تا روز) درخواست شما بررسی و نتیجه با صدا زدن این متد مشخص خواهد شد. پرداخت ‌یار در فرمت زیر از وب سرویس شاپرک می‌پرسد که وضعیت درخواست هایش به چه شکل است:

{    &quotrequestDate&quot: null,

    &quotrequestTypes&quot : null, &quotstatuses&quot: null,

    &quottrackingNumbers&quot: [ &quot154986587429854&quot, &quot154986587429854&quot, &quot564654654654487&quot ],    &quottrackingNumberPsps&quot: null }

بهتره برای توضیح فیلدها به این فایل در سورس کد مراجعه کنید. شرایط صدا زدن این متد : حداقل یکی از 3 فیلد trackingNumberPsp ، trackingNumbers یا requestDate باید دارای مقدار باشند، حداکثر بازه زمانی درخواست ها یک روز، حداکثر امکان جستجوی 100 کد در یک درخواست. در صورت عدم رعایت این شرایط دیتایی بازگردانده نخواهد شد. فرمت پاسخ این سرویس به شکل زیر است:

[        &quottrackingNumber&quot: //value,

        &quottrackingNumberPsp&quot: //value,

        &quotstatus&quot: //value,

        &quotrequestDate&quot : //value,

        &quotdescription&quot : //value,

        &quotrequestType&quot ://value,

        &quotmerchant&quot : //value,

        &quotrelatedMerchants&quot://value,

        &quotrequestRejectionReasons&quot : //value,

        &quotrequestDetails&quot://value    }

]

بهتره برای توضیحات بیشتر به سورس مراجعه کنید.

نکات مربوط به تسویه

پس از مشخص شدن وضعیت درخواست و موفق بودن آن، وقت تسویه تراکنش های ایجاد شده روی IPG مربوط به پذیرنده بر روی سرور شرکت شاپرک است. هنگام انجام تست End-to-End باید VPN که شرکت شاپرک برای شما ساخته متصل باشید، از طریق نام کاربری و کلمه عبور و آدرس IP که به شما داده شده به سرور FTPS شاپرک متصل شده و فایل های تسویه ای که در قالب JSON ساخته اید را به همراه فایل امضاء مربوطه (که توضیح آن را خواهم داد) بر روی سرور قرار دهید.

نام فایل باید در این فرمت باشد : <Payment Facilitator Alias>_YYYYMMDD_CC.json که اول PFID شما بلافاصله کاراکتر آندرلاین و سپس تاریخ تسویه به شمسی و CC شماره سیکل پردازش فایل در شاپرک است. مثلا فایل PFID_13990625_01.json شامل اطلاعات تسویه با پذیرندگان در تاریخ 25 شهریور 1399 و در سیکل 01 است. اگر یک فایل تسویه فرستادیم و دوباره خواستیم در همان روز فایل تسویه بذاریم، باید شماره CC را یکی اضافه کنیم. نام فایل امضاء به این صورت است : <PFID>_YYYYMMDD_CC.json.sign که قوانینش با نام فایل تسویه یکیست. نام گذاری فایل نتیجه توسط شاپرک هم به صورت : REP_<PFID>_YYYYMMDD_CC.json که شبیه به موارد بالاست. فایل های ارسالی برای تسویه حتما باید به همراه فایل امضاء ارسال شوند، پرداخت یار باید جفت کلید خصوصی و عمومی خود را طبق الگوریتم RSA 2048 تولید کند. برای تولید این فایل از نرم افزارهای GnuPG و OpenSSL می توان استفاده کرد. نماینده پرداخت یار باید فایل کلید عمومی را از طریق ایمیل با ضمیمه یک نامه رسمی برای شاپرک ارسال کند. ابتدا باید آدرس ایمیل رسمی شرکت توسط نامه به شاپرک اعلام شده باشد. یک IP ثابت توسط پرداخت یار برای برقرار ارتباط با تانل امن و توسط VPN به شاپرک اعلام می‌شود.
جفت کلید عمومی و خصوصی پرداخت یار باید هر 6ماه یکبار و یا شک به افشای کلید خصوصی، دوباره تولید و کلید عمومی به اطلاع شاپرک برسد. روال به این صورت است که یک هفته قبل از پایان اعتبار کلید عمومی (کل اعتبار نزد شاپرک 180 روز) جفت کلید خصوصی و عمومی جدید را ایجاد و از طریق مسیر IN\KEY_EXCHANGE در FTPS قرار گیرد. این کلید عمومی باید توسط کلید جاری و کلید جدید در دو فایل جداگانه امضاء شده باشد. نتیجه پذیرش یا عدم پذیرش کلیدها در مسیر OUT\EXCHANGE روی FTPS قرار خواهد گرفت.

فرمت فایل پاسخ کلید عمومی به این شکل است و فیلد اول مقدار 0 یا 1 می‌گیرد که 0 به معنی عدم پذیرش کلید و 1 به معنی پذیرش کلید عمومی پرداخت یار است.

Reason Code : 1, Description : Public Key Accepted

شاپرک جهت اطمینان از عدم فراموشی پرداخت یار در خصوص تولید کلید عمومی یک هفته قبل از منقضی شدن آن فایل اخطاری در مسیر OUT\KEY_EXCHANGE قرار می‌دهد که حاوی تاریخ پایان اعتبار آن است. فایل های پاسخ تسویه شاپرک دارای یک فایل امضاء هم در کنارشان هستند که این فایل با کلید عمومی شاپرک که در اختیار پرداختیار قرار گرفته، تایید اعتبار خواهند شد.

فرمت فایل تسویه و توضیح فیلدهای آن

{

&quotsettlementDataDetails&quot: [

{

&quotacceptorCode&quot: &quotSHP_PF_111111B1&quot,

&quotiin&quot: 111111111,

&quotpaymentFacilitatorIban&quot: &quotIR....&quot,

&quotsettlementAmount&quot: 1000000,

&quotwageAmount&quot: 0,

&quotsettlementIban&quot: &quotIR.....&quot

},

{

&quotacceptorCode&quot: &quotSHP_PF_111111B1&quot,

&quotiin&quot: 111111111,

&quotpaymentFacilitatorIban&quot: &quotIR....&quot,

&quotsettlementAmount&quot: 500000,

&quotwageAmount&quot: 0,

&quotsettlementIban&quot: &quotIR....&quot

},

{

&quotacceptorCode&quot: &quotSHP_PF_111111B1&quot,

&quotiin&quot: 111111111,

&quotpaymentFacilitatorIban&quot: &quotIR....&quot,

&quotsettlementAmount&quot: 1000000,

&quotwageAmount&quot: 7000,

&quotsettlementIban&quot: &quotIR....&quot

},

{

&quotacceptorCode&quot: &quotSHP_PF_111111B1&quot,

&quotiin&quot: 111111111,

&quotpaymentFacilitatorIban&quot: &quotIR....&quot,

&quotsettlementAmount&quot: 600000,

&quotwageAmount&quot: 7000,

&quotsettlementIban&quot: &quotIR....&quot

} ]

}

توضیح فیلدها :

فیلد iin

• کد سوئیچ PSP که توسط PSP به شما اعلام می‌شود.
• Int32, MinLen : 6, MaxLen : 9 , Required : Yes

فیلد acceptorCode:

• کد پذیرنده ای که در وب سرویس شاپرک ثبت شده
• string, Minlen : 15, MaxLen: 15, Required : Yes

فیلد paymentFacilitatorIban:

• شماره شبای پرداخت یار
• string, MinLen: 26, MaxLen:26 , Required: Yes

فیلد settlementAmount:

• مبلغ تسویه با پذیرنده
• Int64, MinLen:1 , MaxLen:15, Required : Yes

فیلد wageAmount:

• مبلغ کارمزد تراکنش
• Int64, MinLen:1, MaxLen:15, Required: yes

فیلد settlementIban:

• شماره شبای طرف تسویه
• Int64, MinLen:1, MaxLen:15, Required: yes

نکته : آدرس سرور، نام کاربری و کلمه عبور مربوط به سرویس FTPS به صورت حضوری توسط شاپرک تحویل داده می‌شود. توجه کنید که به ازای هر PSP یک اکانت FTPS باید از شاپرک تحویل گرفته شود، مثلا یک اکانت برای تسویه تراکنش های انجام شده با درگاه ایران کیش و یک اکانت برای تسویه تراکنش های انجام شده با درگاه سامان کیش.

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

[

{

&quoterrorMessage&quot: &quotReferencedDataNotFound&quot,

&quotrecordIndex&quot: 1,

&quoterrorType&quot: 8,

&quotfieldName&quot: &quotsettlementIban&quot,

&quotfieldValue&quot: &quotIR000000000000000000000000&quot

},

{

&quoterrorMessage&quot: &quotNotEnoughResources&quot,

&quotrecordIndex&quot: 2,

&quoterrorType&quot: 15,

&quotfieldName&quot: &quotaccountBalance&quot,

&quotfieldValue&quot: 6244314

},

{

&quoterrorMessage&quot: &quotReferencedDataNotFound&quot,

&quotrecordIndex&quot: 3,

&quoterrorType&quot: 8,

&quotfieldName&quot: &quotsettlementIban&quot,

&quotfieldValue&quot: &quotIR000000000000000000000001&quot

},

{

&quoterrorMessage&quot: &quotOutOfBoundsData&quot,

&quotrecordIndex&quot: 3,

&quoterrorType&quot: 14,

&quotfieldName&quot: &quotwageAmount&quot,

&quotfieldValue&quot: 997278

}

]

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

نکات :

• اگر فایل تسویه توسط پرداخت یار تا 8 صبح در مسیر FTPS بدون خطا قرار بگیرد، شاپرک در سیکل پایای ساعت 15:45 تسویه را انجام می‌دهد.
• اگر اختلالی در سرویس های مربوط به تسویه وجود داشته باشد، انجام تسویه همه فایل های قرار گرفته در مسیر FTPS در اولین سیکل پایا پس از رفع مشکل، صورت خواهد گرفت.
• در تعطیلات رسمی عملیات تسویه انجام نمی‌شود و در اولین روز بعد از تعطیلات انجام خواهد شد.

کتابخانه Shaparak.PaymentFacilitation

همانطور که گفتم، من خودم مدت زیادی درگیر مسائل مربوط به پرداخت یاری بودم، چندین بار به مشکل خوردم و تجربیات زیادی کسب کردم. شرکت شاپرک مستندات کامل و با جزئیاتی جهت پیاده سازی روال پرداخت یاری ارائه داده، اما تمام مدل ها و فیلدهای اطلاعاتی مورد نیاز در فایل های PDF قرار داده که باعث شده هر شرکتی که نیاز به پیاده سازی این روال داره مجبور بشه یک بار لایبرری به زبان و تکنولوژی مورد نیازش برای ارتباط با وب سرویس های شاپرک ایجاد کنه. من برای سهولت استفاده از این وب سرویس ها، یک لایبرری به زبان C# به صورت اوپن سورس در گیت هاب منتشر کرده ام که استفاده از آن برای هرکسی آزاده. حتی اگر پروژه شما به زبان و تکنولوژی دیگریست، می توانید از فیلدها و کامنت های موجود در این سورس کد بهره بگیرید، و لطفاً لایبرری مربوطه را به هر زبانی به صورت آزاد در گیت هاب منتشر کنید تا از دوباره کاری بقیه همکارانتان با هدف مشترک جلوگیری کنید! من سعی کردم تمام مدل های پروژه را بر اساس مستند رسمی شاپرک مستند کنم تا شما با مشاهده کدها نیازی به مراجعه به مستند PDF هنگام کدنویسی نداشته باشید.

یک پیشنهاد : اگر پروژه شما بر بستر .NET CORE یا .NET framework است می توانید در Nuget Package Manager سرچ کنید Shaparak.PaymentFacilitation و پکیج های مربوط به پلت فرم مورد نظر خود را نصب کنید، در توسعه سورس کد این کتابخانه در گیت هاب همکاری کنید تا کدهای این لایبرری همیشه با مستندات شرکت شاپرک همگام و به روز باشد.

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

(این نوشته به روز رسانی خواهد شد!)

پایان.