In this document

Related Samples

This documentation provides technical reference information for using the In-app Billing Version 2 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 these response codes asynchronously as
response_code extras in the com.android.vending.billing.RESPONSE_CODE
broadcast intent. Your application must handle all of these response codes.

Table 6. Summary of response
codes returned by Google Play.

Response Code

Value

Description

RESULT_OK

0

Indicates that the request was sent to the server successfully. When this code is returned in
response to a CHECK_BILLING_SUPPORTED request, indicates that billing is
supported.

RESULT_USER_CANCELED

1

Indicates that the user pressed the back button on the checkout page instead of buying the
item.

RESULT_SERVICE_UNAVAILABLE

2

Indicates that the network connection is down.

RESULT_BILLING_UNAVAILABLE

3

Indicates that In-app Billing is not available because the API_VERSION that you
specified is not recognized by the Google Play application or the user is ineligible for in-app
billing (for example, the user resides in a country that prohibits in-app purchases).

RESULT_ITEM_UNAVAILABLE

4

Indicates that Google Play cannot find the requested item in the application's product
list. This can happen if the product ID is misspelled in your REQUEST_PURCHASE
request or if an item is unpublished in the application's product list.

RESULT_DEVELOPER_ERROR

5

Indicates that an application is trying to make an In-app Billing request but the application
has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate
that an application is not properly signed, or that you sent a malformed request, such as a
request with missing Bundle keys or a request that uses an unrecognized request type.

RESULT_ERROR

6

Indicates an unexpected server error. For example, this error is triggered if you try to
purchase an item from yourself, which is not allowed by Google Wallet.

In-app billing Version 2 API reference

The following section describes the interface for Google Play's In-app Billing service. The
interface is defined in the IMarketBillingService.aidl file, which is included with the
In-app Billing sample
application.

The interface consists of a single request method sendBillingRequest(). This method
takes a single Bundle parameter. The Bundle parameter includes several key-value
pairs, which are summarized in table 7.

The product ID of the item you are making a billing request for. Every in-app item that you
sell using Google Play's In-app Billing service must have a unique product ID, which you
specify on the Google Play Developer Console.

NONCE

long

Any valid long value.

Required for GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS
requests.

A number used once. Your application must generate and send a nonce with each
GET_PURCHASE_INFORMATION and RESTORE_TRANSACTIONS request. The nonce is
returned with the PURCHASE_STATE_CHANGED broadcast intent, so you can use this value
to verify the integrity of transaction responses form Google Play.

NOTIFY_IDS

Array of long values

Any valid array of long values

Required for GET_PURCHASE_INFORMATION and CONFIRM_NOTIFICATIONS
requests.

An array of notification identifiers. A notification ID is sent to your application in an
IN_APP_NOTIFY broadcast intent every time a purchase changes state. You use the
notification to retrieve the details of the purchase state change.

DEVELOPER_PAYLOAD

String

Any valid String less than 256 characters long.

No

A developer-specified string that can be specified when you make a
REQUEST_PURCHASE request. This field is returned in the JSON string that contains
transaction information for an order. You can use this key to send supplemental information with
an order. For example, you can use this key to send index keys with an order, which is useful if
you are using a database to store purchase information. We recommend that you do not use this key
to send data or content.

The BILLING_REQUEST key can have the following values:

CHECK_BILLING_SUPPORTED

This request verifies that the Google Play application supports In-app Billing. You
usually send this request when your application first starts up. This request is useful if you
want to enable or disable certain UI features that are relevant only to In-app Billing.

REQUEST_PURCHASE

This request sends a purchase message to the Google Play application and is the foundation
of In-app Billing. You send this request when a user indicates that he or she wants to purchase
an item in your application. Google Play then handles the financial transaction by displaying
the checkout user interface.

GET_PURCHASE_INFORMATION

This request retrieves the details of a purchase state change. A purchase state change can
occur when a purchase request is billed successfully or when a user cancels a transaction during
checkout. It can also occur when a previous purchase is refunded. Google Play notifies your
application when a purchase changes state, so you only need to send this request when there is
transaction information to retrieve.

CONFIRM_NOTIFICATIONS

This request acknowledges that your application received the details of a purchase state
change. That is, this message confirms that you sent a GET_PURCHASE_INFORMATION
request for a given notification and that you received the purchase information for the
notification.

RESTORE_TRANSACTIONS

This request retrieves a user's transaction status for managed purchases (see Choosing a
Purchase Type for more information). You should send this message only when you need to
retrieve a user's transaction status, which is usually only when your application is reinstalled
or installed for the first time on a device.

