مرجع پرداخت

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

کدهای بازگشتی از سِرور

جدول زیر فهرست کاملی از پاسخ‌هایی که سِرور بازار به برنامهٔ شما باز می‌گرداند را ارائه می‌کند. کد پاسخ، عددی است که در کلید RESPONSE_CODE در Bundle بازگشتی‌ از بازار قرار دارد. باید تمام این کدهای پاسخ را در برنامه‌تان مدیریت کنید.

جدول ۱. کدهای بازگشتی در API نسخهٔ ۳ پرداخت

کد بازگشتی	مقدار	توضیحات
BILLING_RESPONSE_RESULT_OK	0	با موفقیت انجام شد.
BILLING_RESPONSE_RESULT_USER_CANCELED	1	کاربر عملیات را لغو کرد.
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE	3	API‌ برای درخواست ارسال شده پشتیبانی نمی‌شود.
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE	4	این محصول برای فروش موجود نیست.
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR	5	پارامترهای ارسالی به API معتبر نیستند. این خطا همچنین می‌تواند بیانگر این موارد باشد: برنامه به درستی امضا نشده است، تغییرات مورد نیاز در مانیفست ایجاد نشده است، برنامه در پنل پرداخت بازار ثبت نشده یا مجوزهای لازم برای استفاده از پرداخت را کسب نکرده است.
BILLING_RESPONSE_RESULT_ERROR	6	خطا در هنگام انجام عملیات پرداخت
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED	7	خطا در خرید به دلیل اینکه این محصول در حال حاضر در «مالکیت» کاربر است.
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED	8	خطا در مصرف، زیرا این محصول تحت «مالکیت» کاربر نیست.

مرجع API

API پرداخت‌ درون برنامه‌ای در فایل IInAppBillingService.aidl تعریف شده است. این فایل را می‌توانید در برنامهٔ نمونه پیدا کنید.

()getSkuDetails

این متد جزئیات محصول‌ هر یک از شناسه‌های محصول مشخص شده در لیست را برمی‌گرداند. در Bundle بازگشتی از بازار، نتایج کوئری در یک ArrayList رشته‌ای که به کلید DETAILS_LIST نگاشته شده است، قرار گرفته‌اند. هر رشته در این آرایه حاوی اطلاعات محصول در فرمت JSON است. فیلدهای رشته‌‌ی JSON در جدول زیر توضیح داده شده‌اند.

جدول ۲. توضیحات فیلدهای موجود در رشتهٔ JSON بازگشتی با فراخوانی متد getSkuDetails.

کلید	توضیحات
productId	شناسهٔ محصول (یا SKU)
type	مقدار آن برای محصولات درون برنامه‌ای فروشی "inapp" و برای اشتراک‌ها "subs" است.
price	قیمت فرمت شده همراه با علامت ﷼. توجه کنید که این قیمت همان قیمتی است که در پنل پرداخت وارید کرده‌اید.
title	عنوان محصول
description	توضیحاتی در مورد این محصول

()getBuyIntent

این متد یک کد پاسخ (که در کلید RESPONSE_CODE قرار دارد) و یک PendingIntent برای راه‌اندازی خرید محصول (که در کلیدBUY_INTENT قرار دارد) را باز می‌گرداند. بازار پس از دریافت PendingIntent، یک Intent پاسخ حاوی داده‌های مربوط به آن خرید را برمی‌گرداند. در جدول ۳ داده‌های بازگشتی در Intent پاسخ به صورت خلاصه توضیح داده شده‌اند.

جدول ۳. داده‌های بازگشتی بعد از درخواست خرید در API نسخهٔ ۳

کلید	توضیحات
RESPONSE_CODE	اگر مقدار آن 0 باشد نشان‌دهنده یک خرید موفقیت‌آمیز است. هر مقدار دیگر نشان‌دهندهٔ بروز خطا است.
INAPP_PURCHASE_DATA	یک رشته حاوی اطلاعات خرید در فرمت JSON است. توضیحات فیلدهای این رشته در جدول ۴ آمده است.
INAPP_DATA_SIGNATURE	یک رشته حاوی امضای اطلاعات خرید می‌باشد که توسط کلید خصوصی توسعه‌دهنده امضا شده است.

