am 147b01bc: Merge "Doc change: In-app Billing -- add notes about orderId change and subscription orderIds." into jb-mr1-dev
* commit '147b01bc637ad8d184bd0aa2d6bf902e69c92107':
Doc change: In-app Billing -- add notes about orderId change and subscription orderIds.
diff --git a/docs/html/google/play-services/setup.jd b/docs/html/google/play-services/setup.jd
index 2994c2c..0cf2df3 100644
--- a/docs/html/google/play-services/setup.jd
+++ b/docs/html/google/play-services/setup.jd
@@ -7,13 +7,20 @@
downloadable package from the <a href="{@docRoot}tools/help/sdk-manager.html">SDK
Manager</a>. The download includes the client library and code samples.
</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>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 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>
diff --git a/docs/html/google/play/billing/billing_admin.jd b/docs/html/google/play/billing/billing_admin.jd
index 2413ae5..c0f46d0 100755
--- a/docs/html/google/play/billing/billing_admin.jd
+++ b/docs/html/google/play/billing/billing_admin.jd
@@ -11,6 +11,7 @@
<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>
@@ -39,13 +40,13 @@
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>
@@ -56,7 +57,7 @@
<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>
@@ -78,7 +79,7 @@
</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
@@ -432,19 +433,49 @@
<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
diff --git a/docs/html/google/play/billing/billing_integrate.jd b/docs/html/google/play/billing/billing_integrate.jd
index 2ca7c83..b7e2667 100755
--- a/docs/html/google/play/billing/billing_integrate.jd
+++ b/docs/html/google/play/billing/billing_integrate.jd
@@ -242,7 +242,7 @@
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>
@@ -255,7 +255,7 @@
<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
@@ -294,7 +294,7 @@
</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>
diff --git a/docs/html/google/play/billing/billing_overview.jd b/docs/html/google/play/billing/billing_overview.jd
index 4b2a643..be9dc8d 100755
--- a/docs/html/google/play/billing/billing_overview.jd
+++ b/docs/html/google/play/billing/billing_overview.jd
@@ -265,7 +265,7 @@
<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",
@@ -439,7 +439,7 @@
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
@@ -448,9 +448,9 @@
<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>
@@ -488,7 +488,7 @@
<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>
diff --git a/docs/html/google/play/billing/billing_reference.jd b/docs/html/google/play/billing/billing_reference.jd
index e78c99f..0c82fd5 100755
--- a/docs/html/google/play/billing/billing_reference.jd
+++ b/docs/html/google/play/billing/billing_reference.jd
@@ -105,7 +105,7 @@
<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>
@@ -394,8 +394,10 @@
</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>
diff --git a/docs/html/google/play/billing/billing_subscriptions.jd b/docs/html/google/play/billing/billing_subscriptions.jd
index 5980d83..1217d8a 100755
--- a/docs/html/google/play/billing/billing_subscriptions.jd
+++ b/docs/html/google/play/billing/billing_subscriptions.jd
@@ -107,7 +107,7 @@
<p>When users purchase subscriptions in your apps, Google Play handles all
checkout details so your apps never have to directly process any financial
transactions. Google Play processes all payments for subscriptions through
-Google Wallet, just as it does for standard in-app products and app purchases.
+Google Checkout, just as it does for standard in-app products and app purchases.
This ensures a consistent and familiar purchase flow for your users.</p>
<img src="{@docRoot}images/billing_subscription_flow.png" style="border:4px solid ddd;">
@@ -221,10 +221,10 @@
either of two intervals:</p>
<ul>
- <li>Monthly — Google Play bills the customer’s Google Wallet account at
+ <li>Monthly — Google Play bills the customer’s Google Checkout account at
the time of purchase and monthly subsequent to the purchase date (exact billing
intervals can vary slightly over time)</li>
- <li>Annually — Google Play bills the customer's Google Wallet account at
+ <li>Annually — Google Play bills the customer's Google Checkout account at
the time of purchase and again on the same date in subsequent years.</li>
</ul>
@@ -238,7 +238,7 @@
Direct Carrier Billing) that was originally used to purchase the
subscription.</p>
-<p>When the subscription payment is approved by Google Wallet, Google Play
+<p>When the subscription payment is approved by Google Checkout, Google Play
provides a purchase token back to the purchasing app through the In-app Billing
API. For details, see <a href="#token">Purchase token</a>, below. Your apps can
store the token locally or pass it to your backend servers, which can then use
@@ -343,7 +343,7 @@
<h3 id="payment">Payment processing and policies</h3>
<p>In general, the terms of Google Play allow you to sell in-app subscriptions
-only through the standard payment processor, Google Wallet. For purchases of any
+only through the standard payment processor, Google Checkout. For purchases of any
subscription products, just as for other in-app products and apps, the
transaction fee for subscriptions, just as for other in-app purchases, is the
same as the transaction fee for application purchases (30%).</p>
@@ -356,6 +356,22 @@
href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=140504">policies
document</a>.</p>
+<h3 id="orderId">Subscription Order Numbers</h3>
+
+<p>To help you track transactions relating to a given subscription, Google
+Checkout provides a base Merchant Order Number for all recurrences of the subscription and denotes
+each recurring transaction by appending an integer as follows: </p>
+
+<p><span style="color:#777"><code style="color:#777">12999556515565155651.5565135565155651</code> (base order number)</span><br />
+<code>12999556515565155651.5565135565155651..0</code> (initial purchase orderID)<br />
+<code>12999556515565155651.5565135565155651..1</code> (first recurrence orderID)<br />
+<code>12999556515565155651.5565135565155651..2</code> (second recurrence orderID)<br />
+...<br /></p>
+
+<p>Google Play provides that order number to as the value of the
+<code>orderId</code> field of the <code>PURCHASE_STATE_CHANGED</code>
+intent.</p>
+
<h3 id="requirements">System requirements for subscriptions</h3>
<p>In-app purchases of subscriptions are supported only on devices that meet
@@ -440,7 +456,7 @@
token, a string value that uniquely identifies (and associates) a user ID and a
subscription ID. Google Play generates the purchase token when the user
completes the purchase of a subscription product (and payment is approved by
-Google Wallet) and then sends it to the purchasing app on the device through the
+Google Checkout) and then sends it to the purchasing app on the device through the
In-app Billing API. </p>
<p>At the conclusion of a <code>PURCHASE_REQUEST</code> message flow, your app
@@ -456,7 +472,7 @@
<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",
diff --git a/docs/html/google/play/billing/billing_testing.jd b/docs/html/google/play/billing/billing_testing.jd
index edf7e70..4cbcde1 100755
--- a/docs/html/google/play/billing/billing_testing.jd
+++ b/docs/html/google/play/billing/billing_testing.jd
@@ -62,7 +62,7 @@
<img src="{@docRoot}images/billing_test_flow.png" height="381" id="figure1" />
<p class="img-caption">
- <strong>Figure 1.</strong> Wallet flow for the special reserved item android.test.purchased.
+ <strong>Figure 1.</strong>Wallet flow for the special reserved item android.test.purchased.
</p>
<p>You do not need to list the reserved products in your application's product list. Google Play
@@ -91,8 +91,8 @@
<p>When you make an in-app billing request with this product ID, Google Play responds as
though the purchase was refunded. Refunds cannot be initiated through Google Play's in-app
billing service. Refunds must be initiated by you (the merchant). After you process a refund
- request through your Google Wallet account, a refund message is sent to your application by
- Google Play. This occurs only when Google Play gets notification from Google Wallet that
+ request through your Google Checkout account, a refund message is sent to your application by
+ Google Play. This occurs only when Google Play gets notification from Google Checkout that
a refund has been made. For more information about refunds, see <a
href="{@docRoot}google/play/billing/billing_overview.html#billing-action-notify">Handling
IN_APP_NOTIFY messages</a> and <a
@@ -216,7 +216,7 @@
<p>To test your in-app billing implementation with actual in-app purchases, you will need to
register at least one test account on the Google Play publisher site. You cannot use your
-developer account to test the complete in-app purchase process because Google Wallet does not let
+developer account to test the complete in-app purchase process because Google Checkout does not let
you buy items from yourself. If you have not set up test accounts before, see <a
href="{@docRoot}google/play/billing/billing_admin.html#billing-testing-setup">Setting up test
accounts</a>.</p>
@@ -224,8 +224,8 @@
<p>Also, a test account can purchase an item in your product list only if the item is published. The
application does not need to be published, but the item does need to be published.</p>
-<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. Therefore, you may
+<p>When you use a test account to purchase items, the test account is billed through Google Checkout
+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>
diff --git a/docs/html/google/play/billing/index.jd b/docs/html/google/play/billing/index.jd
index f229696..c3c7a24 100755
--- a/docs/html/google/play/billing/index.jd
+++ b/docs/html/google/play/billing/index.jd
@@ -8,8 +8,11 @@
<div class="sidebox-wrapper">
<div class="sidebox">
- <p><strong>Free trials for subscriptions</strong> <span class="new" style="font-size:.78em;">New!</span></p>
- <p>You can now offer users a configurable <a href="{@docRoot}google/play/billing/billing_subscriptions.html#trials">free trial period</a> for your in-app subscriptions. You can set up trials with a simple change in the Developer Console—no change to your app code is needed.
+ <h2><strong>New in In-App Billing</strong></h2>
+ <ul>
+ <li><strong>New order number format</strong>— Starting 5 December, orders are reported in Merchant Order Number format. See <a href="{@docRoot}google/play/billing/billing_admin.html#orderId">Working with Order Numbers</a> for an example.</li>
+ <li><strong>Free trials</strong>—You can now offer users a configurable <a href="/google/play/billing/billing_subscriptions.html#trials">free trial period</a> for your in-app subscriptions. You can set up trials with a simple change in the Developer Console—no change to your app code is needed.</li>
+ </ul>
</div>
</div>
@@ -29,7 +32,7 @@
<p>Any application that you publish through Google Play can implement In-app Billing. No special
account or registration is required other than an Android Market publisher account and a Google
-Wallet Merchant account. Also, because the service uses no dedicated framework APIs, you can add
+Checkout merchant account. Also, because the service uses no dedicated framework APIs, you can add
in-app billing to any application that uses a minimum API level of 4 or higher.</p>
<p>To help you integrate in-app billing into your application, the Android SDK