Added documentation for In-App Payments API.

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

+<h1>In-App Payments Service</h1>
+
+<p class="warning">
+This service is currently available to Chrome users on the
+<a href="http://www.chromium.org/getting-involved/dev-channel">dev channel</a>.
+</p>
+
+<table class="intro">
+  <tr>
+    <th scope="col"></th>
+    <th scope="col"></th>
+  </tr>

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

Is the blank row necessary?

[Andy, 2013/07/09 20:46:53]

Blank row removed.  (I copied the table from one of the API docs; I don't know
what the purpose of the blank row is.)

+  <tr>
+    <td><strong>Description:</strong></td>
+    <td>Use the In-App Payments Service to sell digital and virtual goods within a Chrome app.</td>
+  </tr>
+  <tr>
+    <td><strong>Availability:</strong></td>
+    <td>Chrome 29 or later</td>

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

This brings up an interesting point. Since we're going to start generating these
(though not for this API) what should the language be? We don't have to get it
right now I suppose, but it's already starting to differ (most APIs say like
"Google Chrome 29", here it's "Chrome 29 or later").

What do you think? I never really liked "Google Chrome 29", it feels awkward.

Anyway not something we need to fix right away.

[Andy, 2013/07/09 20:46:53]

I noticed the inconsistency between the docs.  I agree with you that "Google
Chrome XX" is awkward, and strongly prefer "Chrome XX".  Most of the docs at
google.com/chrome use plain "Chrome". 

For this doc, I removed "or later". 

+  </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 In-App Payments Service to sell digital and virtual goods within your app.
+When you use the In-App Payments Service, 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 Service requires you to package a JavaScript file, buy.js, with your app to trigger the purchase flow.

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

can you link to buy.js here? Might as well. Just turn the buy.js into a link I
mean.

[Andy, 2013/07/09 20:46:53]

Done.

+</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

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

You have
the "Buy"
here and
a Buy
above. Can it be consistent?

[Andy, 2013/07/09 20:46:53]

Done.

+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 Service</h2>
+
+<p>Using the In-App Payments Service in an app is similar to using the
+<a href="https://developers.google.com/commerce/wallet/digital/docs/">Google Wallet for 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. These differences are summarized below and described in detail in the
+integration steps.
+</p>
+
+<ul>
+  <li>You can use pre-generated JSON Web Tokens (JWTs) in your app, rather than using a server to generate the tokens.</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>

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

prefer the same <a> than <code> here.

[Andy, 2013/07/09 20:46:53]

Done.

+
+  <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 Service 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;">

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

I presume this pattern is to get a little indented thing in the list? A less
verbose way of doing this, and which would reduce duplication, would be
something like:

(at the top)

<style>
  .indented {
    padding-left: 2em;  /* whatever looks the way you want */
  }
</style>

then everywhere

<ol>
  <li>Generate a JWT...
    <div class="indented">you can generate JWTs...</div>
  </li>
</ol>

[Andy, 2013/07/09 20:46:53]

Done, but I added the style rule in site.css for reuse (plus <style> must
technically be in the <head> section, unless you use the scoped attribute).

+      <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>

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

ditto here and above, though maybe linking to it 3 times in 1 sentence is
overkill? I dunno, see how it looks, but we should be somehow consistent with
the use of monospace vs not (I think not-monospace for the filename and just
always link it - but yeah, see how it looks).

[Andy, 2013/07/09 20:46:53]

Done.

+      </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 set up 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 Service.</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 Service supports automated recurring billing. To set up recurring billing, follow the
+instructions for setting up
+<a href="https://developers.google.com/commerce/wallet/digital/docs/subscriptions">subscriptions</a>
+for the Google Wallet for Digital Goods API,
+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 an additional parameter in the call to <code>buy()</code>).

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

link or some common style here too?

[Andy, 2013/07/09 20:46:53]

Done.

+
+<h2 id="sample-app">Sample app</h2>
+
+<p>
+For a simple app that demonstrates how to use the In-App Payments Service, 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>