راهنمای وب‌سرویس‌های درگاه پرداخت آتی‌پی

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

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

• دریافت یک ترمینال از شبکه همراه آتی‌پی
• ارسال 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