- Home Startseite ホーム 主页 首頁
- SDK
- Dev Guide Handbuch Guía Guide Guida 開発ガイド 开发人员指南 開發指南
- Reference Referenz Referencia Référence Riferimento リファレンス 参考 參考資料
- Resources
- Videos ビデオ
- Blog ブログ 博客 網誌

Android.com

In-app Billing >

# In-app Billing Reference

## In this document

1. Server Response Codes for In-app Billing
2. In-app Billing Service Interface
3. In-app Billing Broadcast Intents

## Downloads

1. Sample Application

## See also

1. Overview of In-app Billing
2. Implementing In-app Billing
3. Security and Design
4. Testing In-app Billing
5. Administering In-app Billing

The following document provides technical reference information for the following:

- Android Market Server Response Codes for In-app Billing
- In-app Billing Interface Parameters
- In-app Billing Broadcast Intents

## Android Market Server Response Codes for In-app Billing

The following table lists all of the server response codes that are sent from Android Market to your application. Android Market 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 1. Summary of response codes returned by Android Market.

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 Android Market 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 Android Market 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 Checkout.

## In-app Billing Service Interface

The following section describes the interface for Android Market'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 2.

Table 2. Description of Bundle keys passed in a `sendBillingRequest()` request.

Key | Type | Possible Values | Required? | Description
--- | --- | --- | --- | ---
`BILLING_REQUEST` | `String` | `CHECK_BILLING_SUPPORTED`, `REQUEST_PURCHASE`, `GET_PURCHASE_INFORMATION`, `CONFIRM_NOTIFICATIONS`, or `RESTORE_TRANSACTIONS` | Yes | The type of billing request you are making with the `sendBillingRequest()` request. The possible values are discussed more below this table.
`API_VERSION` | `int` | 1 | Yes | The version of Android Market's in-app billing service you are using. The current version is 1.
`PACKAGE_NAME` | `String` | A valid package name. | Yes | The name of the application that is making the request.
`ITEM_ID` | `String` | Any valid product identifier. | Required for `REQUEST_PURCHASE` requests. | The product ID of the item you are making a billing request for. Every in-app item that you sell using Android Market's in-app billing service must have a unique product ID, which you specify on the Android Market publisher site.
`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 Android Market.
`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 Android Market 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 Android Market 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. Android Market 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. Android Market 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 3 shows which keys are returned for each request type.

Table 3. Description of Bundle keys that are returned with each in-app billing request type.

Request Type | Keys Returned | Possible Response Codes
--- | --- | ---
`CHECK_BILLING_SUPPORTED` | `RESPONSE_CODE` | `RESULT_OK`, `RESULT_BILLING_UNAVAILABLE`, `RESULT_ERROR`, `RESULT_DEVELOPER_ERROR`
`REQUEST_PURCHASE` | `RESPONSE_CODE`, `PURCHASE_INTENT`, `REQUEST_ID` | `RESULT_OK`, `RESULT_ERROR`, `RESULT_DEVELOPER_ERROR`
`GET_PURCHASE_INFORMATION` | `RESPONSE_CODE`, `REQUEST_ID` | `RESULT_OK`, `RESULT_ERROR`, `RESULT_DEVELOPER_ERROR`
`CONFIRM_NOTIFICATIONS` | `RESPONSE_CODE`, `REQUEST_ID` | `RESULT_OK`, `RESULT_ERROR`, `RESULT_DEVELOPER_ERROR`
`RESTORE_TRANSACTIONS` | `RESPONSE_CODE`, `REQUEST_ID` | `RESULT_OK`, `RESULT_ERROR`, `RESULT_DEVELOPER_ERROR`

## In-app Billing Broadcast Intents

The following section describes the in-app billing broadcast intents that are sent by the Android Market 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 an Android Market 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 Android Market 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 Android Market 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 Android Market at the time a request is made.
- `response_code`—an `int` representing the Android Market server response code.

#### 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. Android Market 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 4):

Table 4. 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. Android Market 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 Android Market server. Your application sends back the `notificationId` with the `GET_PURCHASE_INFORMATION` message so Android Market can determine which messages you are retrieving.
orderId | A unique order identifier for the transaction. This corresponds to the Google Checkout 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 Android Market publisher site.
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 `REQUEST_PURCHASE` request.

↑ Go to top

← Back to In-app Billing