Home | History | Annotate | Download | only in v2
      1 page.title=In-app Billing Version 2
      2 excludeFromSuggestions=true
      3 @jd:body
      4 
      5 <div style="background-color:#fffdeb;width:100%;margin-bottom:1em;padding:.5em;">In-app Billing Version 2 is superseded. Please <a href="{@docRoot}google/play/billing/billing_overview.html#migration">migrate to Version 3</a> at your earliest convenience.</div>
      6     <div id="qv-wrapper" style="margin-top:0;">
      7 <div id="qv">
      8 
      9   <h2>In this document</h2>
     10   <ol>
     11     <li><a href="#billing-types">Product and Purchase Types</a></li>
     12     <li><a href="#billing-arch">Service Architecture</a></li>
     13     <li><a href="#billing-msgs">Service Messages</a></li>
     14     <ol>
     15       <li><a href="#billing-request">Request messages</a></li>
     16       <li><a href="#billing-response">Broadcast intents</a></li>
     17       <li><a href="#billing-message-sequence">Messaging sequence</a></li>
     18       <li><a href="#billing-action-notify">Handling IN_APP_NOTIFY messages</a></li>
     19     </ol>
     20     <li><a href="#billing-security">Security Controls</a></li>
     21     <li><a href="#billing-limitations">Requirements and Limitations</a></li>
     22   </ol>
     23 </div>
     24 </div>
     25 
     26 <p>In-app Billing version 2 is the legacy version of the Google Play In-app
     27 Billing. Like Version 3, it lets you interact with the Google Play purchase flow
     28 and payments system indirectly, by means of IPC communication with the Play
     29 Store app installed on the device. </p>
     30 
     31 <p>Unlike Version 3, the Version 2 API is
     32 asynchronous and uses service messages sent as broadcast intents, so
     33 it is more complicated than Version 3. </p>
     34 
     35 <p>Version 2 supports both unmanaged and managed products, as well as supports
     36 subscriptions, where Version 3 does not yet offer support for subscriptions. If
     37 you want to sell subscriptions in your app, you should implement In-app Billing
     38 Version 2, rather than Version 3. </p>
     39 
     40 <p>If you do not need to sell subscriptions, you
     41 should implement In-app Billing Version 3 instead.</p>
     42 
     43 <h2 id="billing-types">Product Types</h2>
     44 
     45 <p>In-app Billing Version supports three different product types
     46 to give you flexibility in how you monetize your app. In all cases, you define
     47 your products using the Google Play Developer Console, including product type,
     48 SKU, price, description, and so on. For more information, see <a
     49 href="{@docRoot}google/play/billing/billing_admin.html">Administering In-app Billing</a>.</p>
     50 
     51 <ul>
     52 <li><em>Managed per user account</em> &mdash; Items that can be purchased only
     53 once per user account on Google Play. When a user purchases an item that uses
     54 the "managed per user account" product type, Google Play permanently stores the
     55 transaction information for each item on a per-user basis. This enables you to
     56 later query Google Play to restore the state of the items a specific user has
     57 purchased. If a user attempts to purchase a managed item that has already been
     58 purchased, Google Play prevents the user from purchasing the item again and
     59 displays an "Item already purchased" error.
     60 
     61 <p>The "managed" product type is useful if you are selling
     62 items such as game levels or application features. These items are not transient
     63 and usually need to be restored whenever a user reinstalls your application,
     64 wipes the data on their device, or installs your application on a new
     65 device.</p>
     66 
     67 <li><em>Unmanaged</em> &mdash; Items that do not have their transaction
     68 information stored on Google Play. This means that you cannot later query Google
     69 Play to retrieve transaction information for those items. For "unmanaged"
     70 purchases, you are responsible for managing the transaction information. Also,
     71 Google Play does not attempt to prevent the user from purchasing an item
     72 multiple times if it uses the "unmanaged" product type. It's up to you to
     73 control how many times an unmanaged item can be purchased.</p>
     74 
     75 <p>The "unmanaged" product type is useful if you are selling consumable items,
     76 such as fuel or magic spells. These items are consumed within your application
     77 and are usually purchased multiple times.</p></li>
     78 
     79 <li><em>Subscriptions</em> &mdash; Items that are sold with a
     80 developer-specified, recurring billing interval. When a user purchases a
     81 subscription, Google Play and its payment processor automatically bill the
     82 user's account at the specified interval and price, charging the amount to the
     83 original payment method. Once the user purchases a subscription, Google Play
     84 continues billing the account indefinitely, without requiring approval or action
     85 from the user. The user can cancel the subscription at any time. 
     86 
     87 <p>Subscriptions can only be sold using the "managed per user account" purchase
     88 type. As with in-app products, once the user has purchased an in-app product
     89 there is no refund window. Users desiring refunds must contact the developer
     90 directly. For more information about subscriptions and how to sell them in your
     91 apps, see the <a href="{@docRoot}google/play/billing/v2/billing_subscriptions.html">Subscriptions</a>
     92 document.</p></li>
     93 </ul>
     94 
     95 <h2 id="billing-arch">Service Architecture</h2>
     96 
     97 <p>Your app accesses the In-app Billing service using an API that is exposed by
     98 the Google Play app installed on the device. The Google Play app then uses an
     99 asynchronous message loop to convey billing requests and responses between your
    100 application and the Google Play server. In practice, your application never
    101 directly communicates with the Google Play server (see figure 1). Instead, your
    102 application sends billing requests to the Google Play application over
    103 interprocess communication (IPC) and receives purchase responses from the Google
    104 Play application in the form of asynchronous broadcast intents. Your application
    105 does not manage any network connections between itself and the Google Play
    106 server or use any special APIs from the Android platform.</p>
    107 
    108 <div class="figure" style="width:440px">
    109 <img src="/images/billing_arch.png" alt="" height="582" />
    110 <p class="img-caption">
    111   <strong>Figure 1.</strong> Your application sends and receives billing messages through the
    112   Google Play application, which handles all communication with the Google Play server.</p>
    113 </div>
    114 
    115 <p>Some in-app billing implementations may also use a private remote server to deliver content or
    116 validate transactions, but a remote server is not required to implement in-app billing. A remote
    117 server can be useful if you are selling digital content that needs to be delivered to a user's
    118 device, such as media files or photos. You might also use a remote server to store users'
    119 transaction history or perform various in-app billing security tasks, such as signature
    120 verification. Although you can handle all security-related tasks in your application, performing
    121 those tasks on a remote server is recommended because it helps make your application less vulnerable
    122 to security attacks.</p>
    123 
    124 <p>A typical in-app billing implementation relies on three components:</p>
    125 <ul>
    126   <li>A {@link android.app.Service Service} (named <code>BillingService</code> in the sample application),
    127   which processes purchase messages from the application and sends billing requests to the Google
    128   Play in-app billing service.</li>
    129   <li>A {@link android.content.BroadcastReceiver BroadcastReceiver} (named <code>BillingReceiver</code> in the sample
    130   application), which receives all asynchronous billing responses from the Google Play
    131   application.</li>
    132   <li>A security component (named <code>Security</code> in the sample application), which performs
    133   security-related tasks, such as signature verification and nonce generation. For more information
    134   about in-app billing security, see <a href="#billing-security">Security controls</a> later in this
    135   document.</li>
    136 </ul>
    137 
    138 <p>You may also want to incorporate two other components to support in-app billing:</p>
    139 <ul>
    140   <li>A response {@link android.os.Handler Handler} (named <code>ResponseHandler</code> in the sample
    141   application), which provides application-specific processing of purchase notifications, errors,
    142   and other status messages.</li>
    143   <li>An observer (named <code>PurchaseObserver</code> in the sample application), which is
    144   responsible for sending callbacks to your application so you can update your user interface with
    145   purchase information and status.</li>
    146 </ul>
    147 
    148 <p>In addition to these components, your application must provide a way to store information about
    149 users' purchases and some sort of user interface that lets users select items to purchase. You do
    150 not need to provide a checkout user interface. When a user initiates an in-app purchase, the Google
    151 Play application presents the checkout user interface to your user. When the user completes the
    152 checkout process, your application resumes.</p>
    153 
    154 <h2 id="billing-msgs">In-app Billing Messages</h2>
    155 
    156 <p>When the user initiates a purchase, your application sends billing messages to Google Play's
    157 in-app billing service (named <code>MarketBillingService</code>) using simple IPC method calls. The
    158 Google Play application responds to all billing requests synchronously, providing your
    159 application with status notifications and other information. The Google Play application also
    160 responds to some billing requests asynchronously, providing your application with error messages and
    161 detailed transaction information. The following section describes the basic request-response
    162 messaging that takes place between your application and the Google Play application.</p>
    163 
    164 <h3 id="billing-request">In-app billing requests</h3>
    165 
    166 <p>Your application sends in-app billing requests by invoking a single IPC method
    167 (<code>sendBillingRequest()</code>), which is exposed by the <code>MarketBillingService</code>
    168 interface. This interface is defined in an <a
    169 href="{@docRoot}guide/components/aidl.html">Android Interface Definition Language</a> file
    170 (<code>IMarketBillingService.aidl</code>). You can <a
    171 href="{@docRoot}google/play/billing/v2/billing_integrate.html#billing-download">download</a> this AIDL
    172 file with the in-app billing sample application.</p>
    173 
    174 <p>The <code>sendBillingRequest()</code> method has a single {@link android.os.Bundle Bundle} parameter.
    175 The Bundle that you deliver must include several key-value pairs that specify various parameters for
    176 the request, such as the type of billing request you are making, the item that is being purchased and
    177 its type, and the application that is making the request. For more information about the Bundle keys
    178 that are sent with a request, see <a
    179 href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-interface">In-app Billing
    180 Service Interface</a>.
    181 
    182 <p>One of the most important keys that every request Bundle must have is the
    183 <code>BILLING_REQUEST</code> key. This key lets you specify the type of billing request you are
    184 making. Google Play's in-app billing service supports the following five types of billing
    185 requests:</p>
    186 
    187 <ul>
    188   <li><code>CHECK_BILLING_SUPPORTED</code>
    189     <p>This request verifies that the Google Play application supports in-app billing. You
    190     usually send this request when your application first starts up. This request is useful if you
    191     want to enable or disable certain UI features that are relevant only to in-app billing.</p>
    192   </li>
    193   <li><code>REQUEST_PURCHASE</code>
    194     <p>This request sends a purchase message to the Google Play application and is the foundation
    195     of in-app billing. You send this request when a user indicates that he or she wants to purchase
    196     an item in your application. Google Play then handles the financial transaction by displaying
    197     the checkout user interface.</p>
    198   </li>
    199   <li><code>GET_PURCHASE_INFORMATION</code>
    200     <p>This request retrieves the details of a purchase state change. A purchase changes state when
    201     a requested purchase is billed successfully or when a user cancels a transaction during
    202     checkout. It can also occur when a previous purchase is refunded. Google Play notifies your
    203     application when a purchase changes state, so you only need to send this request when there is
    204     transaction information to retrieve.</p>
    205   </li>
    206   <li><code>CONFIRM_NOTIFICATIONS</code>
    207     <p>This request acknowledges that your application received the details of a purchase state
    208     change. Google Play sends purchase state change notifications to your application until you
    209     confirm that you received them.</p>
    210   </li>
    211   <li><code>RESTORE_TRANSACTIONS</code>
    212     <p>This request retrieves a user's transaction status for <a
    213     href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">managed
    214     purchases</a> and <a
    215     href="{@docRoot}google/play/billing/billing_admin.html#billing-purchase-type">subscriptions</a>.
    216     You should send this request only when you need to retrieve a user's transaction
    217     status, which is usually only when your application is reinstalled or installed for the first
    218     time on a device.</p>
    219   </li>
    220 </ul>
    221 
    222 <h3 id="billing-response">In-app Billing Responses</h3>
    223 
    224 <p>The Google Play application responds to in-app billing requests with both synchronous and
    225 asynchronous responses. The synchronous response is a {@link android.os.Bundle Bundle} with the following
    226 three keys:</p>
    227 
    228 <ul>
    229   <li><code>RESPONSE_CODE</code>
    230     <p>This key provides status information and error information about a request.</p>
    231   </li>
    232   <li><code>PURCHASE_INTENT</code>
    233     <p>This key provides a {@link android.app.PendingIntent PendingIntent}, which you use to launch the checkout
    234     activity.</p>
    235   </li>
    236   <li><code>REQUEST_ID</code>
    237     <p>This key provides you with a request identifier, which you can use to match asynchronous
    238     responses with requests.</p>
    239   </li>
    240 </ul>
    241 <p>Some of these keys are not relevant to every request. For more information, see <a
    242 href="#billing-message-sequence">Messaging sequence</a> later in this document.</p>
    243 
    244 <p>The asynchronous response messages are sent in the form of individual broadcast intents and
    245 include the following:</p>
    246 
    247 <ul>
    248     <li><code>com.android.vending.billing.RESPONSE_CODE</code>
    249     <p>This response contains a Google Play server response code, and is sent after you make an
    250     in-app billing request. A server response code can indicate that a billing request was
    251     successfully sent to Google Play or it can indicate that some error occurred during a billing
    252     request. This response is <em>not</em> used to report any purchase state changes (such as refund
    253     or purchase information). For more information about the response codes that are sent with this
    254     response, see <a
    255     href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-codes">Server Response Codes
    256     for In-app Billing</a>.</p>
    257   </li>
    258   <li><code>com.android.vending.billing.IN_APP_NOTIFY</code>
    259     <p>This response indicates that a purchase has changed state, which means a purchase succeeded,
    260     was canceled, or was refunded. This response contains one or more notification IDs. Each
    261     notification ID corresponds to a specific server-side message, and each messages contains
    262     information about one or more transactions. After your application receives an
    263     <code>IN_APP_NOTIFY</code> broadcast intent, you send a <code>GET_PURCHASE_INFORMATION</code>
    264     request with the notification IDs to retrieve message details.</p>
    265   </li>
    266   <li><code>com.android.vending.billing.PURCHASE_STATE_CHANGED</code>
    267     <p>This response contains detailed information about one or more transactions. The transaction
    268     information is contained in a JSON string. The JSON string is signed and the signature is sent
    269     to your application along with the JSON string (unencrypted). To help ensure the security of
    270     your in-app billing messages, your application can verify the signature of this JSON string.</p>
    271   </li>
    272 </ul>
    273 
    274 <p>The JSON string that is returned with the <code>PURCHASE_STATE_CHANGED</code> intent provides
    275 your application with the details of one or more billing transactions. An example of this JSON
    276 string for a subscription item is shown below:</p>
    277 <pre class="no-pretty-print" style="color:black">{ "nonce" : 1836535032137741465,
    278   "orders" :
    279     [{ "notificationId" : "android.test.purchased",
    280        "orderId" : "transactionId.android.test.purchased",
    281        "packageName" : "com.example.dungeons",
    282        "productId" : "android.test.purchased",
    283        "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",
    284        "purchaseTime" : 1290114783411,
    285        "purchaseState" : 0,
    286        "purchaseToken" : "rojeslcdyyiapnqcynkjyyjh" }]
    287 }
    288 </pre>
    289 
    290 <p>For more information about the fields in this JSON string, see <a
    291 href="{@docRoot}google/play/billing/v2/billing_reference.html#billing-intents">In-app Billing
    292 Broadcast Intents</a>.</p>
    293 
    294 <h3 id="billing-message-sequence">Messaging sequence</h3>
    295 
    296 <p>The messaging sequence for a typical purchase request is shown in figure 2. Request types for
    297 each <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, broadcast intents
    298 are shown in <em>italic</em>. For clarity, figure 2 does not show the <code>RESPONSE_CODE</code>
    299 broadcast intents that are sent for every request.</p>
    300 
    301 <p>The basic message sequence for an in-app purchase request is as follows:</p>
    302 
    303 <ol>
    304   <li>Your application sends a purchase request (<code>REQUEST_PURCHASE</code> type), specifying a
    305   product ID and other parameters.</li>
    306   <li>The Google Play application sends your application a Bundle with the following keys:
    307   <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and <code>REQUEST_ID</code>. The
    308   <code>PURCHASE_INTENT</code> key provides a {@link android.app.PendingIntent PendingIntent}, which your
    309   application uses to start the checkout UI for the given product ID.</li>
    310   <li>Your application launches the pending intent, which launches the checkout UI.
    311     <p class="note"><strong>Note:</strong> You must launch the pending intent from an activity
    312     context and not an application context.</p>
    313   </li>
    314   <li>When the checkout flow finishes (that is, the user successfully purchases the item or cancels
    315   the purchase), Google Play sends your application a notification message (an
    316   <code>IN_APP_NOTIFY</code> broadcast intent). The notification message includes a notification ID,
    317   which references the transaction.</li>
    318   <li>Your application requests the transaction information by sending a
    319   <code>GET_PURCHASE_STATE_CHANGED</code> request, specifying the notification ID for the
    320   transaction.</li>
    321   <li>The Google Play application sends a Bundle with a <code>RESPONSE_CODE</code> key and a 
    322   <code>REQUEST_ID</code> key.
    323   <li>Google Play sends the transaction information to your application in a
    324   <code>PURCHASE_STATE_CHANGED</code> broadcast intent.</li>
    325   <li>Your application confirms that you received the transaction information for the given
    326   notification ID by sending a confirmation message (<code>CONFIRM_NOTIFICATIONS</code> type),
    327   specifying the notification ID for which you received transaction information.</li>
    328   <li>The Google Play application sends your application a Bundle with a
    329   <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key.</li>
    330 </ol>
    331 
    332 <img src="/images/billing_request_purchase.png" height="231" id="figure2" />
    333 <p class="img-caption">
    334   <strong>Figure 2.</strong> Message sequence for a purchase request.
    335 </p>
    336 
    337 <p>Keep in mind, you must send a confirmation when you receive transaction information from Google
    338 Play (step 8 in figure 2). If you don't send a confirmation message, Google Play will
    339 continue sending <code>IN_APP_NOTIFY</code> messages for the transactions you have not
    340 confirmed. As a best practice, you should not send a <code>CONFIRM_NOTIFICATIONS</code> request for
    341 a purchased item until you have delivered the item to the user. This way, if your application
    342 crashes or something else prevents your application from delivering the product, your application
    343 will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Google Play indicating
    344 that you need to deliver the product. Also, as a best practice, your application must be able to
    345 handle <code>IN_APP_NOTIFY</code> messages that contain multiple orders.</p>
    346 
    347 <p>The messaging sequence for a restore transaction request is shown in figure 3. Request types for
    348 each <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, broadcast intents
    349 are shown in <em>italic</em>. For clarity, figure 3 does not show the <code>RESPONSE_CODE</code>
    350 broadcast intents that are sent for every request.</p>
    351 
    352 <div class="figure" style="width:490px">
    353 <img src="/images/billing_restore_transactions.png" alt="" height="168" />
    354 <p class="img-caption">
    355   <strong>Figure 3.</strong> Message sequence for a restore transactions request.
    356 </p>
    357 </div>
    358 
    359 <p>The request triggers three responses. The first is a {@link android.os.Bundle Bundle} with a
    360 <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. Next, the Google Play
    361 application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status information
    362 or error information about the request. As always, the <code>RESPONSE_CODE</code> message references
    363 a specific request ID, so you can determine which request a <code>RESPONSE_CODE</code> message
    364 pertains to.</p>
    365 
    366 <p>The <code>RESTORE_TRANSACTIONS</code> request type also triggers a
    367 <code>PURCHASE_STATE_CHANGED</code> broadcast intent, which contains the same type of transaction
    368 information that is sent during a purchase request. Unlike with a purchase request, however, the transactions
    369 are given without any associated notification IDs, so you do not need to respond to this
    370 intent with a <code>CONFIRM_NOTIFICATIONS</code> message. </p>
    371 
    372 <p class="note"><strong>Note:</strong> You should use the <code>RESTORE_TRANSACTIONS</code> request
    373 type only when your application is installed for the first time on a device or when your
    374 application has been removed from a device and reinstalled.</p>
    375 
    376 <p>The messaging sequence for checking whether in-app billing is supported is shown in figure 4. The
    377 request type for the <code>sendBillingRequest()</code> method is shown in <strong>bold</strong>.</p>
    378 
    379 <div class="figure" style="width:454px">
    380 <img src="/images/billing_check_supported.png" alt="" height="168" />
    381 <p class="img-caption">
    382   <strong>Figure 4.</strong> Message sequence for checking whether in-app billing is supported.
    383 </p>
    384 </div>
    385 
    386 <p>The synchronous response for a <code>CHECK_BILLING_SUPPORTED</code> request provides a Bundle
    387 with a server response code.  A <code>RESULT_OK</code> response code indicates that in-app billing
    388 is supported; a <code>RESULT_BILLING_UNAVAILABLE</code> response code indicates that in-app billing
    389 is unavailable because the API version you specified is unrecognized or the user is not eligible to
    390 make in-app purchases (for example, the user resides in a country that does not allow in-app
    391 billing). A <code>SERVER_ERROR</code> can also be returned, indicating that there was a problem with
    392 the Google Play server.</p>
    393 
    394 <h3 id="billing-action-notify">Handling IN_APP_NOTIFY messages</h3>
    395 
    396 <p>Usually, your application receives an <code>IN_APP_NOTIFY</code> broadcast intent from Google
    397 Play in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The
    398 <code>IN_APP_NOTIFY</code> broadcast intent informs your application that the state of a requested
    399 purchase has changed. To retrieve the details of that purchase, your application sends a
    400 <code>GET_PURCHASE_INFORMATION</code> request. Google Play responds with a
    401 <code>PURCHASE_STATE_CHANGED</code> broadcast intent, which contains the details of the purchase
    402 state change. Your application then sends a <code>CONFIRM_NOTIFICATIONS</code> message, informing
    403 Google Play that you have received the purchase state change information.</p>
    404 
    405 <p>In some special cases, you may receive multiple <code>IN_APP_NOTIFY</code> messages even though
    406 you have confirmed receipt of the purchase information, or you may receive
    407 <code>IN_APP_NOTIFY</code> messages for a purchase change even though you never initiated the
    408 purchase. Your application must handle both of these special cases.</p>
    409 
    410 <h4>Handling multiple IN_APP_NOTIFY messages</h4>
    411 
    412 <p>When Google Play receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given
    413 <code>PURCHASE_STATE_CHANGED</code> message, it usually stops sending <code>IN_APP_NOTIFY</code>
    414 intents for that <code>PURCHASE_STATE_CHANGED</code> message. Sometimes, however, Google
    415 Play may send repeated <code>IN_APP_NOTIFY</code> intents for a
    416 <code>PURCHASE_STATE_CHANGED</code> message even though your application has sent a
    417 <code>CONFIRM_NOTIFICATIONS</code> message. This can occur if a device loses network connectivity
    418 while you are sending the <code>CONFIRM_NOTIFICATIONS</code> message. In this case, Google Play
    419 might not receive your <code>CONFIRM_NOTIFICATIONS</code> message and it could send multiple
    420 <code>IN_APP_NOTIFY</code> messages until it receives acknowledgement that you received the
    421 transaction message. Therefore, your application must be able to recognize that the subsequent
    422 <code>IN_APP_NOTIFY</code> messages are for a previously processed transaction. You can do this by
    423 checking the <code>orderID</code> that's contained in the JSON string because every transaction has
    424 a unique <code>orderId</code>.</p>
    425 
    426 <h4>Handling refunds and other unsolicited IN_APP_NOTIFY messages</h4>
    427 
    428 <p>There are two cases where your application may receive <code>IN_APP_NOTIFY</code> broadcast
    429 intents even though your application has not sent a <code>REQUEST_PURCHASE</code> message. Figure 5
    430 shows the messaging sequence for both of these cases. Request types for each
    431 <code>sendBillingRequest()</code> method are shown in <strong>bold</strong>, broadcast intents are
    432 shown in <em>italic</em>. For clarity, figure 5 does not show the <code>RESPONSE_CODE</code>
    433 broadcast intents that are sent for every request.</p>
    434 
    435 <div class="figure" style="width:481px">
    436 <img src="/images/billing_refund.png" alt="" height="189" />
    437 <p class="img-caption">
    438   <strong>Figure 5.</strong> Message sequence for refunds and other unsolicited
    439 IN_APP_NOTIFY messages.</p>
    440 </div>
    441 
    442 <p>In the first case, your application may receive an <code>IN_APP_NOTIFY</code> broadcast intent
    443 when a user has your application installed on two (or more) devices and the user makes an in-app
    444 purchase from one of the devices. In this case, Google Play sends an <code>IN_APP_NOTIFY</code>
    445 message to the second device, informing the application that there is a purchase state change. Your
    446 application can handle this message the same way it handles the response from an
    447 application-initiated <code>REQUEST_PURCHASE</code> message, so that ultimately your application
    448 receives a <code>PURCHASE_STATE_CHANGED</code> broadcast intent message that includes information
    449 about the item that has been purchased. This applies only to items that have their product type
    450 set to "managed per user account."</p>
    451 
    452 <p>In the second case, your application can receive an <code>IN_APP_NOTIFY</code> broadcast intent
    453 when Google Play receives a refund notification from Google Wallet. In this case, Google
    454 Play sends an <code>IN_APP_NOTIFY</code> message to your application. Your application can handle
    455 this message the same way it handles responses from an application-initiated
    456 <code>REQUEST_PURCHASE</code> message so that ultimately your application receives a
    457 <code>PURCHASE_STATE_CHANGED</code> message that includes information about the item that has been
    458 refunded. The refund information is included in the JSON string that accompanies the
    459 <code>PURCHASE_STATE_CHANGED</code> broadcast intent. Also, the <code>purchaseState</code> field in
    460 the JSON string is set to 2.</p>
    461 
    462 <p class="caution"><strong>Important:</strong> You cannot use the Google Wallet API to
    463 issue refunds or cancel in-app billing transactions. You must do this manually through your
    464 Google Wallet merchant account. However, you can use the Google Wallet API to retrieve order
    465 information.</p>
    466 
    467 <h2 id="billing-security">Security Controls</h2>
    468 
    469 <p>To help ensure the integrity of the transaction information that is sent to your application,
    470 Google Play signs the JSON string that is contained in the <code>PURCHASE_STATE_CHANGED</code>
    471 broadcast intent. Google Play uses the private key that is associated with the app to create
    472 this signature. The Developer Console generates an RSA key pair for each app.
    473 You can find the public key portion of this key pair in the app's publishing details
    474 in the Developer Console, under <strong>Settings</strong>, in the License Key field.</p>
    475 
    476 <p>When Google Play signs a billing response, it includes the signed JSON string (unencrypted)
    477 and the signature. When your application receives this signed response you can use the public key
    478 portion of your RSA key pair to verify the signature. By performing signature verification you can
    479 help detect responses that have been tampered with or that have been spoofed. You can perform this
    480 signature verification step in your application; however, if your application connects to a secure
    481 remote server then we recommend that you perform the signature verification on that server.</p>
    482 
    483 <p>In-app billing also uses nonces (a random number used once) to help verify the integrity of the
    484 purchase information that's returned from Google Play. Your application must generate a nonce and
    485 send it with a <code>GET_PURCHASE_INFORMATION</code> request and a <code>RESTORE_TRANSACTIONS</code>
    486 request. When Google Play receives the request, it adds the nonce to the JSON string that
    487 contains the transaction information. The JSON string is then signed and returned to your
    488 application. When your application receives the JSON string, you need to verify the nonce as well as
    489 the signature of the JSON string.</p>
    490 
    491 <p>For more information about best practices for security and design, see <a
    492 href="{@docRoot}google/play/billing/billing_best_practices.html">Security and Design</a>.</p>
    493 
    494 <h2 id="billing-limitations">In-app Billing Requirements and Limitations</h2>
    495 
    496 <p>Before you get started with in-app billing, be sure to review the following requirements and
    497 limitations.</p>
    498 
    499 <ul>
    500   <li>In-app billing can be implemented only in applications that you publish through Google
    501   Play.</li>
    502   <li>You must have a Google Wallet Merchant account to use Google Play In-app Billing.</li>
    503   <li>In-app billing requires version 2.3.4 (or higher) of the Android Market application.
    504   To support subscriptions, version 3.5 or higher of the Google Play app is required. On devices
    505   running Android 3.0, version 5.0.12 (or higher) of the MyApps application is required.</li>
    506   <li>An application can use in-app billing only if the device is running Android 1.6 (API level 4)
    507   or higher.</li>
    508   <li>You can use in-app billing to sell only digital content. You cannot use in-app billing to sell
    509   physical goods, personal services, or anything that requires physical delivery.</li>
    510   <li>Google Play does not provide any form of content delivery. You are responsible for
    511   delivering the digital content that you sell in your applications.</li>
    512   <li>You cannot implement in-app billing on a device that never connects to the network. To
    513   complete in-app purchase requests, a device must be able to access the Google Play server over
    514   the network. </li>
    515 </ul>
    516