Every In-app Billing request generates a synchronous response. The response is a Bundle and can include one or more of the following keys:

RESPONSE_CODE

This key provides status information and error information about a request.

PURCHASE_INTENT

This key provides a PendingIntent, which you use to launch the checkout
activity.

REQUEST_ID

This key provides you with a request identifier, which you can use to match asynchronous
responses with requests.

Some of these keys are not relevant to certain types of requests. Table 8 shows which keys are
returned for each request type.

Table 8. Description of Bundle keys that are returned with
each In-app Billing request type.

In-app billing broadcast intents

The following section describes the In-app Billing broadcast intents that are sent by the Google
Play application. These broadcast intents inform your application about In-app Billing actions
that have occurred. Your application must implement a BroadcastReceiver to
receive these broadcast intents, such as the BillingReceiver that's shown in the in-app
billing sample
application.

com.android.vending.billing.RESPONSE_CODE

This broadcast intent contains a Google Play response code, and is sent after you make an
In-app Billing request. A server response code can indicate that a billing request was successfully
sent to Google Play or it can indicate that some error occurred during a billing request. This
intent is not used to report any purchase state changes (such as refund or purchase information).
For more information about the response codes that are sent with this response, see Google Play Response Codes for In-app Billing. The sample application
assigns this broadcast intent to a constant named ACTION_RESPONSE_CODE.

Extras

request_id—a long representing a request ID. A request ID
identifies a specific billing request and is returned by Google Play at the time a request is
made.

com.android.vending.billing.IN_APP_NOTIFY

This response indicates that a purchase has changed state, which means a purchase succeeded, was
canceled, or was refunded. This response contains one or more notification IDs. Each notification ID
corresponds to a specific server-side message, and each messages contains information about one or
more transactions. After your application receives an IN_APP_NOTIFY broadcast intent,
you send a GET_PURCHASE_INFORMATION request with the notification IDs to retrieve the
message details. The sample application assigns this broadcast intent to a constant named
ACTION_NOTIFY.

Extras

notification_id—a String representing the notification ID for
a given purchase state change. Google Play notifies you when there is a purchase state change
and the notification includes a unique notification ID. To get the details of the purchase state
change, you send the notification ID with the GET_PURCHASE_INFORMATION request.

com.android.vending.billing.PURCHASE_STATE_CHANGED

This broadcast intent contains detailed information about one or more transactions. The
transaction information is contained in a JSON string. The JSON string is signed and the signature
is sent to your application along with the JSON string (unencrypted). To help ensure the security of
your In-app Billing messages, your application can verify the signature of this JSON string. The
sample application assigns this broadcast intent to a constant named
ACTION_PURCHASE_STATE_CHANGED.

Extras

inapp_signed_data—a String representing the signed JSON
string.

inapp_signature—a String representing the signature.

Note: Your application should map the broadcast intents and extras
to constants that are unique to your application. See the Consts.java file in the
sample application to see how this is done.

The fields in the JSON string are described in the following table (see table 9):

Table 9. Description of JSON fields that are returned with
a PURCHASE_STATE_CHANGED intent.

Field

Description

nonce

A number used once. Your application generates the nonce and sends it with the
GET_PURCHASE_INFORMATION request. Google Play sends the nonce back as part of the
JSON string so you can verify the integrity of the message.

notificationId

A unique identifier that is sent with an IN_APP_NOTIFY broadcast intent. Each
notificationId corresponds to a specify message that is waiting to be retrieved on
the Google Play server. Your application sends back the notificationId with the
GET_PURCHASE_INFORMATION message so Google Play can determine which messages you
are retrieving.

orderId

A unique order identifier for the transaction. This corresponds to the Google Wallet 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 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), 2
(refunded), or 3 (expired, for subscription purchases only).

purchaseToken

A token that uniquely identifies a subscription purchase for a given item and user pair.
You can use the token to specify the subscription when querying for subscription validity.

Supported only in In-app Billing API Version 2 and higher.

developerPayload

A developer-specified string that contains supplemental information about an order. You can
specify a value for this field when you make a REQUEST_PURCHASE request.

REST API for subscriptions

Google Play offers an HTTP-based API that you can use to remotely query the validity of a specific subscription at any time or cancel a subscription. The API is designed to be used from your backend servers as a way of securely managing subscriptions, as well as extending and integrating subscriptions with other services. See Purchase Status API for more information.