نیازمندی‌های پذیرنده

برای استفاده از وب سرویس‌ها نیازمند موارد زیر هستید.

  • دریافت یک ترمینال از شبکه همراه آتی‌پی
  • ارسال IP Address سرور پذیرنده. کلیه درخواست‌های پذیرنده باید از طریق این IP Address اعلام شده به وب سرویس‌ها ارسال شود.
  • دریافت API_KEY از شبکه همراه آتی‌پی.
  • پیاده‌سازی وب سرویس‌ها که در ادامه شرح داده می‌شود.
  • آدرس ارسالی از سمت پذیرنده در متد get-token باید به صورت https باشد. ( این مورد الزام نیست و ترجیحا باید رعایت شود. )

نحوه اتصال به وب‌سرویس

برای اتصال به وب سرویس‌ها باید از آدرس زیر استفاده شود. آین آدرس دارای گواهینامه معتبر SSL می‌باشد.

url: https://mipg.atipay.net/v1/<uri>                                           

قسمت  uri در هر یک از وب سرویس‌ها ذکر خواهد شد.

 .ارسال شود application/json به صورت Content-Type در درخواست‌ها باید

 شرح وب سرویس‌ها:

  • متد دریافت توکن:

  این متد برای دریافت توکن اسفاده می‌شود. توکن دریافتی در متدهای بعدی استفاده می‌شود .

uri : /get-token

پارامترهای ارسالی:  

{

  “amount”: long,

  “cellNumber”: “string”,

  “description”: “string”,

  “invoiceNumber”: “string”,

  “redirectUrl”: “string”,

  “apiKey“: “string”

}

توضیح پارامترهای ارسالی:                                                                 

وضعیت   شرح پارامتر
  اجباری مبلغ تراکنش amount
  اجباری شماره موبایل خریدار  cellNumber
  اختیاری توضیحات تراکنش  description
  اجباری شناسه خرید سمت پذیرنده  invoiceNumber
  اجباری آدرسی که بعد از فرایند پرداخت، خریدار به آن هدایت می‌شود.  redirectUrl
  اجباری این پارامتر از شبکه همراه آتی‌پی دریافت می‌شود.  apiKey

پارمترهای خروجی:

{

  “status”: “string”,

  “token”: “string”,

  “errorCode”: “string”,

  “errorDescription”: “string”,

 }

نکته: در نسخه‌های بعدی این خروجی تغییر میکند.

توضیح پارامترهای خروجی:

 شرح  پارامتر
وضعیت سرویس status
توکن دریافتی که در وب سرویس‌های بعدی استفاده می‌شود token
کد خطا errorCode
شرح خطا erroDescription

– متد هدایت به سایت پرداخت:

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

 uri : /redirect-to-gateway

در این متد توکن ارسالی در متد get-token توسط فرم ارسال می‌شود. ( این فرم می‌تواند به صورت auto-submit) ارسال شود و خریدار نباید این فرم را submit کند.

<form action=”<url/uri>” method=”POST”>

<input type=”hidden” value=”<token>” name=”token”>

</form>

بعد از ارسال فرم و هدایت به سایت پرداخت، خریدار با استفاده از اطلاعات کارت تراکنش خرید را انجام می‌دهد و بعد از آن به redirectUrl که در متد get-token تعیین شده است با متد POST هدایت می‌شود.

پارامترهای دریافتی به شرح ذیل می‌باشد:

 شرح  پارامتر
وضعیت تراکنش (جدول ۱ پیوستها) state
کد وضعیت پرداخت (جدول ۱ پیوستها) status
رسید دیحیتالی پرداخت که ۵۰ حرف/عدد میباشد referenceNumber
شناسه واحدی که توسط پذیرنده در متد get-token ارسال شده است                                    reservationNumber 
شماره ترمینال پذیرنده که پرداخت با آن انجام شده است terminalId
شماره پیگیری در سایت پرداخت traceNumber

متد verify پرداخت:

بعد از هدایت خریدار به سایت پذیرنده، باید یک تاییدیه از سمت پذیرنده ارسال شود تا نهایی شدن خرید انجام شود. در صورت عدم ارسال این متد، مبلغ تراکنش به خریدار برگردانده می‌شود.

uri : /verify-payment

 پارامترهای ارسالی: 

{

  “terminalId”: “string”,

  “referenceNumber”: “string”,

  “apiKey“: “string”,

 }

توضیح پارامترهای ارسالی: 

شرح پارامتر  
این پارامتر در جواب متد redirect-to-gateway دریافت شده است   terminalId
این پارامتر در جواب متد redirect-to-gateway دریافت شده است    referenceNumber
این پارامتر از شبکه همراه آتی‌پی دریافت می‌شود.    apiKey

 پارامترهای خروجی:

  شرح   پارامتر
مبلغ تراکنش amount

پیوستها:

جدول ۱:

شرح  state  Status
کاربر انصراف داده است  CanceledByUser ۱
پرداخت با موفقیت انجام شد   OK  
پرداخت انجام نشد  Failed  3
کاربر در بازه زمانی تعیین شده پاسخی ارسال نکرده است  SessionIsNull  4
پارامترهای ارسالی نامعتبر است   InvalidParameters  5
آدرس سرور پذیرنده نامعتبر است MerchantIpAddressIsInvalid  8
توکن ارسال شده یافت نشد  TokenNotFound  10
با این شماره ترمینال فقط تراکنش‌های توکنی قابل پرداخت هستند TokenRequired  11
شماره ترمینال ارسال شده یافت نشد TerminalNotFound  12

1 دیدگاه

پاسخی بگذارید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *