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