پرداخت

مقدمه

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

  • احراز هویت

  • درخواست سفارش پس از درخواست کاربر برای دریافت یک سرویس

  • تعریف یک وب‌سرویس با متود دریافتی POST که پس از پرداخت توسط کاربر به آن درخواست داده خواهد شد.

  • تأیید پرداخت کاربر درصورت دریافت وضعیت PAID از سوی سرور iGap API


احراز هویت

برای استفاده از سرویس‌های iGap API باید حتماً احراز هویت شوید. برای این منظور لازم است تا refresh_token دریافتی را به API زیر ارسال کنید و یک access_token دریافت نمایید.

https://api.igap.net/services/v1.0/auth/tokenAPI
POSTMETHOD
Content-Type: application/jsonHEADERS
}
"refresh_token": "e7fa1267-3b9c-4f0b-92f6-a79af20b095a"
{
BODY
}
"refresh_token": "e7fa1267-3b9c-4f0b-92f6-a79af20b095a"
"expires_in": 1800
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6IjVjZ"
"token_type": "bearer"
{
RESPONSE

لازم به ذکر است که access_token دریافتی هر نیم ساعت پس از دریافت یا درصورت درخواست مجدد به همین API منقضی می‌گردد


درخواست ثبت سفارش

برای درخواست سفارش لازم است تا API زیر توسط شما فراخوانی گردد:

https://api.igap.net/services/v1.0/payment/orderAPI
POSTMETHOD
Content-Type: application/json Authorization: Bearer {{access_token}}HEADERS
}
"order_id": "10006"
"price": 1000
"callback_url": "http://bot.some-services.com/callback-when-payment-done"
:"item"
}
"title": "لباس دخترانه"
"description": "لباس یک تکه دخترانه نلیوفرانه به قیمت 450000 ریال"
"weight": 45,
"size": "L"
"name": "Blue Fab Shirt"
{
{
BODY
}
"token": "77052efa-9f24-40a1-8f74-331efcfed388"
{
RESPONSE

برای فراخوانی این API باید acces_token دریافتی از API احراز هویت را به همراه مقدار Bearer (با یک فاصله خالی) در فیلد Authorization در هدر درخواست قرا دهید.




مقادیر ورودی برای فراخوانی این API به شرح ذیل است:

فیلد ورودیتوضیحاتنکات
order_idشماره سفارشاین شماره باید به ازای هر سفارش منحصر به فرد باشد.
priceقیمت سرویس مورد نظربه ریال باشد.
callback_urlوب سرویسی که پس از پرداخت توسط کاربر، توسط سرور iGap API به آن درخواست داده می‌شود.باید سمت بات یا سرور سوم شخص، پیاده‌سازی شده باشد و حتماً متود دریافتی آن POST باشد..
itemمشخصات سفارش انجام شده توسط کاربرمقدار title و description ضروری است.همچنین پیشنهاد می‌شود در مقدار description مقدار قیمت نیز در متن قرار گیرد.

لازم به ذکر است که مقدار token دریافتی باید حتماً به کلاینت اپلیکیشن باز گردد تا اپلیکیشن بتواند فرآیند پرداخت را ادامه دهد.


تعریف وب سرویس Callback

هدف وجودی این وب‌سرویس این است که بر اساس وضعیت پرداخت دریافتی از سمت سرور iGap API اقدامات لازم توسط بات‌ها یا سرورهای سوم شخص انجام شود؛ یعنی فرض کنین قرار است کاربر پس از پرداخت قیمت لباس یک کد رهگیری سفارش دریافت کند، بنابراین لازم است در این وب‌سرویس چک شود تا اگر پرداخت توسط کاربر به درستی انجام شده بود، کد رهگیری سفارش خرید لباس به کاربر ارسال شود.

همان‌طور که گفته شد این وب‌سرویس توسط بات یا سرور سوم‌شخص پیاده‌سازی شده است و وضعیت پرداخت کاربر و توکن دریافتی درصورتی که وضعیت پرداخت PAID باشد، توسط سرور iGap API به آن ارسال می‌شود.

موارد دریافتی به شرح ذیل است:

فیلد دریافتیتوضیح
order_idشماره سفارش ارسالی در فراخوانی API مربوط به درخواست سفارش، ارسال شده توسط بات یا سرور سوم‌شخص
nameعنوان ارسالی برای سفارش انجام شده در فراخوانی API مربوط به درخواست سفارش، ارسال شده توسط بات یا سرور سوم‌شخص
descriptionتوضیح ارسالی برای سفارش انجام شده در فراخوانی API مربوط به درخواست سفارش، ارسال شده توسط بات یا سرور سوم‌شخص
productکل مشخصات سفارش ارسالی برای سفارش انجام شده در فراخوانی API مربوط به درخواست سفارش، ارسال شده توسط بات یا سرور سوم‌شخص
priceمقدار قیمت ارسالی برای سفارش انجام شده در فراخوانی API مربوط به درخواست سفارش، ارسال شده توسط بات یا سرور سوم‌شخص
statusوضعیت پرداخت
tokenتوکن ارسالی و منحصر به فرد از سمت بانک برای این پرداخت. (درصورتی که پرداخت موفق باشد، اعتبار دارد).


وضعیت‌های ارسالی به شرح ذیل است:

وضعیتتوضیح
CANCELED_BY_USERپرداخت توسط کاربر لغو شد.
FAILUREپرداخت موفقیت آمیز نبود.
IPG_CONNECTION_TIMEOUTپاسخی از سمت بانک دریافت نشد.
PAIDپرداخت موفقیت آمیز بوده است.

لازم به ذکر است که این وب‌سرویس همان فیلد ورودی callback_url در API درخواست ثبت سفارش است.


تأیید پرداخت

این مرحله بسیار حائز اهمیت است، چرا که با فراخوانی API تأیید پرداخت از سوی بات‌ها یا سرورهای سوم‌شخص است که سرور iGap API پرداخت کاربر را نهایی تلقی می‌کند، و درصورتی که 15 دقیقه از پرداخت توسط کاربر گذشته باشد ولی هنوز API تأیید توسط بات یا سرور سوم‌شخص فراخوانی نشده باشد، پول پرداختی توسط کاربر به او بازپس داده می‌شود و عواقب هرگونه سهل‌انگاری در فراخوانی درست و به‌موقع این API توسط بات‌ها یا سرورهای سوم‌شخص به عهده خود آن‌ها است و پیام‌رسان آیگپ هیچ‌گونه مسئولیتی در این خصوص بر عهده نخواهد گرفت.

API تأیید پرداخت به شرح ذیل است:

https://api.igap.net/services/v1.0/payment/confirmAPI
POSTMETHOD
Content-Type: application/json Authorization: Bearer {{access_token}}HEADERS
{"token": "5684765",}BODY
{success: true}RESPONSE

درصورتی که تأیید با موقیت انجام شود، فیلد success مقدار true را خواهد داشت.


نکاتی در مورد API ها

در مورد فراخوانی API ها نکات زیر قابل توجه است:

  • در صورتی که API به درستی فراخوانی شود HTTP STATUS از خانواده 200 یا همان 2XX خواهد بود.

  • در صورتی که مقادیر ورودی به API توسط بات یا سرور سوم‌شخص مشکلی داشته باشد و به درستی ورودی ارسال نشده باشد، یا در هر حالت دیگری که ایراد از درخواست بات یا سرور سوم‌شخص باشد، HTTP STATUS از خانواده 400 یا همان 4XX است.

  • در صورتی که ایراد از سمت سرور iGap API باشد HTTP STATUS از خانواده 500 یا همان 5XX است.

  • در صورتی که HTTP STATUS از خانواده 500 یا 400 باشد، پاسخ یک JSON به فرمت زیر است:

فیلدتوضیح
nameیک رشته متنی شامل کد متنی خطای رخ داده
messageمتن پیام خطای رخ داده
detailsجزئیات اضافه در مورد خطای رخ داده که حتی ممکن است در جواب وجود نداشته باشد.

ساخت دکمه ی پرداخت

برای ساخت دکمه ی پرداخت کافیست در ساختار دکمه actionType را عدد 8 (BUTTON_ACTION_PAY_DIRECT) قرار دهید و در داخل value توکن دریافتی از بانک را قرار دهید .

this.additionalData.push([
{
actionType: 8,
label: "پرداخت",
value: {token: bankResponse.token},
imageUrl: "",
}
]);