مستندات فني اتصال به درگاه پرداخت اينترنتي شپا
با استفاده از این سرویس قادر خواهید بود وب سایت و پلتفرم تون رو به شبکه پرداخت شپا وصل کنید. برای این منظور می بایست سه مرحله رو انجام بدید
در این مستند چگونگی استفاده از سرویس پرداخت اینترنتی بر بستر وب و بر پایه پروتکل امن https توضیح داده شده است.سرویس ها در قالب آدرس های اینترنتی در اختیار پذیرندگان قرار می گیرد تا در سایت خود استفاده نمایند.
مرحله اول : ارسال دیتا
پذیرنده اطلاعات مورد نیاز را از خریدار دریافت نموده و به آدرس زیر ارسال می نماید .متد مورد استفاده جهت فراخوانی آدرس دریافت توکن به صورت post می باشد.
method:post
URL: https://merchant.shepa.com/api/v1/token
پارامترهای ارسالی به شرح زیر می باشد :
| نام | نوع | اجباری | شرح |
| api | string | بله | كد 36 كاراكتري درگاه پرداخت |
| amount | Integer | بله | مبلغ تراکنش (واحد در زمان تعریف درگاه پرداخت مشخص می گردد) |
| callback | string | بله | آدرس بارگشت به سایت پدیرنده بعد از انجام تراکنش |
| mobile | string | خیر | شماره تماس خریدار |
| string | خیر | ایمیل خریدار | |
| description | string | خیر | توضیحات مربوط به تراکش |
| order | object | بله | جزییات سفارش |
پارامتر های مربوط به جزییات سفارش :
| نام | نوع | اجباری | شرح |
| total | Integer | بله | مجموع پرداختی سفارش |
| billing | object | بله | اطلاعات آدرس صورت حساب |
| shipping | object | خیر | اطلاعات پستی (در صورتی که ارسال نشود به صورت پیشفرض اطلاعات صورت حساب ذخیره خواهد شد) |
| products | array | بله | آرایه ای از کالاهای درون سبد خرید برای فروش |
پارامتر های مربوط به billing:
| نام | نوع | اجباری | شرح |
| first_name | string | بله | نام مشتری |
| last_name | string | بله | نام خانوادگی مشتری |
| address_1 | string | بله | آدرس مشتری |
| city | string | بله | شهر مشتری |
| state | string | بله | استان مشتری |
| postcode | string | بله | کد پستی مشتری |
| country | string | بله | کشور مشتری (طبق استاندارد دو کارکتری ایزو 3166 ) |
| string | بله | پست الکترونیکی مشتری | |
| phone | string | بله | تلفن مشتری |
برای پرداخت های دلاری باید اطلاعات کالاهای مورد نظر برای فروش را ارسال نماییم
این اطلاعات را در به صورت آرایه ای از داده ها در پالامتر products ارسال می کنم که جزییات آن به صورت زیر می باشد:
| نام | نوع | اجباری | شرح |
| id | Integer | بله | کد کالا |
| name | string | بله | نام کالا |
| slug | string | خیر | شناسه یکتای کالا |
| price | Integer | بله | قیمت کالا |
| qty | Integer | بله | تعداد |
| image | 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 فراخوانی می گردد و پارامترهای اجباری ارسالی به آین آدرس به شرح زیر می باشد:
| نام | نوع | شرح |
|
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 استفاده می گردد.