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

<h1>In-App Payments Service</h1>

<table class="intro">
  <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</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 In-App Payments Service to sell digital and virtual goods within your app.
The In-App Payments Service, 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, 
<a href="https://raw.github.com/GoogleChrome/chrome-app-samples/master/in-app-payments/buy.js">buy.js</a>,
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 In-App Payments Service 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 in the payment processing window, 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 In-App Payments Service 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 <a href="https://raw.github.com/GoogleChrome/chrome-app-samples/master/in-app-payments/buy.js">buy.js</a>
  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 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>
    <div class="indent-small">
      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>
    </div>
  </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.
    <div class="indent-small">
      Due to the security restrictions in the
      <a href="contentSecurityPolicy.html">Content Security Policy</a> for Chrome apps,
      you cannot include the <a href="https://raw.github.com/GoogleChrome/chrome-app-samples/master/in-app-payments/buy.js">buy.js</a>
      library from an external location. Instead, you must package the library with your app, and load it from the packaged location.
    </div>
  </li>

  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#3">Create success and failure callback handlers.</a>
    <div class="indent-small">
      Success and failure callback handlers let your app react to the purchase flow's completion.
    </div>
  </li>

  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#4">Call buy().</a>
    <div class="indent-small">
      When a customer clicks a "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>
    </div>
  </li>

  <li>(Optional) <a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#5">Acknowledge purchase notification.</a>
    <div class="indent-small">
      You can specify a postback URL to make sure that the customer has paid for an item.
    </div>
  </li>

  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#6">Get set up as a seller on Google Wallet.</a>
    <div class="indent-small">
      You must sign up for Google Wallet for digital goods in order to use the In-App Payments Service.
    </div>
  </li>

  <li><a href="https://developers.google.com/commerce/wallet/digital/docs/tutorial#7">Switch to the production server.</a>
    <div class="indent-small">
      Switch from the sandbox server to the production server and test your app using real credit cards.
    </div>
  </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 <a href="https://raw.github.com/GoogleChrome/chrome-app-samples/master/in-app-payments/buy.js">buy.js</a>
with your app; and you must specify an 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 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>