Warning: AIDL is now deprecated and will be removed in a future release. To implement billing features for Google Play, use the Google Play Billing Library.
This documentation provides technical reference information for using the Google Play Billing AIDL.
Server Response Codes
The following table lists all of the server response codes that are sent from
Google Play to your application. Google Play sends the response code
synchronously as an integer mapped to the RESPONSE_CODE key in
the response Bundle. Your application must handle all of these
response codes.
Table 1. Summary of response codes for Google Play Billing AIDL calls.
| Response Code | Value | Description |
|---|---|---|
BILLING_RESPONSE_RESULT_OK |
0 | Success |
BILLING_RESPONSE_RESULT_USER_CANCELED |
1 | User pressed back or canceled a dialog |
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE |
2 | Network connection is down |
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE |
3 | The Google Play Billing AIDL version is not supported for the type requested |
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE |
4 | Requested product is not available for purchase |
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR |
5 | Invalid arguments provided to the API. This error can also indicate that the application was not correctly signed or properly set up for billing, or does not have the necessary permissions in its manifest. |
BILLING_RESPONSE_RESULT_ERROR |
6 | Fatal error during the API action |
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED |
7 | Failure to purchase since item is already owned |
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED |
8 | Failure to consume since item is not owned |
Google Play Billing AIDL Reference - Support
This section describes methods for obtaining information about the types of billing support that are available for your app.
The isBillingSupported() method
This method indicates whether:
- The given AIDL version is supported for your app.
- Google Play supports billing in the user's country.
- Google Play's billing system is enabled in your app package.
- Your app can use the given type of item for billing purposes.
Table 2. isBillingSupported() parameters.
| Key | Type | Description |
|---|---|---|
apiVersion
|
int
|
The version number of the Google Play Billing AIDL that your app is using. |
packageName
|
String
|
The package name of the app that's calling this method. |
type
|
String
|
Value must be inapp for an in-app product or
subs for subscriptions.
|
This method is available in version 3 and later of the Google Play Billing AIDL.
The isBillingSupportedExtraParams() method
This method is identical to
isBillingSupported(), except
that you can pass in a fourth argument, a Bundle, that can
contain extra parameters.
Table 3. isBillingSupportedExtraParams()
parameters.
| Key | Type | Description |
|---|---|---|
apiVersion
|
int
|
The version number of the Google Play Billing AIDL that your app is using. |
packageName
|
String
|
The package name of the app that's calling this method. |
type
|
String
|
Value must be inapp for an in-app product or
subs for subscriptions.
|
extraParams
|
Bundle
|
A set of extra parameters that further specifies the type of Google Play's billing system that the app supports. This bundle can contain an optional key called |
This method is available in version 7 and later of the Google Play Billing AIDL.
Google Play Billing AIDL Reference - Details
The Google Play Billing AIDL is defined in the
IInAppBillingService.aidl file,
which is included with the Version 3
sample application.
The getSkuDetails() method
Use the getSkuDetails() method to obtain product details for a corresponding list
of product IDs.
Table 4. GetSkuDetails() parameters.
| Key | Type | Description |
|---|---|---|
apiVersion
|
int
|
The version number of the Google Play Billing AIDL that your app is using. |
packageName
|
String
|
The package name of the app that's calling this method. |
type
|
String
|
Type of the in-app items ("inapp" for one-time purchases and "subs" for subscriptions). |
skusBundle
|
Bundle
|
Bundle containing a StringArrayList of SKUs with key ITEM_ID_LIST.
|
If getSkuDetails() method is successful, Google Play sends a response
Bundle. The query results are stored in the Bundle within
a String ArrayList mapped to the DETAILS_LIST
key. Each String in the details list contains product details for a single
product in JSON format. The fields in the JSON string with the product details
are summarized in table 5.
Table 5. Description of JSON fields with product item details
returned from a getSkuDetails() request.
| Key | Description |
|---|---|
productId |
The product ID for the product. |
type |
Value must be inapp for an in-app product or
subs for subscriptions. |
price |
Formatted price of the item, including its currency sign. The price does not include tax. |
price_amount_micros |
Price in micro-units, where 1,000,000 micro-units equal one unit of the
currency. For example, if price is "€7.99",
price_amount_micros is "7990000". This value
represents the localized, rounded price for a particular currency. |
price_currency_code |
ISO 4217
currency code for price. For example, if price is
specified in British pounds sterling, price_currency_code is
"GBP". |
title |
Title of the product. |
description |
Description of the product. |
subscriptionPeriod |
Subscription period, specified in
ISO 8601 format.
For example, P1W equates to one week, P1M
equates to one month, P3M equates to three months,
P6M equates to six months, and P1Y equates to
one year.
Note: Returned only for subscriptions. |
freeTrialPeriod |
Trial period configured in Google Play Console, specified in
ISO 8601 format. For
example, P7D equates to seven days.
To learn more about free trial eligibility, see
In-app Subscriptions.
Note: Returned only for subscriptions which have a trial period configured. |
introductoryPrice |
Formatted introductory price of a subscription, including its currency
sign, such as €3.99. The price doesn't include tax.
Note: Returned only for subscriptions which have an introductory period configured. |
introductoryPriceAmountMicros |
Introductory price in micro-units. The currency is the same as
price_currency_code.
Note: Returned only for subscriptions which have an introductory period configured. |
introductoryPricePeriod |
The billing period of the introductory price, specified in
ISO 8601 format.
Note: Returned only for subscriptions which have an introductory period configured. |
introductoryPriceCycles |
The number of subscription billing periods for which the user will be given the introductory
price, such as 3.
Note: Returned only for subscriptions which have an introductory period configured. |
The getBuyIntent() method
This method returns a response code integer mapped to the
RESPONSE_CODE key, and a
PendingIntent to launch the purchase flow for the in-app
item mapped to the BUY_INTENT key, as described in Implementing Google Play
Billing. When it receives the PendingIntent, Google Play
sends a response Intent with the data for that purchase order.
The data that is returned in the response Intent is summarized
in table 6.
Note: Instead of using this method, we recommend that you
use getBuyIntentExtraParams(), which
provides additional functionality.
Table 6. Response data from a Google Play purchase request.
| Key | Description |
|---|---|
RESPONSE_CODE |
Value is 0 if the purchase was success, error otherwise.
|
INAPP_PURCHASE_DATA |
A String in JSON format that contains details about the purchase order. See table 7 for a description of the JSON fields. |
INAPP_DATA_SIGNATURE |
String containing the signature of the purchase data that was signed with the private key of the developer. The data signature uses the RSASSA-PKCS1-v1_5 scheme. |
Table 7 describes the JSON fields that are returned in the response data for a purchase order.
Table 7. Descriptions of the JSON fields for
INAPP_PURCHASE_DATA.
| Field | Description |
|---|---|
autoRenewing |
Indicates whether the subscription renews automatically. If
true, the subscription is active, and will
automatically renew on the next billing date. If false,
indicates that the user has canceled the subscription. The user has
access to subscription content until the next billing date and will
lose access at that time unless they re-enable automatic renewal
(or manually renew, as described in
Manual Renewal).
If you offer a
grace period, this value remains set to true for all
subscriptions, as long as the grace period has not lapsed. The next
billing date is extended dynamically every day until the end of the grace
period or until the user fixes their payment method.
|
orderId |
A unique order identifier for the transaction. This identifier corresponds to the Google payments order ID. |
packageName |
The application package from which the purchase originated. |
productId |
The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Google Play Console. |
purchaseTime |
The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970). |
purchaseState |
The purchase state of the order. It always returns 0 (purchased). |
developerPayload |
A developer-specified string that contains supplemental information
about an order. You can specify a value for this field when you make a
getBuyIntent request. |
purchaseToken |
A token that uniquely identifies a purchase for a given item and user pair. |
The consumePurchase() method
Consume purchase corresponding to the given purchase token. This will result in this item being
removed from all
subsequent responses to getPurchases() and allow
repurchase of items of the same sku.
Table 8. consumePurchase() parameters.
| Key | Type | Description |
|---|---|---|
apiVersion
|
int
|
The version number of the Google Play Billing AIDL that your app is using. |
packageName
|
String
|
The package name of the app that's calling this method. |
purchaseToken
|
String
|
Token in the purchase information JSON that identifies the purchase to be consumed. |
This method returns a RESULT_OK(0) of consumption succeeded, and appropriate response
codes on failures.
The getBuyIntentToReplaceSkus() method
This method is used to upgrade or downgrade a subscription purchase. The
method is similar to getBuyIntent(),
except that it takes a list with exactly one already-purchased SKU to be replaced
with the SKU being purchased. When the user completes the purchase, Google
Play swaps out the old SKU and credits the user with the unused value of
their subscription time on a pro-rated basis. Google Play applies this credit
to the new subscription, and does not begin billing the user for the new
subscription until after the credit is used up.
Note: Instead of using this method, we recommend that you
use getBuyIntentExtraParams(), which
provides additional functionality.
This method was added with version 5 of the Google Play Billing AIDL. To verify
that the method is reported, send an isBillingSupported AIDL
request.
Note: You can only use this method for
subscription purchases. If the passed type parameter is anything
other than "subs", the method returns
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR.
Furthermore, the passed SKUs may not include SKUs for seasonal subscriptions.
This method returns a response code integer mapped to the
RESPONSE_CODE key, and a
PendingIntent to launch the purchase flow for the in-app
subscription mapped to the BUY_INTENT key. When it receives the
PendingIntent, Google Play
sends a response Intent with the data for that purchase order.
The data that is returned in the response Intent is summarized
in table 9.
Table 9. Response data from a Google Play Billing AIDL Version 5 purchase request.
| Key | Description |
|---|---|
RESPONSE_CODE |
Value is 0 if the purchase succeeds. If the purchase fails,
contains an error code. |
INAPP_PURCHASE_DATA |
A String in JSON format that contains details about the purchase order. See table 6 for a description of the JSON fields. |
INAPP_DATA_SIGNATURE |
String containing the signature of the purchase data that the developer signed with their private key. The data signature uses the RSASSA-PKCS1-v1_5 scheme. |
The getBuyIntentExtraParams() method
This method begins a purchase request. The method is a variant of the getBuyIntent() method, and takes an additional
extraParams parameter. This parameter is a
Bundle of optional keys and values that affect the
operation of the method as shown in table 10.
Table 10. getBuyIntentExtraParams() extra
parameters.
| Key | Type | Description |
|---|---|---|
skusToReplace
|
List<String>
|
An optional list with exactly one SKU that the user is upgrading or downgrading from. Pass this field if the purchase is upgrading or downgrading existing subscription. The specified SKU is replaced with the SKU that the user is purchasing. Google Play replaces the specified SKU at the start of the next billing cycle. |
replaceSkusProration
|
boolean
|
Specifies whether the user should be credited for any unused subscription time on the SKUs they are upgrading or downgrading. If you set this field to true, Google Play swaps out the old SKUs and credits the user with the unused value of their subscription time on a pro-rated basis. Google Play applies this credit to the new subscription, and does not begin billing the user for the new subscription until after the credit is used up. If you set this field to false, the user does not receive credit for any unused subscription time, and the recurrence date does not change.
Default value is true. Ignored if you do not pass
|
accountId
|
String
|
Optional obfuscated string that is uniquely associated with the user's account in your app. If you pass this value, Google Play can use it to detect irregular activity, such as many devices making purchases on the same account in a short period of time. This field is similar to Do not use your Google Play Console developer ID or the user's Google ID for this field. In addition, this field should not contain the user's ID in cleartext. We recommend that you use a one-way hash to generate a string from the user's ID, and store the hashed string in this field. |
developerId
|
String
|
Optional obfuscated string that is uniquely associated with the user's account across all of
your apps. This field is similar to Do not use your Google Play Console developer ID or the user's Google ID for this field. In addition, this field should not contain the user's ID in cleartext. We recommend that you use a one-way hash to generate a string from the user's ID, and store the hashed string in this field. |
vr
|
boolean
|
Specifies whether the provided intent represents the beginning of a virtual reality (VR) purchase flow. Note: In order for this extra parameter to have an effect on your app, you must use the Google Play Billing AIDL Version 7, or a more recent API. |
This method is available in version 6 and later of the Google Play Billing AIDL.
The getPurchases() method
This method returns the current un-consumed products owned by the user,
including both purchased items and items acquired by redeeming a promo code.
Table 11 lists the response data that is returned in the
Bundle.
Table 11. Response data from a
getPurchases request.
| Key | Description |
|---|---|
RESPONSE_CODE |
Value is 0 if the request was successful, error
otherwise. |
INAPP_PURCHASE_ITEM_LIST |
StringArrayList containing the list of productIds of
purchases from this
app. |
INAPP_PURCHASE_DATA_LIST |
StringArrayList containing the details for purchases from
this app. See table 13 for the list of detailed information stored in each item in the
list. |
INAPP_DATA_SIGNATURE_LIST |
StringArrayList containing the signatures of purchases from
this app. |
INAPP_CONTINUATION_TOKEN |
String containing a continuation token to retrieve the next set of
in-app products owned by the user. This is only set by the Google Play
service if the number of products owned by the user is very large. When a
continuation token is present in the response, you must make another call
to getPurchases and pass in the continuation token that you
received. The subsequent getPurchases call returns more
purchases and possibly another continuation token. |
The getPurchaseHistory() method
This method returns the most recent purchase made by the user for each SKU,
even if that purchase is expired, canceled, or consumed. Table 12 lists the
response data that is returned in the Bundle:
Table 12. Response data from a getPurchaseHistory
request.
| Key | Description |
|---|---|
RESPONSE_CODE |
Value is 0 if the request was successful, error otherwise.
|
INAPP_PURCHASE_ITEM_LIST |
StringArrayList containing the list of productIds of
purchases from this app. |
INAPP_PURCHASE_DATA_LIST |
StringArrayList containing the details for recent purchases
from this app. See table 6 for the list of detailed information stored in each
INAPP_PURCHASE_DATA item in the list.
|
INAPP_DATA_SIGNATURE_LIST |
StringArrayList containing the signatures of purchases from
this app. |
INAPP_CONTINUATION_TOKEN |
String containing a continuation token to retrieve the next set of
in-app products owned by the user. This is only set by the Google Play
service if the number of products owned by the user is very large. When a
continuation token is present in the response, you must make another call
to getPurchases and pass in the continuation token that you
received. The subsequent getPurchases call returns more
purchases and possibly another continuation token. |
Table 13. Descriptions of the JSON fields for the purchase
history returned by getPurchaseHistory().
| Field | Description |
|---|---|
productId |
The item's product identifier. Every item has a product ID, which you must specify in the application's product list on the Google Play Console. |
purchaseTime |
The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970). |
developerPayload |
A developer-specified string that contains supplemental information
about an order. You can specify a value for this field when you make a
getBuyIntent request. |
purchaseToken |
A token that uniquely identifies a purchase for a given item and user pair. |
Note: The getPurchaseHistory() method has higher
overhead than getPurchases(), because
it requires a call to the Google Play server. You should use getPurchases() if you do not actually need the
user's purchase history.
This method is available in version 6 and later of the Google Play Billing AIDL.