مستندات فني اتصال به درگاه پرداخت اينترنتي شپا
با استفاده از این سرویس قادر خواهید بود وب سایت و پلتفرم تون رو به شبکه پرداخت شپا وصل کنید. برای این منظور می بایست سه مرحله رو انجام بدید
در این مستند چگونگی استفاده از سرویس پرداخت اینترنتی بر بستر وب و بر پایه پروتکل امن https توضیح داده شده است.سرویس ها در قالب آدرس های اینترنتی در اختیار پذیرندگان قرار می گیرد تا در سایت خود استفاده نمایند.
مرحله اول : ارسال دیتا
پذیرنده اطلاعات مورد نیاز را از خریدار دریافت نموده و به آدرس زیر ارسال می نماید .متد مورد استفاده جهت فراخوانی آدرس دریافت توکن به صورت post می باشد.
method:post
URL: https://merchant.shepa.com/api/v1/token
پارامترهای ارسالی به شرح زیر می باشد :
| نام | نوع | اجباری | شرح |
| api | string | بله | كد 36 كاراكتري درگاه پرداخت |
| amount | Integer | بله | مبلغ تراکنش (با واحد ریال) |
| callback | string | بله | آدرس بارگشت به سایت پدیرنده بعد از انجام تراکنش |
| mobile | string | خیر | شماره تماس خریدار |
| string | خیر | ایمیل خریدار | |
| cardnumber | string | خیر | شماره کارت جهت پرداخت (در صورت تمایل برای الزام کردن کاربر جهت پرداخت با کارت مشخص) |
| description | string | خیر | توضیحات مربوط به تراکش |
مقادیری که بعد از دریافت توکن ارسال می گردد به شرح زیر می باشد:
| نام | نوع | شرح |
| success | string | وضعیت درخواست که با True/ false مشخص می گردد |
| result | object | در صورت موفقیت آمیز بودن بجکتی با ایندکس توکن باز گردانده می شود |
| errors | string | در صورت وجود خطا لیست خطاها بازگردانده می شود |
مقادیر داخل ایندکسresult به شرح زیر می باشد:
| نام | نوع | شرح |
| token | string | توکن یکبار مصرف جهت اتصال به بانک |
| url | string | آدرس اینترنتی جهت اتصال به بانک |
مرحله دوم :انتقال کاربر به صفحه پرداخت
در صورتی که پاسخ true بود کاربر با توکن 36 کارکتری و فراخوانی url بازگشتی به بانک متصل می گردد.
* نکته : متد فراخوانی آدرس بانک به صورت get می باشد.
در صورت ارسال صحیح توکن کاربر به صفحه بانک redirect می گردد و کاربر 15 دقیقه زمان دارد تا عملیات خرید خود را انجام دهد ، بعد از اتمام عملیات پرداخت یار شپا خریدار را به آدرس مشخص شده منتقل می کند.پارامترهایی که برای کاربر در این مرحله ارسال می گردد به شرح زیر می باشد:
| نام | نوع | شرح |
| status | string | در صورت موفقیت آمیز بودن عملیات success و عدم موفق failed می باشد. |
| token | string | توکن 36 کارکتری ارسال شده در زمان اتصال به بانک |
مرحله سوم :بازگشت به سایت پذیرنده
تایید نهایی عملیات پرداخت با استفاده از آدرس زیر انجام می گردد:
method:post
URL: https://merchant.shepa.com/api/v1/verifyاین آدرس به صورت متد post فراخوانی می گردد و پارامترهای اجباری ارسالی به آین آدرس به شرح زیر می باشد:
| نام | نوع | شرح |
| token | string | توکن 36 کارکتری استفاده شده در مرحله پرداخت |
| amount | Integer | مبلغ تراکنش که در مرحله دریافت توکن ارسال گردیده است |
| api | string | كد 36 كاراكتري درگاه پرداخت |
مقداری که توسط آدرس بالا برگردانده می شود به شرح زیر می باشد :
| نام | نوع | شرح |
| success | string | وضعیت درخواست که با True/ false مشخص می گردد |
| result | object | در صورت موفقیت آمیز بودن آبجکتی با ایندکس refid , date باز گردانده می شود |
| errors | string | در صورت وجود خطا لیست خطاها بازگردانده می شود |
مقادیر داخل ایندکسresult به شرح زیر می باشد:
| نام | نوع | شرح |
| refid | Integer | در صورت موفقیت آمیز بودن عملیات تراکنش ، شماره پیگیری آن بازگردانده می شود. |
| transaction_id | Integer | در صورت موفقیت آمیز بودن شماره تراکنش جهت پیگیری بازگردانده می شود. |
| amount | Integer | در صورت موفقیت آمیز بودن مبلغ نهایی تراکنش بازگردانده می شود. |
| card_pan | string | در صورت موفقیت آمیز بودن ارقامی از کارت خریدار بازگردانده می شود. |
| date | datetime | در صورت موفقیت آمیز بودن تراکنش ، تاریخ انجام تراکنش را باز می گرداند |
* نکته : تا زمانی که عملیات تایید نهایی انجام نگردد ، پول به حساب خریدار بازگشت داده خواهد شد و برای انجام تایید نهایی فقط ۱۵ دقیقه فرصت دارید.
مرحله چهارم: استفاده کردن از متد بازگشت وجه (Refund)
این متد برای برگشت وجه به حساب مشتری با استفاده از کد رهگیری پرداخت انجام میشود. به این صورت که پس از پرداخت وجه در صورتی که پذیرنده امکان ارائه محصولات و یا خدمات خریداری شده را نداشته باشد میتواند از این API برای بازگشت وجه به مشتری استفاده نماید. برای استفاده از این متد ابتدا باید از منوی سرویس ها، سرویس برگشت وجه (Refund) را انتخاب کنید و حساب خود را شارژ نمایید. پس از آن می توانید از طریق این متد نسبت به بازگشت مبلغ مورد نظر خود اقدام نمایید.
آدرس استفاده از برگشت وجه به صورت زیر می باشد:
method:post
URL: https://merchant.shepa.com/api/v1/refund-transactionاین آدرس به صورت متد post فراخوانی می گردد و پارامترهای اجباری ارسالی به آین آدرس به شرح زیر می باشد:
| نام | نوع | شرح |
| api | string | كد 36 كاراكتري درگاه پرداخت |
|
amount
|
Integer | مبلغ برگشت وجه |
| transaction_id | Integer | شماره تراکنش دریافتی در پاسخ متد تایید تراکنش |
مقادیری که بعد از درخواست برگشت وجه ارسال می گردد به شرح زیر می باشد:
| نام | نوع | شرح |
| success | string | وضعیت درخواست که با True/ false مشخص می گردد |
| result | object | در صورت موفقیت آمیز بودن بجکتی با ایندکس توکن باز گردانده می شود |
| errors | string | در صورت وجود خطا لیست خطاها بازگردانده می شود |
مقادیر داخل ایندکسresult شامل کد رهگیری برگشت وجه می باشد.
نحوه استفاده از سند باکس (SandBox)
جهت استفاده از سند باکس از آدرس های زیر به جای آدرس های اصلی استفاده می گردد:
| ردیف | توضیحات | آدرس |
| 1 | آدرس دریافت توکن | https://sandbox.shepa.com/api/v1/token |
| 2 | آدرس تایید نهایی تراکنش | https://sandbox.shepa.com/api/v1/verify |
و به جای کد درگاه (api) ، کلمه sandbox استفاده می گردد.