Added documentation for In-App Payments API.

chrome/common/extensions/docs/templates/articles/service_in_app_payments.html

+<h1>In-App Payments API</h1>
+
+{{?api.permissions.trunk}}{{+partials.warning_trunk}}{{/}}
+{{?api.permissions.dev}}{{+partials.warning_dev}}{{/}}
+{{?api.permissions.beta}}{{+partials.warning_beta}}{{/}}

[not at google - send to devlin, 2013/07/08 16:15:43]

these shouldn't be necessary since it's not built into chrome .: not tied to any
version.

[Andy, 2013/07/09 00:51:23]

Done.

[not at google - send to devlin, 2013/07/09 14:57:36]

My comment here is actually wrong but also right. I didn't realise that it is in
fact tied to a specific version, though that's because the app is built into
Chrome.

However, the dev/beta/stable stuff doesn't apply, right? We always install the
app?

So all we really need to say is the availability, which luckily isn't going to
change.

[not at google - send to devlin, 2013/07/09 14:58:09]

oops this was an old comment sorry.

+
+<table class="intro">
+  <tr>
+    <th scope="col"></th>
+    <th scope="col"></th>
+  </tr>
+  <tr>
+    <td><strong>Description:</strong></td>
+    <td>Use the Chrome In-App Payments API to sell digital and virtual goods within a Chrome app.</td>
+  </tr>
+  <tr>
+    <td><strong>Availability:</strong></td>
+    <td>Chrome 29 or later</td>
+  </tr>
+  <tr>
+    <td><strong>Sample:</strong></td>
+    <td><a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/in-app-payments">in-app-payments</a></td>
+  </tr>
+  <tr>
+    <td><strong>Learn more:</strong></td>
+    <td>
+    <a href="https://support.google.com/chrome_webstore/answer/1053354">Google Wallet</a>; <br>
+    <a href="https://developers.google.com/commerce/wallet/digital/docs/">Google Wallet for Digital Goods</a></td>
+  </tr>
+</table>
+
+<h2 id="overview">Overview</h2>
+
+<p>
+You can use the Chrome In-App Payments API to sell digital and virtual goods within your app.
+When you use the In-App Payments API, the Chrome Wallet App, which is embedded in Chrome, communicates with the
+<a href="https://support.google.com/chrome_webstore/answer/1053354">Google Wallet</a>
+servers and handles all the required checkout details, so your app does not have to process any financial transactions.
+The In-App Payments API requires you to package a JavaScript file, buy.js, with your app to trigger the purchase flow.
+</p>
+
+<h2 id="flow">Purchase flow</h2>
+
+<p>
+When a customer clicks a Buy button in your app to make a purchase, the Chrome Wallet App displays a payment processing window
+on top of your application window:
+</p>
+
+<img src="{{static}}/images/in-app-payments-review.png"
+     width="569"
+     alt="screenshot: in-app-payments review dialog">
+
+<p>
+When the user clicks the "Buy" button, the Google Wallet server processes the payment and displays a purchase confirmation dialog
+to the user, as shown below. The success or failure callback in your app is invoked appropriately.
+</p>
+
+<img src="{{static}}/images/in-app-payments-confirmation.png"
+     width="563"
+     alt="screenshot: in-app-payments confirmation dialog">
+
+<p>
+If the user is not signed up for Google Wallet, the Chrome Wallet App takes the user through the sign-up flow:
+</p>
+
+<img src="{{static}}/images/in-app-payments-set-up.png"
+     width="565"
+     alt="screenshot: Google wallet set up dialog">
+
+<h2 id="sample-code">Sample code</h2>
+
+<p>
+The following code snippet illustrates how to initiate the purchase flow in an app.
+The parameters for the <code>buy()</code> method are described below.
+</p>
+
+<pre>
+google.payments.inapp.buy({
+  parameters: {},
+  jwt: 'eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiIxNDIwNDk' +
+       '1MzA5NDM1MjE2ODU3MSIsImF1ZCI6Ikdvb2dsZSI' +
+       'sInR5cCI6Imdvb2dsZS9wYXltZW50cy9pbmFwcC9' +
+       'zdWJzY3JpcHRpb24vdjEiLCJpYXQiOjEzNTg0NTc' +
+       'yNjksImV4cCI6MjM1ODQxMjMzNDMsInJlcXVlc3Q' +
+       'iOnsiaW5pdGlhbFBheW1lbnQiOnsicHJpY2UiOiI' +
+       'xMC41MCIsImN1cnJlbmN5Q29kZSI6IlVTRCIsInB' +
+       'heW1lbnRUeXBlIjoicHJvcmF0ZWQifSwicmVjdXJ' +
+       'yZW5jZSI6eyJwcmljZSI6IjQuOTkiLCJjdXJyZW5' +
+       'jeUNvZGUiOiJVU0QiLCJzdGFydERhdGUiOiIxMzU' +
+       '4NDYzMjY5IiwiZnJlcXVlbmN5IjoibW9udGhseSI' +
+       'sIm51bVJlY3VycmVuY2VzIjoiMTIifSwibmFtZSI' +
+       '6IlBpZWNlIG9mIENha2UiLCJkZXNjcmlwdGlvbiI' +
+       '6IkEgZGVsaWNpb3VzIHBpZWNlIG9mIHZpcnR1YWw' +
+       'gY2FrZSIsInNlbGxlckRhdGEiOiJZb3VyIERhdGE' +
+       'gSGVyZSJ9fQ.sXd39R7MNNfDFa-jnlTNu2C2te-_' +
+       'x9--87Phfdr5GrE',
+  success: logSuccess,
+  failure: logFailure
+});
+</pre>
+
+<h2 id="how-to">How to use the API</h2>
+
+<p>Using the In-App Payments API in an app is similar to using the
+<a href="https://developers.google.com/commerce/wallet/digital/docs/">Google Wallet Digital Goods API</a> in a web site.
+The integration steps below are based on the
+<a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial">Google Wallet for Digital Goods Tutorial</a>,
+but there are a few key differences for Apps:
+</p>
+
+<ul>
+  <li>You can use pre-generated JSON Web Tokens (JWTs) in your app, rather than generate the tokens with a server.</li>
+
+  <li>You must package the <code>buy.js</code> library with your app, and load the library from its location in your package.</li>
+
+  <li>You must call the <code>buy()</code> method with an extra parameter called <code>parameters</code>.</li>
+
+  <li>The UI to process payments is displayed in a separate window on top of your application window, rather than in an iframe.</li>
+</ul>
+
+<p>Follow these steps to use the In-App Payments API in your app:</p>
+
+<ol>
+  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#1">Generate a JSON Web Token (JWT) for each item to be purchased.</a>
+    <ul style="list-style-type: none;">
+      <li>You can generate JWTs using a server, or you can pre-generate JWTs for use in your app.
+      <p class="warning">
+      Note: If you use pre-generated JWTs, you should generate the JWTs outside of your app, and include
+      the generated tokens in your app.
+      <strong>NEVER</strong> include the Seller secret you use to generate tokens in your app.
+      If you need to generate JWTs dynamically, you should use a server.
+      </p>
+      </li>
+    </ul>
+  </li>
+
+  <li>Include <a href="https://raw.github.com/GoogleChrome/chrome-app-samples/master/in-app-payments/buy.js">buy.js</a> in your app.
+    <ul style="list-style-type: none;">
+      <li>Due to the security restrictions in the
+      <a href="https://developer.chrome.com/extensions/contentSecurityPolicy.html">Content Security Policy</a> for Chrome apps,
+      you cannot include the <code>buy.js</code> library from an external location. Instead, you must package
+      <code>buy.js</code> with your app, and load the library from the packaged location.</li>
+      </li>
+    </ul>
+  </li>
+
+  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#3">Create success and failure callback handlers.</a>
+    <ul style="list-style-type: none;">
+      <li>Success and failure callback handlers let your app react to the purchase flow's completion.</li>
+    </ul>
+  </li>
+
+  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#4">Call buy().</a>
+    <ul style="list-style-type: none;">
+      <li>When a customer clicks the Buy button in your app, call <code>buy()</code> to initiate the purchase flow.
+      <p>
+      For Apps, you must call <code>buy()</code> with an extra parameter called <code>parameters</code>.
+      This parameter currently has one field, <code>env</code>, which specifies the environment in which to process a payment.
+      You can set this field to either <code>prod</code> (production server that accepts real credit cards), or
+      <code>sandbox</code> (test server that accepts test credit cards to simulate transactions).
+      The default setting is <code>sandbox</code>.
+      </p>
+      </li>
+    </ul>
+  </li>
+
+  <li>(Optional) <a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#5">Acknowledge purchase notification.</a>
+    <ul style="list-style-type: none;">
+      <li>You can specify a postback URL to make sure that the customer has paid for an item.</li>
+    </ul>
+  </li>
+
+  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#6">Get setup as a seller on Google Wallet.</a>
+    <ul style="list-style-type: none;">
+      <li>You must sign up for Google Wallet for digital goods in order to use the In-App Payments API.</li>
+    </ul>
+  </li>
+
+  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#7">Switch to the production server.</a>
+    <ul style="list-style-type: none;">
+      <li>Switch from the sandbox server to the production server and test your app using real credit cards.</li>
+    </ul>
+  </li>
+</ol>
+
+<h2 id="recurring">Recurring billing</h2>
+
+<p>The In-App Payments API supports automated recurring billing. To set up recurring billing, follow the
+<a href="https://developers.google.com/commerce/wallet/digital/docs/subscriptions">instructions for setting up subscriptions for the Google Wallet digital goods API</a>,
+but note again the differences described above (you can use pre-generated JWT tokens;
+you must package buy.js with your app; and you must specify the additional parameter in the call to <code>buy()</code>).
+
+<h2 id="sample-app">Sample app</h2>
+
+<p>
+For a simple app that demonstrates how to use the In-App Payments API, see:
+</p>
+
+</ul>
+  <li><a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/in-app-payments">source code</a></li>
+  <li><a href="https://chrome.google.com/webstore/detail/moldiohggmfllblgmikpeoagipenlcae">published app</a> (requires Chrome 29 or higher)</li>
+</ul>
+
+<p>
+You can install and run the published app from the Chrome Web Store to try out the in-app payment purchase flow.
+The app has options to use either the production server or the sandbox server. When testing with the sandbox server,
+use these <a href="https://developers.google.com/commerce/wallet/digital/docs/testing">test credit card numbers</a>,
+which pass basic checks by the Google Wallet for Digital Goods system.
+</p>