am 1cb5ad47: am 147b01bc: Merge "Doc change: In-app Billing -- add notes about...

    Manager</a>. The download includes the client library and code samples.

</p>

<p>You must download the Google Play services SDK in order to develop using the

<a href="{@docRoot}reference/gms-packages.html">Google Play services APIs</a>. However, <strong>you

cannot use the Android emulator</strong> to test an app that depends on the Google Play services

APIs—you must use a real device running Android 2.2 or higher that includes

Google Play Store.</p>

<p>

    To develop using the <a href="{@docRoot}reference/gms-packages.html">Google

    Play services APIs</a>, you must download the Google Play services SDK.

    Additionally, you must provide a physical <strong>development device</strong> on

    which you can run and debug your app. You can develop on any compatible Android

    device that runs Android 2.2 or higher and includes the Google Play Store.

    Ideally, you would develop and test the app on a variety of devices, including

    both phones and tablets. 

</p>

<p class="note"><strong>Note</strong>: Google Play services is not supported on the

Android emulator — to develop using the APIs, you need to provide a development

device such as an Android phone or tablet.</p>

<p>To install the Google Play services SDK for development:</p>

    <li><a href="#billing-purchase-type">Choosing a Purchase Type</a></li>

    <li><a href="#billing-testing-setup">Setting up Test Accounts</a></li>

    <li><a href="#billing-refunds">Handling Refunds</a></li>

    <li><a href="#billing-refunds">Working with Order Numbers</a></li>

    <li><a href="#billing-support">Where to Get Support</a></li>

  </ol>

  <h2>Downloads</h2>

site, registering test accounts, and handling refunds when necessary.</p>

<p>You must have a Google Play publisher account to register test accounts. And you must have a

Google Wallet merchant account to create a product list and issue refunds to your users. If you

Google Checkout merchant account to create a product list and issue refunds to your users. If you

already have a publisher account on Google Play, you can use your existing account. You do not

need to register for a new account to support in-app billing. If you do not have a publisher

account, you can register as a Google Play developer and set up a publisher account at the

Google Play <a href="http://play.google.com/apps/publish">publisher site</a>. If you do not have a

Google Wallet merchant account, you can register for one at the <a

href="http://checkout.google.com">Google Wallet site</a>.</p>

Google Checkout merchant account, you can register for one at the <a

href="http://checkout.google.com">Google Checkout site</a>.</p>

<h2 id="billing-list-setup">Creating a Product List</h2>

<p>You can access an application's product list by clicking the <strong>In-App Products</strong>

link that appears under each of the applications that are listed for your publisher account (see

figure 1). The <strong>In-App Products</strong> link appears only if you have a Google Wallet

figure 1). The <strong>In-App Products</strong> link appears only if you have a Google Checkout

merchant account and an application's manifest includes the <code>com.android.vending.BILLING</code>

permission.</p>

</p>

<p>You can create a product list for any published application or any draft application that's been

uploaded and saved to the Google Play site. However, you must have a Google Wallet merchant

uploaded and saved to the Google Play site. However, you must have a Google Checkout merchant

account and the application's manifest must include the <code>com.android.vending.BILLING</code>

permission. If an application's manifest does not include this permission, you will be able to edit

existing items in the product list but you will not be able to add new items to the list. For more

<p>In-app billing does not allow users to send a refund request to Google Play. Refunds for

in-app purchases must be directed to you (the application developer). You can then process the

refund through your Google Wallet merchant account. When you do this, Google Play receives a

refund notification from Google Wallet, and Google Play sends a refund message to your

refund through your Google Checkout merchant account. When you do this, Google Play receives a

refund notification from Google Checkout, and Google Play sends a refund message to your

application. For more information, see <a

href="{@docRoot}google/play/billing/billing_overview.html#billing-action-notify">Handling

IN_APP_NOTIFY messages</a> and <a

href="http://www.google.com/support/androidmarket/bin/answer.py?answer=1153485">In-app Billing

Pricing</a>.</p>

<p class="caution"><strong>Important:</strong> You cannot use the Google Wallet API to issue

<p class="caution"><strong>Important:</strong> You cannot use the Google Checkout API to issue

refunds or cancel in-app billing transactions. You must do this manually through your Google

Wallet merchant account. However, you can use the Google Wallet API to retrieve order

Checkout merchant account. However, you can use the Google Checkout API to retrieve order

information.</p>

<h2 id="orderId">Working with Order Numbers</h2>

<p>When a user purchases an in-app item, Google Checkout assigns the transaction

a unique and permanent order number. Google Play provides that order number to

you at the conclusion of the purchase flow, as the value of the

<code>orderId</code> field of the <code>PURCHASE_STATE_CHANGED</code>

intent.</p>

