# پرداخت درون برنامه ای اپلیکیشن های موبایل

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

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

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

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

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

https://api.hamrahpay.com/api/v1/rest/in-app-purchase/pay-request

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

نام فیلد نوع فیلد توضیحات
sku_token String شناسه کالای دریافت شده از داشبورد همراه پی در بخش کالاهای اپلیکیشن (اجباری)
customer_identity Integer شناسه ای برای شناسایی مشتری . این شناسه میتواند شناسه دستگاه مشتری، نام کاربری مشتری در سرویس شما و یا هر نوع رشته ی منحصر به مشتری شما باشد (اجباری)
os_name String نام سیستم عاملی که اپ شما در آن نصب شده است. نام های مجاز
android ios ipados macos windows blackberry crossplatforms tizen harmonyos (اجباری)
application_scheme String Application Scheme شناسه ای برای شناسایی اپ شما در سیستم عامل جهت عملیات بازگشت از صفحه ی پرداخت به اپلیکیشن شما و اعلام نتیجه ی پرداخت است . این نام باید شامل حروف انگلیسی و اعداد بدون فاصله باشد. (اجباری)
customer_name String نام مشتری (اختیاری)
mobile String شماره موبایل مشتری (اختیاری)
library_name String نام کتابخانه . در صورتی که شما کتابخانه ای برای اتصال به سرویس پرداخت درون برنامه ای همراه پی تهیه کرده اید باید یک نام یکتا برای کتابخانه خود انتخاب نمایید. این نام باید با حروف انگلیسی و اعداد باشد. (اجباری)

فیلد های پاسخ

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

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

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

نکته

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

ملاحظات امنیتی

  • لینک صفحه ی پرداخت الزاما باید در مرورگر خارج از برنامه باز شود و هرگونه استفاده از انواع WebView برای نمایش صفحه ی پرداخت در داخل برنامه مجاز نیست
  • هرگونه شبیه سازی مرورگر در داخل برنامه غیر مجاز است.

# مرحله 3- بازگشت به اپلیکیشن و وریفای تراکنش

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

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

https://api.hamrahpay.com/api/v1/rest/in-app-purchase/verify

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

نام فیلد نوع فیلد توضیحات
sku_token String شناسه کالای دریافت شده از داشبورد همراه پی در بخش کالاهای اپلیکیشن (اجباری)
payment_token String توکن پرداخت
customer_identity String شناسه ای برای شناسایی مشتری . این شناسه میتواند شناسه دستگاه مشتری، نام کاربری مشتری در سرویس شما و یا هر نوع رشته ی منحصر به مشتری شما باشد (اجباری)

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

{
    "status"            :  1,
    "status_type"       :  "OK",
    "verified_at"       :  "تاریخ وریفای",
    "expires_at"        :  "تاریخ انقضا",
    "now"               :  "تاریخ و زمان حال حاضر"
}

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

نام فیلد نوع فیلد توضیحات
status String کد وضعیت پرداخت. 1 به معنای پرداخت موفق
status_type String نوع وضعیت . OK در زمان پرداخت موفق
verified_at String تاریخ وریفای
expires_at String تاریخ انقضاء در صورتی که کالا از نوع اشتراک زمانی باشد.
now String تاریخ و ساعت حال برای مقایسه با تاریخ و زمان وریفای و جلوگیری از دستکاری تاریخ و ساعت توسط کاربر در دستگاه مورداستفاده

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

# متد کمکی - دریافت اطلاعات آخرین پرداخت کاربر

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

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

https://api.hamrahpay.com/api/v1/rest/get-last-purchase

# متد کمکی - دریافت اَبَر داده های اپلیکیشن

اَبَر داده یا MetaData یک مجموعه ای از اطلاعات است که شما میتوانید به هر اپلیکیشن اضافه نمایید و از آن در برنامه های خود استفاده کنید

داده ها به صورت key,value در داشبورد همراه پی به اپلیکیشن اضافه میشود و با استفاده از API میتوانید به آنها دسترسی داشته باشید این داده ها را میتوانید هر زمان بروز رسانی، اضافه و یا حذف نمایید

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

  • تنظیمات خاص اپلیکیشن که به صورت مدام در حال تغییر است
  • URL های پویا در برنامه برای زمان هایی که در برنامه خود از وب سرویس های خاص استفاده میکنید و پس از مدتی URL تغییر میکند و شما با استفاده از این قابلیت دیگر نیازی به بروز رسانی نرم افزار ندارید
  • فعال و غیر فعال سازی اپلیکیشن از راه دور
  • مثال های دیگر از شما 😃

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

https://api.hamrahpay.com/api/v1/rest/get-product-metadata

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

نام فیلد نوع فیلد توضیحات
product_token String شناسه اپلیکیشن

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

[
    {
        "key"   :   "example-key-1",
        "value" :   "example-value-1"
    },
    {
        "key"   :   "example-key-2",
        "value" :   "example-value-2"
    },
    .
    .
    .
    {
        "key"   :   "example-key-n",
        "value" :   "example-value-n"
    },
]

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

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

https://api.hamrahpay.com/api/v1/rest/get-product-skus

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

نام فیلد نوع فیلد توضیحات
product_token String شناسه اپلیکیشن

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

[
    {
        "token"   : "توکن sku",
        "name"    : "کالای تست",
        "price"   : "15000",
        "duration": "30"
    },
    {
        "token"   : "توکن sku",
        "name"    : "کالای تست",
        "price"   : "15000",
        "duration": "30"
    },
    .
    .
    .
    {
        "token"   : "توکن sku",
        "name"    : "کالای تست",
        "price"   : "15000",
        "duration": "30"
    },
]

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

نام فیلد نوع فیلد توضیحات
token String توکن sku
name String نام کالا
price String مبلغ
duration 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 پارمتر نوع خروجی معتبر نیست
-12 inactive_in_app_product اپلیکیشن غیرفعال است
-13 inactive_in_app_product_sku کالای مورد نظر غیر فعال است
-14 terminal_not_defined کسب و کار معتبر نیست.
-15 invalid_token توکن پرداخت نامعتبر است.
-100 unknown_error خطایی در عملیات رخ داده است.