1page.title=In-app Billing Reference
2parent.title=In-app Billing
3parent.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</a></li>
11    <li><a href="#billing-interface">API Reference</a>
12    <ol>
13      <li><a href="#getSkuDetails">getSkuDetails()</a></li>
14      <li><a href="#getBuyIntent">getBuyIntent()</a></li>
15      <li><a href="#upgrade-getBuyIntentToReplaceSkus">getBuyIntentToReplaceSkus()</a></li>
16      <li><a href="#getPurchases">getPurchases()</a></li>
17    </ol>
18    </li>
19  </ol>
20  <h2>Downloads</h2>
21  <ol>
22    <li><a href="{@docRoot}google/play/billing/billing_integrate.html#billing-download">Sample
23    Application (V3)</a></li>
24  </ol>
25  <h2>See also</h2>
26  <ol>
27    <li><a href="{@docRoot}google/play/billing/api.html">In-app Billing Version 3</a></li>
28    <li><a href="{@docRoot}training/in-app-billing/index.html">Selling In-app Products</a></li>
29  </ol>
30</div>
31</div>
32<p>This documentation provides technical reference information for using the
33In-app Billing Version 3 API. </p>
34
35<h2 id="billing-codes">Server Response Codes</h2>
36<p>
37  The following table lists all of the server response codes that are sent from
38  Google Play to your application. Google Play sends the response code
39  synchronously as an integer mapped to the {@code RESPONSE_CODE} key in the
40  response {@code Bundle}. Your application must handle all of these response
41  codes.
42</p>
43<p class="table-caption" id="response-codes-table">
44<strong>Table 1.</strong> Summary of response codes for In-app Billing Version 3 API calls.</p>
45<table>
46  <tr>
47    <th scope="col">Response Code</th>
48    <th scope="col">Value</th>
49    <th scope="col">Description</th>
50  </tr>
51  <tr>
52    <td>{@code BILLING_RESPONSE_RESULT_OK}</td>
53    <td>0</td>
54    <td>Success</td>
55  </tr>
56  <tr>
57    <td>{@code BILLING_RESPONSE_RESULT_USER_CANCELED}</td>
58    <td>1</td>
59    <td>User pressed back or canceled a dialog</td>
60  </tr>
61  <tr>
62    <td>{@code BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE}</td>
63    <td>2</td>
64    <td>Network connection is down</td>
65  </tr>
66  <tr>
67    <td>{@code BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE}</td>
68    <td>3</td>
69    <td>Billing API version is not supported for the type requested</td>
70  </tr>
71  <tr>
72    <td>{@code BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE}</td>
73    <td>4</td>
74    <td>Requested product is not available for purchase</td>
75  </tr>
76  <tr>
77    <td>{@code BILLING_RESPONSE_RESULT_DEVELOPER_ERROR}</td>
78    <td>5</td>
79    <td>Invalid arguments provided to the API. This error can also indicate that
80    the application was not correctly signed or properly set up for In-app
81    Billing in Google Play, or does not have the necessary permissions in its
82    manifest</td>
83  </tr>
84  <tr>
85    <td>{@code BILLING_RESPONSE_RESULT_ERROR}</td>
86    <td>6</td>
87    <td>Fatal error during the API action</td>
88  </tr>
89  <tr>
90    <td>{@code BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED}</td>
91    <td>7</td>
92    <td>Failure to purchase since item is already owned</td>
93  </tr>
94  <tr>
95    <td>{@code BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED}</td>
96    <td>8</td>
97    <td>Failure to consume since item is not owned</td>
98  </tr>
99</table>
100
101<h2 id="billing-interface">API Reference</h2>
102<p>The In-app Billing Version 3 API is defined in the {@code
103  IInAppBillingService.aidl} file, which is included with the Version 3
104  <a href="{@docRoot}training/in-app-billing/preparing-iab-app.html#GetSample">
105  sample application</a>.</p>
106
107<h3 id="getSkuDetails">The getSkuDetails() method</h3>
108<p>
109  This method returns product details for a list of product IDs. In the
110  response {@code Bundle} sent by Google Play, the query results are stored in
111  a String {@code ArrayList} mapped to the {@code DETAILS_LIST} key. Each
112  String in the details list contains product details for a single product in
113  JSON format. The fields in the JSON string with the product details are
114  summarized in table 2.
115</p>
116<p class="table-caption" id="product-details-table">
117<strong>Table 2.</strong> Description of JSON fields with product item details
118returned from a {@code getSkuDetails} request.</p>
119<table>
120  <tr>
121    <th scope="col">Key</th>
122    <th scope="col">Description</th>
123  </tr>
124  <tr>
125    <td>{@code productId}</td>
126    <td>The product ID for the product.</td>
127  </tr>
128  <tr>
129    <td>{@code type}</td>
130    <td>Value must be <code>“inapp”</code> for an in-app product or
131      <code>"subs"</code> for subscriptions.</td>
132  </tr>
133  <tr>
134    <td>{@code price}</td>
135    <td>Formatted price of the item, including its currency sign. The price
136does not include tax.</td>
137  </tr>
138  <tr>
139    <td>{@code price_amount_micros}</td>
140    <td>Price in micro-units, where 1,000,000 micro-units equal one unit of the
141    currency. For example, if {@code price} is {@code "€7.99"}, {@code
142    price_amount_micros} is {@code "7990000"}. This value represents the
143    localized, rounded price for a particular currency.</td>
144  </tr>
145  <tr>
146    <td>{@code price_currency_code}</td>
147    <td><a href="http://en.wikipedia.org/wiki/ISO_4217#Active_codes">ISO 4217
148    currency code</a> for {@code price}. For example, if {@code price} is
149    specified in British pounds sterling, {@code price_currency_code} is {@code
150    "GBP"}.</td>
151  </tr>
152  <tr>
153    <td>{@code title}</td>
154    <td>Title of the product.</td>
155  </tr>
156  <tr>
157    <td>{@code description}</td>
158    <td>Description of the product.</td>
159  </tr>
160</table>
161</p>
162
163<h3 id="getBuyIntent">The getBuyIntent() method</h3>
164<p>
165  This method returns a response code integer mapped to the {@code
166  RESPONSE_CODE} key, and a {@link android.app.PendingIntent} to launch the
167  purchase flow for the in-app item mapped to the {@code BUY_INTENT} key, as
168  described in <a href=
169  "{@docRoot}google/play/billing/billing_integrate.html#purchase">Purchasing an
170  Item</a>. When it receives the {@link android.app.PendingIntent}, Google Play
171  sends a response {@code Intent} with the data for that purchase order. The
172  data that is returned in the response {@code Intent} is summarized in table
173  3.
174</p>
175
176<p class="table-caption" id="purchase-pendingintent-response-table">
177<strong>Table 3.</strong>  Response data from an In-app Billing Version 3 purchase request.</p>
178<table>
179  <tr>
180    <th scope="col">Key</th>
181    <th scope="col">Description</th>
182  </tr>
183  <tr>
184    <td>{@code RESPONSE_CODE}</td>
185    <td>Value is <code>0</code> if the purchase was success, error otherwise.</td>
186  </tr>
187  <tr>
188    <td>{@code INAPP_PURCHASE_DATA}</td>
189    <td>
190       A String in JSON format that contains details about the purchase order. See table 4 for a description of the JSON fields.
191    </td>
192  </tr>
193  <tr>
194    <td>{@code INAPP_DATA_SIGNATURE}</td>
195    <td>String containing the signature of the purchase data that was signed
196with the private key of the developer. The data signature uses the
197RSASSA-PKCS1-v1_5 scheme.</td>
198  </tr>
199</table>
200</p>
201
202<p>Table 4 describes the JSON fields that are returned in the response data for
203a purchase order.</p>
204<p class="table-caption" id="purchase-data-table">
205<strong>Table 4.</strong>  Descriptions of the JSON fields for {@code INAPP_PURCHASE_DATA}.</p>
206<table>
207  <tr>
208    <th scope="col">Field</th>
209    <th scope="col">Description</th>
210  </tr>
211    <tr>
212    <td>{@code autoRenewing}</td>
213    <td>Indicates whether the subscription renews automatically. If
214      <code>true</code>, the subscription is active, and will
215      automatically renew on the next billing date. If <code>false</code>,
216      indicates that the user has canceled the subscription. The user has
217      access to subscription content until the next billing date and will
218      lose access at that time unless they re-enable automatic renewal
219      (or manually renew, as described in
220      <a href="{@docRoot}google/play/billing/billing_subscriptions.html#manual-renewal">Manual
221      Renewal</a>).
222      If you offer a <a href="{@docRoot}google/play/billing/billing_subscriptions.html#grace-period"
223      >grace period</a>, this value remains set to <code>true</code> for all
224      subscriptions, as long as the grace period has not lapsed. The next billing date
225      is extended dynamically every day until the end of the grace period or until the
226      user fixes their payment method.
227    </td>
228  </tr>
229  <tr>
230    <td>{@code orderId}</td>
231    <td>A unique order identifier for the transaction. This identifier
232      corresponds to the Google payments order ID. If the order is a test
233      purchase made through the In-app Billing Sandbox, {@code orderId} is
234      blank.</td>
235  </tr>
236  <tr>
237    <td>{@code packageName}</td>
238    <td>The application package from which the purchase originated.</td>
239  </tr>
240  <tr>
241    <td>{@code productId}</td>
242    <td>The item's product identifier. Every item has a product ID, which you
243      must specify in the application's product list on the Google Play
244      Developer Console.</td>
245  </tr>
246  <tr>
247    <td>{@code purchaseTime}</td>
248    <td>The time the product was purchased, in milliseconds since the epoch (Jan 1, 1970).</td>
249  </tr>
250  <tr>
251    <td>{@code purchaseState}</td>
252    <td>The purchase state of the order. Possible values are <code>0</code>
253      (purchased), <code>1</code> (canceled), or <code>2</code> (refunded).</td>
254  </tr>
255  <tr>
256    <td>{@code developerPayload}</td>
257    <td>A developer-specified string that contains supplemental information about an order. You can specify a value for this field when you make a {@code getBuyIntent} request.</td>
258  </tr>
259  <tr>
260    <td>{@code purchaseToken}</td>
261    <td>A token that uniquely identifies a purchase for a given item and user pair. </td>
262  </tr>
263</table>
264</p>
265
266<h3 id="upgrade-getBuyIntentToReplaceSkus">The getBuyIntentToReplaceSkus()
267  method</h3>
268
269<p>This method is used to upgrade or downgrade a subscription purchase. The method
270is similar to <a href="#getBuyIntent"><code>getBuyIntent()</code></a>, except
271that it takes a list of already-purchased SKUs that are to be
272replaced with the SKU being purchased. When the user completes the purchase,
273Google Play cancels the old SKUs and credits the user with the unused value of
274their subscription time on a pro-rated basis. Google Play applies this credit
275to the new subscription, and does not begin billing the user for the new
276subscription until after the credit is used up.</p>
277
278<p>This method was added with version 5 of the in-app billing API. To verify
279that the method is reported, send an <code>isBillingSupported</code> AIDL
280request.</p>
281
282<p class="note"><strong>Note:</strong> You can only use this method for
283subscription purchases. If the passed <code>type</code> parameter is anything
284other than <code>"subs"</code>, the method returns
285<a href="#billing-codes"><code>BILLING_RESPONSE_RESULT_DEVELOPER_ERROR</code></a>.
286Furthermore, the passed SKUs may not include SKUs for seasonal
287subscriptions.</p>
288
289<p>
290  This method returns a response code integer mapped to the {@code
291  RESPONSE_CODE} key, and a {@link android.app.PendingIntent} to launch the
292  purchase flow for the in-app subscription mapped to the {@code BUY_INTENT}
293  key, as described in <a href=
294  "{@docRoot}google/play/billing/billing_integrate.html#purchase">Purchasing an
295  Item</a>. When it receives the {@link android.app.PendingIntent}, Google Play
296  sends a response {@code Intent} with the data for that purchase order. The
297  data that is returned in the response {@code Intent} is summarized in table
298  5.
299</p>
300
301<p class="table-caption" id="upgrade-purchase-pendingintent-response-table">
302<strong>Table 5.</strong> Response data from an In-app Billing Version 5 purchase request.</p>
303<table>
304  <tr>
305    <th scope="col">Key</th>
306    <th scope="col">Description</th>
307  </tr>
308  <tr>
309    <td>{@code RESPONSE_CODE}</td>
310    <td>Value is <code>0</code> if the purchase succeeds. If the purchase fails, contains an error
311      code.</td>
312  </tr>
313  <tr>
314    <td>{@code INAPP_PURCHASE_DATA}</td>
315    <td>
316       A String in JSON format that contains details about the purchase order.
317       See <a href="#purchase-data-table">table 4</a> for a description of the JSON fields.
318    </td>
319  </tr>
320  <tr>
321    <td>{@code INAPP_DATA_SIGNATURE}</td>
322    <td>String containing the signature of the purchase data that the developer
323      signed with their private key. The data signature uses the
324      RSASSA-PKCS1-v1_5 scheme.</td>
325  </tr>
326</table>
327</p>
328
329</p>
330
331<h3 id="getPurchases">The getPurchases() method</h3>
332<p>This method returns the current un-consumed products owned by the user,
333  including both purchased items and items acquired by redeeming a promo code.
334  Table 5 lists the response data that is returned in the
335  {@link android.os.Bundle}.</p>
336
337<p class="table-caption" id="getpurchases-response-table">
338<strong>Table 6.</strong> Response data from a {@code getPurchases} request.</p>
339<table>
340  <tr>
341    <th scope="col">Key</th>
342    <th scope="col">Description</th>
343  </tr>
344  <tr>
345    <td>{@code RESPONSE_CODE}</td>
346    <td>Value is <code>0</code> if the request was successful, error otherwise.</td>
347  </tr>
348  <tr>
349    <td>{@code INAPP_PURCHASE_ITEM_LIST}</td>
350    <td>{@code StringArrayList} containing the list of productIds of purchases from this app.</td>
351  </tr>
352  <tr>
353    <td>{@code INAPP_PURCHASE_DATA_LIST}</td>
354    <td>{@code StringArrayList} containing the details for purchases from this app. See table 4 for the list of detail information stored in each {@code INAPP_PURCHASE_DATA} item in the list.</td>
355  </tr>
356  <tr>
357    <td>{@code INAPP_DATA_SIGNATURE_LIST}</td>
358    <td>{@code StringArrayList} containing the signatures of purchases from this app.</td>
359  </tr>
360  <tr>
361    <td>{@code INAPP_CONTINUATION_TOKEN}</td>
362    <td>String containing a continuation token to retrieve the next set of
363      in-app products owned by the user. This is only set by the Google Play
364      service if the number of products owned by the user is very large. When a
365      continuation token is present in the response, you must make another call
366      to {@code getPurchases} and pass in the continuation token that you
367      received. The subsequent {@code getPurchases} call returns more purchases
368      and possibly another continuation token.</td>
369  </tr>
370</table>
371</p>
372