جدول ۴ فیلدهای JSON حاوی اطلاعات سفارش را به اختصار توضیح می‌دهد.

جدول ۴. توضیحات فیلدهای JSON در INAPP_PURCHASE_DATA.

فیلد	توضیحات
autoRenewing	این فیلد بیانگر این است که آیا اشتراک به صورت خودکار تمدید می‌شود یا خیر. در صورتی که مقدار آن true باشد، اشتراک فعال است و به صورت خودکار با سررسیدن تاریخ پرداخت بعدی فعال می‌شود. در صورتی که مقدار آن false باشد،‌ بیانگر این است که کاربر اشتراک را لغو کرده است. در این صورت کاربر تنها تا پایان دوره‌ٔ فعلی اشتراکش به محتوای اشتراک دسترسی خواهد داشت و با اتمام دوره‌ٔ فعلی اجازه‌ٔ دسترسی به محتوای اشتراک را از دست خواهد داد (مگر این‌که دوباره قابلیت تمدید خودکار را فعال کند یا آن را به صوت دستی، آن‌گونه که در قسمت تمدید دستی توضیح داده شده است، تمدید کند).
orderId	یک شناسهٔ منحصر به فرد برای هر سفارش.
packageName	نام بستهٔ برنامه‌ای که خرید از آن صورت گرفته.
productId	شناسهٔ محصول یا SKU. که در هنگام اضافه کردن محصول در پنل پرداخت آن را تعریف می‌کنید.
purchaseTime	زمان خرید محصول را بر حسب میلی ثانیه (از تاریخ ۱ ژانویه ۱۹۷۰) نشان می‌دهد.
purchaseState	وضعیت این سفارش. مقادیر ممکن عبارتند از: 0 (خریداری شده)، 1 (لغو شده)، 2 (برگشت خورده).
developerPayload	رشته‌ای است که توسعه‌دهنده آن را می‌سازد و حاوی اطلاعات تکمیلی در مورد سفارش خرید است. زمانی که درخواست  getBuyIntent  را می‌سازید می‌توانید مقداری نیز برای این فیلد مشخص کنید.
purchaseToken	رشته‌‌ای است که توسط بازار برای شناسایی یکتای یک تراکنش پرداخت ساخته می‌شود.

()getPurchases

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

جدول ۵. پاسخ بازگشتی حاصل از فراخوانی متد getPurchases.

کلید	توضیحات
RESPONSE_CODE	اگر درخواست موفقیت‌آمیز باشد مقدار آن 0 است. هر مقدار دیگر نشان‌دهندهٔ بروز خطا است.
INAPP_PURCHASE_ITEM_LIST	یک ArrayList رشته‌ای حاوی لیستی از شناسهٔ محصولات است.
INAPP_PURCHASE_DATA_LIST	یک ArrayList حاوی جزئیات خرید‌ها است. برای آگاهی از جزئیات اطلاعات ذخیره شده در هر آیتم INAPP_PURCHASE_DATA از لیست، به جدول ۴ مراجعه کنید.
INAPP_DATA_SIGNATURE_LIST	یک ArrayList رشته‌ای حاوی امضای خریدها است.
INAPP_CONTINUATION_TOKEN	توکنی برای بازیابی دستهٔ بعدی محصولات درون‌برنامه‌ای که این کاربر مالک آن‌ها است. بازار در صورتی این فیلد را مقداردهی می‌کند که تعداد محصولاتی که کاربر صاحب آن‌ها است، زیاد باشد. وقتی که این توکن در پاسخ موجود باشد، برای دریافت مابقی لیست خریدهای کاربر باید مجدداً   getPurchases را فراخوانی کرده و این توکن را نیز به آن بدهید. پاسخ بازگشتی شامل ادامهٔ لیست خریدهای کاربر و احتمالاً توکنی دیگر خواهد بود. در صورت موجود بودن این توکن  در پاسخ برگردانده شده، باید این روند را تا زمانی که لازم است ادامه دهید تا لیست همهٔ خریدهای کاربر را دریافت کنید.