# راهنمای API درگاه پرداخت

API های همراه پی بر پایه استاندارد RESTful طراحی شده اند که هر کدام دارای یک آدرس URL مشخص است. ارسال اطلاعات به URL با استفاده از متد POST انجام میشود و پاسخ های دریافتی به صورت JSON است.

جهت رفع هرگونه مشکل یا پرسش با پشتیبانی همراه پی در تماس باشید.

# مرحله 1 - ارسال اطلاعات

در مرحله ای اول، باید اطللاعات پرداخت را به صورت POST به آدرس مشخص شده ارسال نمایید.

https://api.hamrahpay.com/api/v1/rest/pg/pay-request

# فیلد های اطلاعات

نام فیلد نوع فیلد توضیحات
api_key String api_key دریافت شده از بخش کسب و کار های شما در داشبورد همراه پی (اجباری)
amount Integer مبلغ قابل پرداخت به ریال ، بدون اعشار و بزرگتر یا مساوی 10000 ریال (اجباری)
callback_url String آدرس بازگشت پس از پرداخت به صورت urlencode. این آدرس باید آدرس دامنه تایید شده در کسب و کار یکسان باشد. (اجباری)
description String توضیحات تراکنش (اجباری)
customer_name String نام مشتری (اختیاری)
mobile String شماره موبایل مشتری (اختیاری)
email String آدرس ایمیل مشتری (اختیاری)
allowed_cards Json Object شماره کارت/کارت های مجاز برای انجام تراکنش. به صورت آبجکت json از شماره 16 رقمی کارت های مجاز

توضیحات

allowed_cards مناسب کسب و کارهایی است که از قبل احراز هویت کاربران خود را انجام داده اند و برای پیشگیری از هرگونه سوء استفاده، پرداخت هر مشتری را محدود به شماره کارتهای آن مشتری مینمایند.

نمونه allowed_cards

{
    '6389204646429312',
    '6399632242377493'
} 

فیلد های پاسخ

نام فیلد نوع فیلد توضیحات
status Integer نشان دهنده وضعیت پاسخ - مقدار 1 به معنای بدون خطا و 0 به معنای بروز خطا
payment_token String توکن پرداخت
pay_url String لینک پرداخت، با هدایت مشتری به این لینک، صفحه ی پرداخت نمایش داده میشود.
error_code String در صورت بروز خطا، کد خطا را نشان میدهد. در انتهای این مستندات، جدول کدهای خطا و توضیحات آن ارائه شده است.
error_message String در صورت بروز خطا، کلید متن خطا را نمایش میدهد.

نکته

اگر میخواید به جای دریافت لینک صفحه ی پرداخت، تصویر QR-Code آن را دریافت کنید میتونید به جای URL بالا از این URL استفاده کنید

https://api.hamrahpay.com/api/v1/rest/pg/pay-request/qrcode

# مرحله 2- هدایت کاربر به صفحه ی پرداخت

در صورتی که در مرحله ی قبل خطایی دریافت نشود، در پاسخ به درخواست شما یک توکن پرداخت و لینک صفحه ی پرداخت داده خواهد شد. با هدایت کاربر به لینک صفحه پرداخت در فیلد pay_url صفحه ی پرداخت نمایش داده میشود.

نکته

کاربر باید به لینک صفحه ی پرداخت ریدایرکت شود. در صورتی که با متد POST کاربر را به صفحه ی پرداخت هدایت کنید با خطا روبرو خواهید شد.

# مرحله 3- بازگشت به سایت پذیرنده

پس از انجام عملیات پرداخت در صفحه ی پرداخت بانک، کاربر به آدرس callback_url سایت پذیرنده هدایت میشود. در این مرحله با توجه به اقلام اطلاعاتی ارسال شده به سایت پذیرنده، میتوان وضعیت پرداخت را تشخیص داد. اقلام اطلاعاتی با استفاده از متد GET به سایت پذیرنده ارسال میشودند

اقلام اطلاعاتی

نام فیلد نوع فیلد توضیحات
status String در صورتی که مقدار آن برابر OK بود یعنی پرداخت موفق بوده است. و در صورتی که مقدار آن NOK است به معنای پرداخت نا موفق است.
payment_token String توکن پرداخت شده
error String در صورت پرداخت ناموفق، خطا را نمایش میدهد.

# مرحله 4- وریفای تراکنش

در صورتی که در مرحله ی قبل مقدار status برابر یا OK بود باید این مرحله را انجام دهید در غیر اینصورت باید خطای مرتبط را به کاربر نمایش دهید.

نکته

