templates/articles/google_wallet.html

<h1>Google Wallet for Digital Goods</h1>

<table class="intro">
  <tr>
    <td><strong>Description:</strong></td>
    <td>Use Google Wallet for digital goods 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/samples/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><br>
    <a href="http://www.youtube.com/watch?v=Z3jryGggMCs">How-to Video</a></td>
  </tr>
</table>

<h2 id="overview">Overview</h2>

<p>
You can use Google Wallet for digital goods to sell digital and virtual goods within your app.
The Google Wallet for digital goods client 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.
Google Wallet for digital goods 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, Google Wallet for digital goods displays a payment processing window
on top of your application window:
</p>

<img src="{{static}}/images/wallet-review.png"
     width="694"
     alt="screenshot: Google Wallet 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/wallet-confirmation.png"
     width="694"
     alt="screenshot: Google Wallet confirmation dialog">

<p>
If the user is not signed up for Google Wallet, Google Wallet for digital goods takes the user through the sign-up flow:
</p>

<img src="{{static}}/images/wallet-set-up.png"
     width="694"
     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 Google Wallet for digital goods</h2>

<p>Using Google Wallet for digital goods in a Chrome 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 Google Wallet for digital goods 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">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 in order to use Google Wallet for digital goods.
    </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>Google Wallet for digital goods 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 Google Wallet for digital goods, see:
</p>

</ul>
  <li><a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/samples/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>