<p>In your app, you can use the order number as a general-purpose identifier for

the in-app purchase transaction. After the purchase, you can use the order

number as a means of tracking the transaction in reconciliation reports and for

customer support.</p>

<p>The order number itself is a string consisting of numbers only, with a format

assigned and managed by Google Checkout.</p>

<p>For transactions dated 5 December 2012 or later, Google Checkout assigns a

Merchant Order Number (rather than a Google Order Number) and reports the Merchant

Order Number as the value of <code>orderID</code>. Here's an

example:</p>

<pre>"orderId" : "12999556515565155651.5565135565155651"</pre>

<p>For transactions dated previous to 5 December 2012, Google checkout assigned

a Google Order Number and reported that number as the value of

<code>orderID</code>. Here's an example of an <code>orderID</code> holding a

Google Order Number:</p>

<pre>"orderId" : "556515565155651"</pre>

<h2 id="billing-testing-setup">Setting Up Test Accounts</h2>

<p>The Google Play publisher site lets you set up one or more test accounts. A test account is a

    List</a>.</p>

    <p class="note"><strong>Note:</strong> You must publish the items in your product

    list (<code>sword_001</code> and <code>potion_001</code>) even though you are not publishing the

    sample application. Also, you must have a Google Wallet Merchant account to add items to the

    sample application. Also, you must have a Google Checkout Merchant account to add items to the

    sample application's product list.</p>

  </li>

</ol>

<ol>

  <li><strong>Make sure you have at least one test account registered under your Google Play

  publisher account.</strong>

    <p>You cannot purchase items from yourself (Google Wallet prohibits this), so you need to

    <p>You cannot purchase items from yourself (Google Checkout prohibits this), so you need to

    create at least one test account that you can use to purchase items in the sample application.

    To learn how to set up a test account, see <a

    href="{@docRoot}google/play/billing/billing_testing.html#billing-testing-setup">Setting up Test

  </li>

  <li><strong>Run the application and purchase the sword or the potion.</strong>

    <p>When you use a test account to purchase items, the test account is billed through Google

    Wallet and your Google Wallet Merchant account receives a payout for the purchase.

    Wallet and your Google Checkout Merchant account receives a payout for the purchase.

    Therefore, you may want to refund purchases that are made with test accounts, otherwise the

    purchases will show up as actual payouts to your merchant account.</p>

</ol>

<pre class="no-pretty-print" style="color:black">{ "nonce" : 1836535032137741465,

  "orders" :

    [{ "notificationId" : "android.test.purchased",

       "orderId" : "transactionId.android.test.purchased",

       "orderId" : "12999556515565155651.5565135565155651",

       "packageName" : "com.example.dungeons",

       "productId" : "android.test.purchased",

       "developerPayload" : "bGoa+V7g/yqDXvKRqq+JTFn4uQZbPiQJo4pf9RzJ",

to "managed per user account."</p>

<p>In the second case, your application can receive an <code>IN_APP_NOTIFY</code> broadcast intent

when Google Play receives a refund notification from Google Wallet. In this case, Google

when Google Play receives a refund notification from Google Checkout. In this case, Google

Play sends an <code>IN_APP_NOTIFY</code> message to your application. Your application can handle

this message the same way it handles responses from an application-initiated

<code>REQUEST_PURCHASE</code> message so that ultimately your application receives a

<code>PURCHASE_STATE_CHANGED</code> broadcast intent. Also, the <code>purchaseState</code> field in

the JSON string is set to 2.</p>

<p class="caution"><strong>Important:</strong> You cannot use the Google Wallet API to

<p class="caution"><strong>Important:</strong> You cannot use the Google Checkout API to

issue refunds or cancel in-app billing transactions. You must do this manually through your

Google Wallet merchant account. However, you can use the Google Wallet API to retrieve order

Google Checkout merchant account. However, you can use the Google Checkout API to retrieve order

information.</p>

<h2 id="billing-security">Security Controls</h2>

<ul>

  <li>In-app billing can be implemented only in applications that you publish through Google

  Play.</li>

  <li>You must have a Google Wallet Merchant account to use Google Play In-app Billing.</li>

  <li>You must have a Google Checkout Merchant account to use Google Play In-app Billing.</li>

  <li>In-app billing requires version 2.3.4 (or higher) of the Android Market application.

  To support subscriptions, version 3.5 or higher of the Google Play app is required. On devices

  running Android 3.0, version 5.0.12 (or higher) of the MyApps application is required.</li>

  <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 Wallet.</td>

purchase an item from yourself, which is not allowed by Google Checkout.</td>

</tr>

</table>

</tr>

<tr>

  <td>orderId</td>

  <td>A unique order identifier for the transaction. This corresponds to the Google Wallet Order

  ID.</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>