1 page.title=In-app Billing Reference <span style="font-size:16px;">(IAB Version 2)</span> 2 excludeFromSuggestions=true 3 @jd:body 4 5 <p class="caution" style= 6 "background-color:#fffdeb;width:100%;margin-bottom:1em;padding:.5em;"> 7 The <strong>In-app Billing Version 2 API</strong> has been deprecated in 8 favor of the Version 3 API. If your app is using In-app Billing, please 9 <strong>make sure that it is using the Version 3 API</strong>. If your app is 10 still using the Version 2 API, you must <strong>migrate to the Version 3 API 11 as soon as possible</strong>.<br> 12 <br> 13 We plan to turn off the In-app Billing Version 2 service on <strong>January 14 27, 2015</strong>, after which time users will <strong>no longer be able to 15 purchase in-app items and subscriptions through the Version 2 API</strong>. 16 We strongly encourage and recommend you migrate your apps to use Version 3 17 API by November 2014, to provide ample time for users to update their apps to 18 the new version.<br> 19 <br> 20 For more information, please see the <a href= 21 "http://support.google.com/googleplay/android-developer/answer/6090268">Help Center 22 article</a>. For common questions about transitioning your implementation to 23 In-app Billing Version 3, please see <a href= 24 "{@docRoot}google/play/billing/billing_overview.html#migration">Migration 25 Considerations</a>. 26 </p> 27 <div id="qv-wrapper" style="margin-top:0;"> 28 <div id="qv"> 29 <h2>In this document</h2> 30 <ol> 31 <li><a href="#billing-codes">Server Response Codes</a></li> 32 <li><a href="#billing-interface">API Reference</a></li> 33 <li><a href="#billing-intents">Broadcast Intents</a></li> 34 <li><a href="#http-api">REST API for Subscriptions</a></li> 35 </ol> 36 37 <h2>Related Samples</h2> 38 <ol> 39 <li><a href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">Sample 40 Application (V2)</a></li> 41 </ol> 42 43 </div> 44 </div> 45 <p>This documentation provides technical reference information for using the In-app Billing Version 2 API. </p> 46 47 <h2 id="billing-codes">Server Response Codes</h2> 48 <p>The following table lists all of the server response codes that are sent from Google Play to 49 your application. Google Play sends these response codes asynchronously as 50 <code>response_code</code> extras in the <code>com.android.vending.billing.RESPONSE_CODE</code> 51 broadcast intent. Your application must handle all of these response codes.</p> 52 53 <p class="table-caption" id="response-codes-table"><strong>Table 6.</strong> Summary of response 54 codes returned by Google Play.</p> 55 56 <table> 57 <tr> 58 <th>Response Code</th> 59 <th>Value</th> 60 <th>Description</th> 61 </tr> 62 <tr> 63 <td><code>RESULT_OK</code></td> 64 <td>0</td> 65 <td>Indicates that the request was sent to the server successfully. When this code is returned in 66 response to a <code>CHECK_BILLING_SUPPORTED</code> request, indicates that billing is 67 supported.</td> 68 </tr> 69 <tr> 70 <td><code>RESULT_USER_CANCELED</code></td> 71 <td>1</td> 72 <td>Indicates that the user pressed the back button on the checkout page instead of buying the 73 item.</td> 74 </tr> 75 <tr> 76 <td><code>RESULT_SERVICE_UNAVAILABLE</code></td> 77 <td>2</td> 78 <td>Indicates that the network connection is down.</td> 79 </tr> 80 <tr> 81 <td><code>RESULT_BILLING_UNAVAILABLE</code></td> 82 <td>3</td> 83 <td>Indicates that In-app Billing is not available because the <code>API_VERSION</code> that you 84 specified is not recognized by the Google Play application or the user is ineligible for in-app 85 billing (for example, the user resides in a country that prohibits in-app purchases).</td> 86 </tr> 87 <tr> 88 <td><code>RESULT_ITEM_UNAVAILABLE</code></td> 89 <td>4</td> 90 <td>Indicates that Google Play cannot find the requested item in the application's product 91 list. This can happen if the product ID is misspelled in your <code>REQUEST_PURCHASE</code> 92 request or if an item is unpublished in the application's product list.</td> 93 </tr> 94 <tr> 95 <td><code>RESULT_DEVELOPER_ERROR</code></td> 96 <td>5</td> 97 <td>Indicates that an application is trying to make an In-app Billing request but the application 98 has not declared the com.android.vending.BILLING permission in its manifest. Can also indicate 99 that an application is not properly signed, or that you sent a malformed request, such as a 100 request with missing Bundle keys or a request that uses an unrecognized request type.</td> 101 </tr> 102 <tr> 103 <td><code>RESULT_ERROR</code></td> 104 <td>6</td> 105 <td>Indicates an unexpected server error. For example, this error is triggered if you try to 106 purchase an item from yourself, which is not allowed by Google Wallet.</td> 107 </tr> 108 </table> 109 </p> 110 111 <h3 id="billing-interface">In-app billing Version 2 API reference</h3> 112 113 <p>The following section describes the interface for Google Play's In-app Billing service. The 114 interface is defined in the <code>IMarketBillingService.aidl</code> file, which is included with the 115 In-app Billing <a 116 href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">sample 117 application</a>.</p> 118 <p>The interface consists of a single request method <code>sendBillingRequest()</code>. This method 119 takes a single {@link android.os.Bundle} parameter. The Bundle parameter includes several key-value 120 pairs, which are summarized in table 7.</p> 121 122 <p class="table-caption"><strong>Table 7.</strong> Description of Bundle keys passed in a 123 <code>sendBillingRequest()</code> request.</p> 124 125 <table> 126 127 <tr> 128 <th>Key</th> 129 <th>Type</th> 130 <th>Possible Values</th> 131 <th>Required?</th> 132 <th>Description</th> 133 </tr> 134 <tr> 135 <td><code>BILLING_REQUEST</code></td> 136 <td><code>String</code></td> 137 <td><code>CHECK_BILLING_SUPPORTED</code>, <code>REQUEST_PURCHASE</code>, 138 <code>GET_PURCHASE_INFORMATION</code>, <code>CONFIRM_NOTIFICATIONS</code>, or 139 <code>RESTORE_TRANSACTIONS</code></td> 140 <td>Yes</td> 141 <td>The type of billing request you are making with the <code>sendBillingRequest()</code> request. 142 The possible values are discussed more below this table.</td> 143 </tr> 144 <tr> 145 <td><code>API_VERSION</code></td> 146 <td><code>int</code></td> 147 <td> <ul> 148 <li><code>"2"</code> [<a href="#version_2">details</a>]</li> 149 <li><code>"1"</code> [<a href="#version_1">details</a>]</li> 150 </ul></td> 151 <td>Yes</td> 152 <td>The version of Google Play's In-app Billing service you want to use.</td> 153 </tr> 154 <tr> 155 <td><code>PACKAGE_NAME</code></td> 156 <td><code>String</code></td> 157 <td>A valid package name.</td> 158 <td>Yes</td> 159 <td>The name of the application that is making the request.</td> 160 </tr> 161 <tr> 162 <td><code>ITEM_ID</code></td> 163 <td><code>String</code></td> 164 <td>Any valid product identifier.</td> 165 <td>Required for <code>REQUEST_PURCHASE</code> requests.</td> 166 <td>The product ID of the item you are making a billing request for. Every in-app item that you 167 sell using Google Play's In-app Billing service must have a unique product ID, which you 168 specify on the Google Play Developer Console.</td> 169 </tr> 170 <tr> 171 <td><code>NONCE</code></td> 172 <td><code>long</code></td> 173 <td>Any valid <code>long</code> value.</td> 174 <td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> 175 requests.</td> 176 <td>A number used once. Your application must generate and send a nonce with each 177 <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is 178 returned with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent, so you can use this value 179 to verify the integrity of transaction responses form Google Play.</td> 180 </tr> 181 <tr> 182 <td><code>NOTIFY_IDS</code></td> 183 <td>Array of <code>long</code> values</td> 184 <td>Any valid array of <code>long</code> values</td> 185 <td>Required for <code>GET_PURCHASE_INFORMATION</code> and <code>CONFIRM_NOTIFICATIONS</code> 186 requests.</td> 187 <td>An array of notification identifiers. A notification ID is sent to your application in an 188 <code>IN_APP_NOTIFY</code> broadcast intent every time a purchase changes state. You use the 189 notification to retrieve the details of the purchase state change.</td> 190 </tr> 191 <tr> 192 <td><code>DEVELOPER_PAYLOAD</code></td> 193 <td><code>String</code></td> 194 <td>Any valid <code>String</code> less than 256 characters long.</td> 195 <td>No</td> 196 <td>A developer-specified string that can be specified when you make a 197 <code>REQUEST_PURCHASE</code> request. This field is returned in the JSON string that contains 198 transaction information for an order. You can use this key to send supplemental information with 199 an order. For example, you can use this key to send index keys with an order, which is useful if 200 you are using a database to store purchase information. We recommend that you do not use this key 201 to send data or content.</td> 202 </tr> 203 </table> 204 205 <p>The <code>BILLING_REQUEST</code> key can have the following values:</p> 206 207 <ul> 208 <li><code>CHECK_BILLING_SUPPORTED</code> 209 <p>This request verifies that the Google Play application supports In-app Billing. You 210 usually send this request when your application first starts up. This request is useful if you 211 want to enable or disable certain UI features that are relevant only to In-app Billing.</p> 212 </li> 213 <li><code>REQUEST_PURCHASE</code> 214 <p>This request sends a purchase message to the Google Play application and is the foundation 215 of In-app Billing. You send this request when a user indicates that he or she wants to purchase 216 an item in your application. Google Play then handles the financial transaction by displaying 217 the checkout user interface.</p> 218 </li> 219 <li><code>GET_PURCHASE_INFORMATION</code> 220 <p>This request retrieves the details of a purchase state change. A purchase state change can 221 occur when a purchase request is billed successfully or when a user cancels a transaction during 222 checkout. It can also occur when a previous purchase is refunded. Google Play notifies your 223 application when a purchase changes state, so you only need to send this request when there is 224 transaction information to retrieve.</p> 225 </li> 226 <li><code>CONFIRM_NOTIFICATIONS</code> 227 <p>This request acknowledges that your application received the details of a purchase state 228 change. That is, this message confirms that you sent a <code>GET_PURCHASE_INFORMATION</code> 229 request for a given notification and that you received the purchase information for the 230 notification.</p> 231 </li> 232 <li><code>RESTORE_TRANSACTIONS</code> 233 <p>This request retrieves a user's transaction status for managed purchases (see <a 234 href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">Choosing a 235 Purchase Type</a> for more information). You should send this message only when you need to 236 retrieve a user's transaction status, which is usually only when your application is reinstalled 237 or installed for the first time on a device.</p> 238 </li> 239 </ul> 240 241 <p>Every In-app Billing request generates a synchronous response. The response is a {@link 242 android.os.Bundle} and can include one or more of the following keys:</p> 243 244 <ul> 245 <li><code>RESPONSE_CODE</code> 246 <p>This key provides status information and error information about a request.</p> 247 </li> 248 <li><code>PURCHASE_INTENT</code> 249 <p>This key provides a {@link android.app.PendingIntent}, which you use to launch the checkout 250 activity.</p> 251 </li> 252 <li><code>REQUEST_ID</code> 253 <p>This key provides you with a request identifier, which you can use to match asynchronous 254 responses with requests.</p> 255 </li> 256 </ul> 257 258 <p>Some of these keys are not relevant to certain types of requests. Table 8 shows which keys are 259 returned for each request type.</p> 260 261 <p class="table-caption"><strong>Table 8.</strong> Description of Bundle keys that are returned with 262 each In-app Billing request type.</p> 263 264 <table> 265 266 <tr> 267 <th>Request Type</th> 268 <th>Keys Returned</th> 269 <th>Possible Response Codes</th> 270 </tr> 271 <tr> 272 <td><code>CHECK_BILLING_SUPPORTED</code></td> 273 <td><code>RESPONSE_CODE</code></td> 274 <td><code>RESULT_OK</code>, <code>RESULT_BILLING_UNAVAILABLE</code>, <code>RESULT_ERROR</code>, 275 <code>RESULT_DEVELOPER_ERROR</code></td> 276 </tr> 277 <tr> 278 <td><code>REQUEST_PURCHASE</code></td> 279 <td><code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, <code>REQUEST_ID</code></td> 280 <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td> 281 </tr> 282 <tr> 283 <td><code>GET_PURCHASE_INFORMATION</code></td> 284 <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td> 285 <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td> 286 </tr> 287 <tr> 288 <td><code>CONFIRM_NOTIFICATIONS</code></td> 289 <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td> 290 <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td> 291 </tr> 292 <tr> 293 <td><code>RESTORE_TRANSACTIONS</code></td> 294 <td><code>RESPONSE_CODE</code>, <code>REQUEST_ID</code></td> 295 <td><code>RESULT_OK</code>, <code>RESULT_ERROR</code>, <code>RESULT_DEVELOPER_ERROR</code></td> 296 </tr> 297 </table> 298 299 <h3 id="billing-intents">In-app billing broadcast intents</h3> 300 301 <p>The following section describes the In-app Billing broadcast intents that are sent by the Google 302 Play application. These broadcast intents inform your application about In-app Billing actions 303 that have occurred. Your application must implement a {@link android.content.BroadcastReceiver} to 304 receive these broadcast intents, such as the <code>BillingReceiver</code> that's shown in the in-app 305 billing <a href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">sample 306 application</a>.</p> 307 308 <h4>com.android.vending.billing.RESPONSE_CODE</h4> 309 310 <p>This broadcast intent contains a Google Play response code, and is sent after you make an 311 In-app Billing request. A server response code can indicate that a billing request was successfully 312 sent to Google Play or it can indicate that some error occurred during a billing request. This 313 intent is not used to report any purchase state changes (such as refund or purchase information). 314 For more information about the response codes that are sent with this response, see <a 315 href="#billing-codes">Google Play Response Codes for In-app Billing</a>. The sample application 316 assigns this broadcast intent to a constant named <code>ACTION_RESPONSE_CODE</code>.</p> 317 318 <h5>Extras</h5> 319 320 <ul type="none"> 321 <li><code>request_id</code>—a <code>long</code> representing a request ID. A request ID 322 identifies a specific billing request and is returned by Google Play at the time a request is 323 made.</li> 324 <li><code>response_code</code>—an <code>int</code> representing the Google Play server 325 response code.</li> 326 </ul> 327 328 <h4>com.android.vending.billing.IN_APP_NOTIFY</h4> 329 330 <p>This response indicates that a purchase has changed state, which means a purchase succeeded, was 331 canceled, or was refunded. This response contains one or more notification IDs. Each notification ID 332 corresponds to a specific server-side message, and each messages contains information about one or 333 more transactions. After your application receives an <code>IN_APP_NOTIFY</code> broadcast intent, 334 you send a <code>GET_PURCHASE_INFORMATION</code> request with the notification IDs to retrieve the 335 message details. The sample application assigns this broadcast intent to a constant named 336 <code>ACTION_NOTIFY</code>.</p> 337 338 <h5>Extras</h5> 339 340 <ul type="none"> 341 <li><code>notification_id</code>—a <code>String</code> representing the notification ID for 342 a given purchase state change. Google Play notifies you when there is a purchase state change 343 and the notification includes a unique notification ID. To get the details of the purchase state 344 change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</li> 345 </ul> 346 347 <h4>com.android.vending.billing.PURCHASE_STATE_CHANGED</h4> 348 349 <p>This broadcast intent contains detailed information about one or more transactions. The 350 transaction information is contained in a JSON string. The JSON string is signed and the signature 351 is sent to your application along with the JSON string (unencrypted). To help ensure the security of 352 your In-app Billing messages, your application can verify the signature of this JSON string. The 353 sample application assigns this broadcast intent to a constant named 354 <code>ACTION_PURCHASE_STATE_CHANGED</code>.</p> 355 356 <h5>Extras</h5> 357 358 <ul type="none"> 359 <li><code>inapp_signed_data</code>—a <code>String</code> representing the signed JSON 360 string.</li> 361 <li><code>inapp_signature</code>—a <code>String</code> representing the signature.</li> 362 </ul> 363 364 <p class="note"><strong>Note:</strong> Your application should map the broadcast intents and extras 365 to constants that are unique to your application. See the <code>Consts.java</code> file in the 366 sample application to see how this is done.</p> 367 368 <p>The fields in the JSON string are described in the following table (see table 9):</p> 369 370 <p class="table-caption"><strong>Table 9.</strong> Description of JSON fields that are returned with 371 a <code>PURCHASE_STATE_CHANGED</code> intent.</p> 372 373 <table> 374 375 <tr> 376 <th>Field</th> 377 <th>Description</th> 378 </tr> 379 <tr> 380 <td>nonce</td> 381 <td>A number used once. Your application generates the nonce and sends it with the 382 <code>GET_PURCHASE_INFORMATION</code> request. Google Play sends the nonce back as part of the 383 JSON string so you can verify the integrity of the message.</td> 384 </tr> 385 <tr> 386 <td>notificationId</td> 387 <td>A unique identifier that is sent with an <code>IN_APP_NOTIFY</code> broadcast intent. Each 388 <code>notificationId</code> corresponds to a specify message that is waiting to be retrieved on 389 the Google Play server. Your application sends back the <code>notificationId</code> with the 390 <code>GET_PURCHASE_INFORMATION</code> message so Google Play can determine which messages you 391 are retrieving.</td> 392 </tr> 393 <tr> 394 <td>orderId</td> 395 <td>A unique order identifier for the transaction. This corresponds to the Google Wallet Order 396 ID.</td> 397 </tr> 398 <tr> 399 <td>packageName</td> 400 <td>The application package from which the purchase originated.</td> 401 </tr> 402 <tr> 403 <td>productId</td> 404 <td>The item's product identifier. Every item has a product ID, which you must specify in the 405 application's product list on the Google Play Developer Console.</td> 406 </tr> 407 <tr> 408 <td>purchaseTime</td> 409 <td>The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).</td> 410 </tr> 411 412 <tr> 413 <td>purchaseState</td> 414 <td>The purchase state of the order. Possible values are 0 (purchased), 1 (canceled), 2 415 (refunded), or 3 (expired, for subscription purchases only).</td> 416 </tr> 417 <tr> 418 <td>purchaseToken</td> 419 <td>A token that uniquely identifies a subscription purchase for a given item and user pair. 420 You can use the token to specify the subscription when querying for subscription validity. 421 422 <p><br><em>Supported only in In-app Billing API Version 2 and higher.</em></p></td> 423 </tr> 424 <tr> 425 <td>developerPayload</td> 426 <td>A developer-specified string that contains supplemental information about an order. You can 427 specify a value for this field when you make a <code>REQUEST_PURCHASE</code> request.</td> 428 </tr> 429 </table> 430 431 <!--<h2 id="other-intents">Other Intents</h2> 432 433 <p>The following Intents related to In-app Billing may be useful in your 434 implemention. </p> --> 435 436 <h3 id="http-api">REST API for subscriptions</h3> 437 <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/gp-purchase-status-api.html">Purchase Status API</a> for more information.</p> 438
