| page.title=In-app Billing Reference |
| parent.title=In-app Billing |
| parent.link=index.html |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#billing-codes">Server Response Codes for In-app Billing</a></li> |
| <li><a href="#billing-interface">In-app Billing Service Interface</a></li> |
| <li><a href="#billing-intents">In-app Billing Broadcast Intents</a></li> |
| <li><a href="#other-intents">Other Broadcast Intents</a></li> |
| <li><a href="#billing-versions">In-app Billing API Versions</a></li> |
| </ol> |
| <h2>Downloads</h2> |
| <ol> |
| <li><a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">Sample |
| Application</a></li> |
| </ol> |
| <h2>See also</h2> |
| <ol> |
| <li><a href="{@docRoot}google/play/billing/billing_overview.html">Overview of In-app |
| Billing</a></li> |
| <li><a href="{@docRoot}google/play/billing/billing_integrate.html">Implementing In-app |
| Billing</a></li> |
| <li><a href="{@docRoot}google/play/billing/billing_best_practices.html">Security and |
| Design</a></li> |
| <li><a href="{@docRoot}google/play/billing/billing_testing.html">Testing In-app |
| Billing</a></li> |
| <li><a href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app |
| Billing</a></li> |
| </ol> |
| </div> |
| </div> |
| |
| <p>The following document provides technical reference information for the following:</p> |
| |
| <ul> |
| <li><a href="#billing-codes">Google Play Server Response Codes for In-app Billing</a></li> |
| <li><a href="#billing-interface">In-app Billing Interface Parameters</a></li> |
| <li><a href="#billing-intents">In-app Billing Broadcast Intents</a></li> |
| <li><a href="#other-intents">Other Intents</a></li> |
| <li><a href="#billing-versions">In-app Billing API Versions</a></li> |
| </ul> |
| |
| <h2 id="billing-codes">Server Response Codes for In-app Billing</h2> |
| |
| <p>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 |
| <code>response_code</code> extras in the <code>com.android.vending.billing.RESPONSE_CODE</code> |
| broadcast intent. Your application must handle all of these response codes.</p> |
| |
| <p class="table-caption" id="response-codes-table"><strong>Table 1.</strong> Summary of response |
| codes returned by Google Play.</p> |
| |
| <table> |
| |
| <tr> |
| <th>Response Code</th> |
| <th>Value</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td><code>RESULT_OK</code></td> |
| <td>0</td> |
| <td>Indicates that the request was sent to the server successfully. When this code is returned in |
| response to a <code>CHECK_BILLING_SUPPORTED</code> request, indicates that billing is |
| supported.</td> |
| </tr> |
| <tr> |
| <td><code>RESULT_USER_CANCELED</code></td> |
| <td>1</td> |
| <td>Indicates that the user pressed the back button on the checkout page instead of buying the |
| item.</td> |
| </tr> |
| <tr> |
| <td><code>RESULT_SERVICE_UNAVAILABLE</code></td> |
| <td>2</td> |
| <td>Indicates that the network connection is down.</td> |
| </tr> |
| <tr> |
| <td><code>RESULT_BILLING_UNAVAILABLE</code></td> |
| <td>3</td> |
| <td>Indicates that in-app billing is not available because the <code>API_VERSION</code> 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).</td> |
| </tr> |
| <tr> |
| <td><code>RESULT_ITEM_UNAVAILABLE</code></td> |
| <td>4</td> |
| <td>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 <code>REQUEST_PURCHASE</code> |
| request or if an item is unpublished in the application's product list.</td> |
| </tr> |
| <tr> |
| <td><code>RESULT_DEVELOPER_ERROR</code></td> |
| <td>5</td> |
| <td>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.</td> |
| </tr> |
| <tr> |
| <td><code>RESULT_ERROR</code></td> |
| <td>6</td> |
| <td>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.</td> |
| </tr> |
| </table> |
| |
| <h2 id="billing-interface">In-app Billing Service Interface</h2> |
| |
| <p>The following section describes the interface for Google Play's in-app billing service. The |
| interface is defined in the <code>IMarketBillingService.aidl</code> file, which is included with the |
| in-app billing <a |
| href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">sample |
| application</a>.</p> |
| <p>The interface consists of a single request method <code>sendBillingRequest()</code>. This method |
| takes a single {@link android.os.Bundle} parameter. The Bundle parameter includes several key-value |
| pairs, which are summarized in table 2.</p> |
| |
| <p class="table-caption"><strong>Table 2.</strong> Description of Bundle keys passed in a |
| <code>sendBillingRequest()</code> request.</p> |
| |
| <table> |
| |
| <tr> |
| <th>Key</th> |
| <th>Type</th> |
| <th>Possible Values</th> |
| <th>Required?</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td><code>BILLING_REQUEST</code></td> |
| <td><code>String</code></td> |
| <td><code>CHECK_BILLING_SUPPORTED</code>, <code>REQUEST_PURCHASE</code>, |
| <code>GET_PURCHASE_INFORMATION</code>, <code>CONFIRM_NOTIFICATIONS</code>, or |
| <code>RESTORE_TRANSACTIONS</code></td> |
| <td>Yes</td> |
| <td>The type of billing request you are making with the <code>sendBillingRequest()</code> request. |
| The possible values are discussed more below this table.</td> |
| </tr> |
| <tr> |
| <td><code>API_VERSION</code></td> |
| <td><code>int</code></td> |
| <td> <ul> |
| <li><code>"2"</code> [<a href="#version_2">details</a>]</li> |
| <li><code>"1"</code> [<a href="#version_1">details</a>]</li> |
| </ul></td> |
| <td>Yes</td> |
| <td>The version of Google Play's in-app billing service you want to use. The current version is |
| 2.</td> |
| </tr> |
| <tr> |
| <td><code>PACKAGE_NAME</code></td> |
| <td><code>String</code></td> |
| <td>A valid package name.</td> |
| <td>Yes</td> |
| <td>The name of the application that is making the request.</td> |
| </tr> |
| <tr> |
| <td><code>ITEM_ID</code></td> |
| <td><code>String</code></td> |
| <td>Any valid product identifier.</td> |
| <td>Required for <code>REQUEST_PURCHASE</code> requests.</td> |
| <td>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 publisher site.</td> |
| </tr> |
| <tr> |
| <td><code>NONCE</code></td> |
| <td><code>long</code></td> |
| <td>Any valid <code>long</code> value.</td> |
| <td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> |
| requests.</td> |
| <td>A number used once. Your application must generate and send a nonce with each |
| <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is |
| returned with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent, so you can use this value |
| to verify the integrity of transaction responses form Google Play.</td> |
| </tr> |
| <tr> |
| <td><code>NOTIFY_IDS</code></td> |
| <td>Array of <code>long</code> values</td> |
| <td>Any valid array of <code>long</code> values</td> |
| <td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>CONFIRM_NOTIFICATIONS</code> |
| requests.</td> |
| <td>An array of notification identifiers. A notification ID is sent to your application in an |
| <code>IN_APP_NOTIFY</code> broadcast intent every time a purchase changes state. You use the |
| notification to retrieve the details of the purchase state change.</td> |
| </tr> |
| <tr> |
| <td><code>DEVELOPER_PAYLOAD</code></td> |
| <td><code>String</code></td> |
| <td>Any valid <code>String</code> less than 256 characters long.</td> |
| <td>No</td> |
| <td>A developer-specified string that can be specified when you make a |
| <code>REQUEST_PURCHASE</code> 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.</td> |
| </tr> |
| </table> |
| |
| <p>The <code>BILLING_REQUEST</code> key can have the following values:</p> |
| |
| <ul> |
| <li><code>CHECK_BILLING_SUPPORTED</code> |
| <p>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.</p> |
| </li> |
| <li><code>REQUEST_PURCHASE</code> |
| <p>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.</p> |
| </li> |
| <li><code>GET_PURCHASE_INFORMATION</code> |
| <p>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.</p> |
| </li> |
| <li><code>CONFIRM_NOTIFICATIONS</code> |
| <p>This request acknowledges that your application received the details of a purchase state |
| change. That is, this message confirms that you sent a <code>GET_PURCHASE_INFORMATION</code> |
| request for a given notification and that you received the purchase information for the |
| notification.</p> |
| </li> |
| <li><code>RESTORE_TRANSACTIONS</code> |
| <p>This request retrieves a user's transaction status for managed purchases (see <a |
| href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">Choosing a |
| Purchase Type</a> 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.</p> |
| </li> |
| </ul> |
| |
| <p>Every in-app billing request generates a synchronous response. The response is a {@link |
| android.os.Bundle} and can include one or more of the following keys:</p> |
| |
| <ul> |
| <li><code>RESPONSE_CODE</code> |
| <p>This key provides status information and error information about a request.</p> |
| </li> |
| <li><code>PURCHASE_INTENT</code> |
| <p>This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout |
| activity.</p> |
| </li> |
| <li><code>REQUEST_ID</code> |
| <p>This key provides you with a request identifier, which you can use to match asynchronous |
| responses with requests.</p> |
| </li> |
| </ul> |
| |
| <p>Some of these keys are not relevant to certain types of requests. Table 3 shows which keys are |
| returned for each request type.</p> |
| |
| <p class="table-caption"><strong>Table 3.</strong> Description of Bundle keys that are returned with |
| each in-app billing request type.</p> |
| |
| <table> |
| |
| <tr> |
| <th>Request Type</th> |
| <th>Keys Returned</th> |
| <th>Possible Response Codes</th> |
| </tr> |
| <tr> |
| <td><code>CHECK_BILLING_SUPPORTED</code></td> |
| <td><code>RESPONSE_CODE</code></td> |
| <td><code>RESULT_OK</code>, <code>RESULT_BILLING_UNAVAILABLE</code>, <code>RESULT_ERROR</code>, |
| <code>RESULT_DEVELOPER_ERROR</code></td> |
| </tr> |
| <tr> |
| <td><code>REQUEST_PURCHASE</code></td> |
| <td><code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, <code>REQUEST_ID</code></td> |
| <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td> |
| </tr> |
| <tr> |
| <td><code>GET_PURCHASE_INFORMATION</code></td> |
| <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td> |
| <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td> |
| </tr> |
| <tr> |
| <td><code>CONFIRM_NOTIFICATIONS</code></td> |
| <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td> |
| <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td> |
| </tr> |
| <tr> |
| <td><code>RESTORE_TRANSACTIONS</code></td> |
| <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td> |
| <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td> |
| </tr> |
| </table> |
| |
| <h2 id="billing-intents">In-app Billing Broadcast Intents</h2> |
| |
| <p>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 {@link android.content.BroadcastReceiver} to |
| receive these broadcast intents, such as the <code>BillingReceiver</code> that's shown in the in-app |
| billing <a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">sample |
| application</a>.</p> |
| |
| <h4>com.android.vending.billing.RESPONSE_CODE</h4> |
| |
| <p>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 <a |
| href="#billing-codes">Google Play Response Codes for In-app Billing</a>. The sample application |
| assigns this broadcast intent to a constant named <code>ACTION_RESPONSE_CODE</code>.</p> |
| |
| <h5>Extras</h5> |
| |
| <ul type="none"> |
| <li><code>request_id</code>—a <code>long</code> 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.</li> |
| <li><code>response_code</code>—an <code>int</code> representing the Google Play server |
| response code.</li> |
| </ul> |
| |
| <h4>com.android.vending.billing.IN_APP_NOTIFY</h4> |
| |
| <p>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 <code>IN_APP_NOTIFY</code> broadcast intent, |
| you send a <code>GET_PURCHASE_INFORMATION</code> request with the notification IDs to retrieve the |
| message details. The sample application assigns this broadcast intent to a constant named |
| <code>ACTION_NOTIFY</code>.</p> |
| |
| <h5>Extras</h5> |
| |
| <ul type="none"> |
| <li><code>notification_id</code>—a <code>String</code> 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 <code>GET_PURCHASE_INFORMATION</code> request.</li> |
| </ul> |
| |
| <h4>com.android.vending.billing.PURCHASE_STATE_CHANGED</h4> |
| |
| <p>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 |
| <code>ACTION_PURCHASE_STATE_CHANGED</code>.</p> |
| |
| <h5>Extras</h5> |
| |
| <ul type="none"> |
| <li><code>inapp_signed_data</code>—a <code>String</code> representing the signed JSON |
| string.</li> |
| <li><code>inapp_signature</code>—a <code>String</code> representing the signature.</li> |
| </ul> |
| |
| <p class="note"><strong>Note:</strong> Your application should map the broadcast intents and extras |
| to constants that are unique to your application. See the <code>Consts.java</code> file in the |
| sample application to see how this is done.</p> |
| |
| <p>The fields in the JSON string are described in the following table (see table 4):</p> |
| |
| <p class="table-caption"><strong>Table 4.</strong> Description of JSON fields that are returned with |
| a <code>PURCHASE_STATE_CHANGED</code> intent.</p> |
| |
| <table> |
| |
| <tr> |
| <th>Field</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>nonce</td> |
| <td>A number used once. Your application generates the nonce and sends it with the |
| <code>GET_PURCHASE_INFORMATION</code> request. Google Play sends the nonce back as part of the |
| JSON string so you can verify the integrity of the message.</td> |
| </tr> |
| <tr> |
| <td>notificationId</td> |
| <td>A unique identifier that is sent with an <code>IN_APP_NOTIFY</code> broadcast intent. Each |
| <code>notificationId</code> corresponds to a specify message that is waiting to be retrieved on |
| the Google Play server. Your application sends back the <code>notificationId</code> with the |
| <code>GET_PURCHASE_INFORMATION</code> message so Google Play can determine which messages you |
| are retrieving.</td> |
| </tr> |
| <tr> |
| <td>orderId</td> |
| <td>A unique order identifier for the transaction. This corresponds to the transaction's Merchant |
| Order Number. For transactions dated previous to 5 December 2012, the orderID correcponds to the transaction's |
| Google Order Number. For more information, see <a href="{@docRoot}google/play/billing/billing_admin.html#orderId">Working |
| with order numbers</a>.</td> |
| </tr> |
| <tr> |
| <td>packageName</td> |
| <td>The application package from which the purchase originated.</td> |
| </tr> |
| <tr> |
| <td>productId</td> |
| <td>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 publisher site.</td> |
| </tr> |
| <tr> |
| <td>purchaseTime</td> |
| <td>The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).</td> |
| </tr> |
| |
| <tr> |
| <td>purchaseState</td> |
| <td>The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), 2 |
| (refunded), or 3 (expired, for subscription purchases only).</td> |
| </tr> |
| <tr> |
| <td>purchaseToken</td> |
| <td>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. |
| |
| <p><br><em>Supported only in In-app Billing API version 2 and higher.</em></p></td> |
| </tr> |
| <tr> |
| <td>developerPayload</td> |
| <td>A developer-specified string that contains supplemental information about an order. You can |
| specify a value for this field when you make a <code>REQUEST_PURCHASE</code> request.</td> |
| </tr> |
| </table> |
| |
| <!--<h2 id="other-intents">Other Intents</h2> |
| |
| <p>The following Intents related to In-app Billing may be useful in your |
| implemention. </p> --> |
| |
| <h2 id="http-api">HTTP API for verification and cancelation</h2> |
| |
| <p>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 <a |
| href="{@docRoot}google/play/billing/billing_subscriptions.html#play-dev-api"> |
| Google Play Android Developer API</a> for more information.</p> |
| |
| <h2 id="billing-versions">In-app Billing API Versions</h2> |
| |
| <p>The In-app Billing API is versioned, with each version offering |
| additional features to your app. At run time, your app can query the Google Play app to determine |
| what version of the API it supports and what features are available. Typically, the Google Play app |
| will be updated and will support the latest version of the API. |
| |
| <p>The sections below list the supported versions of the In-app Billing API. |
| Versions are specified in the <code>API_VERSION</code> key of the Bundle object |
| passed in the <code>sendBillingRequest()</code>, which is defined in the defined |
| in the <code>IMarketBillingService.aidl</code> file, which is included with the |
| in-app billing <a |
| href="{@docRoot}google/play/billing/billing_integrate.html#billing-download"> |
| sample application</a>. For more information, see <a |
| href="#billing-interface">In-app Billing Service Interface</a>.</p> |
| <h3 id="version_2">In-app Billing version 2</h3> |
| |
| <p><em>May 2012</em></p> |
| |
| <ul> |
| <li>Adds support for subscriptions. |
| <ul> |
| <li>Adds a new supported string value, "2", for the <code>API_VERSION</code> key |
| of the Bundle object passed in the <code>sendBillingRequest()</code>.</li> |
| <li>Adds a new JSON field, <code>purchaseToken</code>, to the |
| <code>orders</code> list returned in a <code>PURCHASE_STATE_CHANGED</code> |
| intent. </li> |
| <li>Adds a new <code>purchaseState</code> value, <code>3</code> (expired), to the |
| <code>orders</code> list returned in a <code>PURCHASE_STATE_CHANGED</code> |
| intent. The value indicates that a subscription has expired and is no longer valid.</li> |
| <li>Requires Google Play (Play Store) version 3.5 or higher.</li> |
| </ul> |
| |
| <h3 id="version_1">In-app Billing version 1</h3> |
| |
| <p><em>March 2011</em></p> |
| |
| <ul> |
| <li>Initial release.</li> |
| <li>Requires Google Play/Android Market 2.3.4 or higher.</li> |
| </ul> |
| |