با هر بار فراخوانی متد وریفای،پاسخ وریفای اعلام میشود. برای پیشگیری از هرگونه سوء استفاده، الزاما باید قبل از ارائه ی محصول و یا خدمات به خریدار، توکن پرداخت را در پایگاه داده خود چک نمایید و در صورت عدم وجود و پرداخت موفق، محصول و خدمات را ارائه نمایید.

در صورت وجود توکن پرداخت در پایگاه داده شما، بدین معنی است که این تراکنش قبلا انجام شده است و مشتری سعی در شارژ مجدد حساب خود برای دریافت محصول یا خدمات دارد و در این صورت نباید خدماتی ارائه شود. در اصطلاح به این موضوع Double Spending میگویند.

ادرس URL وریفای تراکنش که باید اقلام اطلاعات مورد نیاز با متد POST به آن ارسال شود.

https://api.hamrahpay.com/api/v1/rest/pg/verify

اقلام اطلاعاتی ارسالی توسط شما

نام فیلد نوع فیلد توضیحات
api_key String api_key دریافت شده از بخش کسب و کار های شما در داشبورد همراه پی (اجباری)
payment_token String دریافتی در مرحله قبل

نمونه پاسخ دریافتی در صورت پرداخت موفق

{
    "status"            :  100,
    "reserve_number"    :  "شماره پیگیری",
    "reference_number"  :  "شماره مرجع پرداخت",
    "payment_token"     :  "توکن پرداخت"
}

اقلام اطلاعاتی دریافتی در پاسخ

نام فیلد نوع فیلد توضیحات
status String وضعیت پرداخت . در صورتی که مقدار آن 100 یا 101 بود به معنی پرداخت موفق است. مقدار 100 در اولین پاسخ به هر تراکنش به همراه شماره پیگیری و شماره مرجع است و مقدار 101 در درخواست های بعدی برای هر تراکنش بدون شماره پیگیری و شماره مرجع. در هر صورت 100 یا 101 به معنی پرداخت موفق است
reserve_number String شماره پیگیری تراکنش
reference_number String شماره مرجع بانکی تراکنش
payment_token String توکن پرداخت

در این مرحله، در صورت دریافت پاسخ پرداخت موفق و توجه به نکته بالا میتوانید محصول/خدمات خود را به مشتری ارائه نمایید.

# متد کمکی - دریافت لیست تراکنش های وریفای نشده

در برخی مواقع ممکن است پس از بازگشت مشتری از صفحه ی پرداخت به وب سایت شما، وب سایت شما به هر دلیلی از دسترس خارج شده باشد و نتوانید پاسخ انجام تراکنش مشتری را دریافت کرده و نمایش دهد. با استفاده از این متد میتوانید لیست تراکنش های وریفای نشده ی خود را دریافت کرده و اقدام به وریفای آنها نمایید. در این صورت میتوانید بدون از دست دادن پرداخت های مشتریان، اقدام به ارائه محصول و خدمات کنید.

ادرس URL دریافت لیست تراکنش های وریفای نشده با متد POST

https://api.hamrahpay.com/api/v1/rest/pg/get-unverfied-payments

اقلام اطلاعاتی ارسالی توسط شما

نام فیلد نوع فیلد توضیحات
api_key String api_key دریافت شده از بخش کسب و کار های شما در داشبورد همراه پی (اجباری)

نمونه پاسخ دریافتی

[
    {
        "payment_token" :   "توکن پرداخت",
        "status"        :   "وضعیت پرداخت"
    },
    {
        "payment_token" :   "توکن پرداخت",
        "status"        :   "وضعیت پرداخت"
    }
]

اقلام اطلاعاتی در پاسخ

نام فیلد نوع فیلد توضیحات
status String وضعیت پرداخت . 1 به معنای موفق و 0 به معنای ناموفق
payment_token String توکن پرداخت

# جدول کد های خطا

کد خطا کلید خطا توضیحات فارسی
-1 invalid_data اطلاعات ارسال شده صحیح نیست
-2 invalid_api_key_or_ip API_KEY یا IP درخواست کننده صحیح نیست
-3 amount_is_less_or_more_than_allowed_value مبلغ کمتر یا بیشتر از حد مجاز است
-4 terminal_is_not_active کسب و کار غیر فعال است
-5 request_not_found درخواست یافت نشد
-6 payment_was_not_succeed پرداخت موفق نبوده است.
-7 invalid_output_param پارمتر نوع خروجی معتبر نیست
-14 terminal_not_defined کسب و کار معتبر نیست.
-15 invalid_token توکن پرداخت نامعتبر است.
-100 unknown_error خطایی در عملیات رخ داده است.