این سند رفرنس تکنیکال برای استفاده از API نسخهٔ ۳ پرداخت درون برنامه‌ای ارائه می‌کند.

پاسخ‌های بازگشتی سرور


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

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

کد بازگشتیمقدارتوضیحات
BILLING_RESPONSE_RESULT_OK0موفقیت در انجام عمل
BILLING_RESPONSE_RESULT_USER_CANCELED1کاربر عملیات را متوقف کرده است
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE3API‌ برای درخواست ارسال شده پشتیبانی نمی‌شود
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE4این محصول برای فروش موجود نیست
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR5پارامترهای ارسالی به API معتبر نیستند. این خطا زمانی رخ می‌دهد که تغییرات مورد نیاز در مانیفست ایجاد نشده باشد، برنامه در پنل پرداخت بازار ثبت نشده باشد یا مجوزهای لازم برای استفاده از پرداخت را کسب نکرده باشد.
BILLING_RESPONSE_RESULT_ERROR6خطا در هنگام عملیات پرداخت
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED7خطا در خرید به دلیل اینکه این محصول در حال حاضر در «مالکیت» کاربر است
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED8خطا در مصرف، زیرا این محصول مربوط به این کاربر نیست

API Reference


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

متد ()getSkuDetails

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

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

کلیدتوضیحات
productIdشناسهٔ محصول
typeبرای خرید‌های درون برنامه‌ای این مقدار باید “inapp” باشد.
priceقیمت فرمت شده همراه با علامت ریال. توجه کنید که این قیمت همان قیمتی است که در پنل پرداخت وارید کرده‌اید.
titleعنوان محصول
descriptionتوضیحاتی در مورد این محصول

متد ()getBuyIntent

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

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

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

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

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

فیلدتوضیحات
orderIdیک شناسهٔ منحصر به فرد برای هر سفارش
packageNameنام بسته‌ای که توسط آن درخواست خرید صادر شده است.
productIdشناسهٔ محصول. این همان شناسه‌ای است که در پنل مدیریت خرید بازار وارد کرده‌اید.
purchaseTimeزمانی که خرید انجام شده است بر حسب میلی ثانیه ( از epoch (Jan 1, 1970))
purchaseStateوضعیت این سفارش 0 (خریداری شده)، 1 (لغو شده) یا 2 (برگشت خورده).
developerPayloadرشتهٔ ساخته شده توسط توسعه دهنده که حاوی اطلاعات لازم برای خرید این محصول است. شما می‌توانید این رشته را زمانی که درخواست getBuyIntent می‌دهید، ارسال کنید.
purchaseTokenیک توکن که به صورت منحصر به فرد خرید یک محصول توسط یک کاربر را مشخص می‌کند.

متد ()getPurchases

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

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

کلید توضیحات
RESPONSE_CODEمقدار 0 اگر عملیات با موفقیت انجام شده باشد. در غیر این صورت خطا.
INAPP_PURCHASE_ITEM_LISTStringArrayList شامل لیستی از محصولات درون برنامه‌ای برای این برنامه/td>
INAPP_PURCHASE_DATA_LISTStringArrayList حامل جزئیات خرید‌های درون این برنامه. برای باخبر شدن از جزئیات هر مورد ذخیره شده درون INAPP_PURCHASE_DATA، به جدول ۴ مراجعه کنید.
INAPP_DATA_SIGNATURE_LISTStringArrayList حاوی امضای خریدهای درون برنامه‌ای برای این برنامه.
INAPP_CONTINUATION_TOKENیک رشته شامل توکنی برای پیگیری دستهٔ بعدی خریدهای این کاربر درون این برنامه. این فیلد در صورتی مقدار دهی می‌شود که تعداد خریدهای کاربر درون این برنامه زیاد باشد. وقتی که این توکن موجود باشد، برای دریافت بقیهٔ لیست خریدهای کاربر باید یک درخواست دیگر از طریق getPurchases بدهید و این توکن را هم همراه آن بفرستید. پاسخ بازگشتی شامل ادامهٔ لیست خریدهای کاربر خواهد بود و در صورت موجود بودن این توکن باید این روند را تا زمانی که لازم است ادامه دهید تا لیست همهٔ خریدهای کاربر را دریافت کنید.