Developers
This documentation provides technical reference information for using the In-app Billing Version 3 API.
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 In-app Billing Version 3 API 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 | Billing API 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 In-app Billing in Google Play, 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 |
API Reference
The In-app Billing Version 3 API is defined in the IInAppBillingService.aidl file, which is included with the Version 3
sample application.
The getSkuDetails() method
This method returns product details for a list of product IDs. In the
response Bundle sent by Google Play, the query results are stored in
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 2.
Table 2. 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. |
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 Purchasing an
Item. 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
3.
Table 3. Response data from an In-app Billing Version 3 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 4 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 4 describes the JSON fields that are returned in the response data for a purchase order.
Table 4. 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. If the order is a test
purchase made through the In-app Billing Sandbox, orderId is
blank. |
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 Developer Console. |
purchaseTime |
The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970). |
purchaseState |
The purchase state of the order. Possible values are 0
(purchased), 1 (canceled), or 2 (refunded). |
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 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 of already-purchased SKUs that are to be
replaced with the SKU being purchased. When the user completes the purchase,
Google Play cancels 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.
This method was added with version 5 of the in-app billing API. 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, as described in Purchasing an
Item. 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
5.
Table 5. Response data from an In-app Billing 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 4 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 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 5 lists the response data that is returned in the
Bundle.
Table 6. 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 4 for the list of detail 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. |