Google Wallet for Digital Goods

Reference

This page documents the Google Wallet for Digital Goods API for JavaScript.

Contents

How to load the library

Every page that relies on the Google Wallet for Digital Goods API must load the API library as in the following examples.

To load the sandbox API library when you're doing initial development and testing use:

<script src="https://sandbox.google.com/checkout/inapp/lib/buy.js"></script>

To load the production version of the API library use:

<script src="https://wallet.google.com/inapp/lib/buy.js"></script>

JavaScript functions

Functions your client can call:

Functions your client can provide:

buy

google.payments.inapp.buy(purchaseContent)

Initiates the purchase flow. To avoid possible problems with popup blockers, call this function from an onClick handler. For example:

function purchase(){
  ...
  google.payments.inapp.buy({
    'jwt': generatedJwt,
    'success': successHandler,
    'failure': failureHandler
    });
}

<button ... onClick="purchase()">Buy</button>
Parameter Description
purchaseContent An object that defines the purchased item and, optionally, specifies callback handlers. This object has the following fields:
jwt
An object containing the JWT that represents the item to be purchased. See JWT body for details.
success (optional)
Your successHandler function.
failure (optional)
Your failureHandler function.

successHandler

successHandler(result)

Called when a purchase is successfully completed, after the iframe is closed. If you define this function, you should pass it as a parameter to buy().

var successHandler = function(result){
  ...
}
Parameter Description
result An object that contains a request object, a response object, and a JWT:
request
Has the same fields and values as the request object that was passed to buy() (in the jwt parameter). The field order and literal values might be different from the original request. For example, "10.50" might change to "10.5".
response
Contains an orderId field, which contains an order identifier from Google.
jwt
The same JWT that's passed to the server if you specify a postback URL. This JWT includes all the information that's in the request and response objects. For details, see The postback JWT.

Here's an example of the result object for a success handler:

{
  "request": {
    "name": "Piece of Cake",
    "description": "Virtual chocolate cake to fill your virtual tummy",
    "price": "10.50",
    "currencyCode": "USD",
    "sellerData": "user_id:1224245,offer_code:3098576987,affiliate:aksdfbovu9j"
  },
  "response": {
    "orderId": "3485709183457474939449"
  },
  "jwt": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJleHAiOiAxMzA5OTkxNzY0LCAiYXVkIjogImdvb2cucGF5bWVudHMuaW5hcHAuYnV5SXRlbSIsICJpc3MiOiAiMTA4NzM2NjAzNTQ2MjAwOTQ3MTYiLCAic2VsbGVyRGF0YSI6ICJfc2VsbGVyX2RhdGFfIiwgIml0ZW1EZXNjcmlwdGlvbiI6ICJUaGUgc2FmZXRpZXN0IHdheSB0byBkaXNwbGF5IHlvdXIgZmxhaXIiLCAiaXRlbVByaWNlIjogIjMuOTkiLCAiaXNvQ3VycmVuY3lDb2RlIjogIlVTRCIsICJpYXQiOiAxMzA5OTkxMTY0LCAiaXRlbU5hbWUiOiAiU2FmZXR5bW91c2UgUGF0Y2gifQ.E1VH0T9DvQn4GdCjyVavnlurpx0iklQXlqeI1_tAMa8"
}

failureHandler

failureHandler(result)

Called when a purchase fails to complete. If you define this function, you should pass it as a parameter to buy().

Examples of failing to complete include when the buyer closes the iframe before confirming the purchase, or if the buyer's payment method fails multiple times.

var failureHandler = function(result){
  ...
}
Parameter Description
result An object that contains a request object and error information:
request
Either an empty object or an object with the same fields and values as the request object that was passed to buy() (in the jwt parameter). The field order and literal values might be different from the original request. For example, "10.50" might change to "10.5". If the object is empty, it means that the failure occurred quickly, before the request could be delivered to the payments system.
response
Contains an errorType field with the following possible error types:
MERCHANT_ERROR - purchase request contains errors such as a badly formatted JWT
PURCHASE_CANCELLED - buyer cancelled purchase or declined payment
POSTBACK_ERROR - failure to acknowledge postback notification
INTERNAL_SERVER_ERROR - internal Google error

Here's an example of the result object for a failure handler:

{
  "request": {
    "name": "Piece of Cake",
    "description": "Virtual chocolate cake to fill your virtual tummy",
    "price": "10.50",
    "currencyCode": "USD",
    "sellerData": "user_id:1224245,offer_code:3098576987,affiliate:aksdfbovu9j"
  },
  "response": {
    "errorType": "PURCHASE_CANCELLED"
  }
}

Single item JWT

The JSON-formatted body of a JWT (Java Web Token) represents the item being purchased. The Google Wallet for Digital Goods API currently uses JWT v1 and HMAC SHA-256 signatures. For information about the JWT format, see the JWT specification. For information about JWT libraries, see Libraries.

You might deal with JWTs in a few ways in your code. First, your server-side code creates a JWT that your client-side code provides as a parameter to buy(). Second, your success handler is passed the same JWT that you passed to buy(). Finally, if you specify a postback URL, your server-side code receives a Google-generated JWT in an HTTP POST message whenever a purchase transaction completes successfully. This Google-generated JWT is described in Handling Postbacks.

The JWT your server-side code generates can have the following JSON fields and child objects. Unless otherwise noted, each field is required.

  {
    "iss" : "1337133713371337",
    "aud" : "Google"
    "typ" : "google/payments/inapp/item/v1",
    "exp" : "1309988959",
    "iat" : "1409988959",
    "request" :{
      "name" : "Piece of Cake",
      "description" : "Virtual chocolate cake to fill your virtual tummy",
      "price" : "10.50",
      "currencyCode" : "USD",
      "sellerData" : "user_id:1224245,offer_code:3098576987,affiliate:aksdfbovu9j"
    }
  }
Field Type Description
iss String Your Seller Identifier, which you get as described in step 1 and step 7 of the Web tutorial. The "iss" field is a standard JWT field that identifies the issuer of the JWT.
aud String Must be "Google". The "aud" field is a standard JWT field that identifies the target audience for the JWT.
exp String The time when the purchase will expire, specified in seconds since the epoch. This is a standard JWT field.
iat String The time when the JWT was issued, specified in seconds since the epoch. This is a standard JWT field.
typ String The type of request. Must be "google/payments/inapp/item/v1". This is a standard JWT field.
request Object The item being purchased. See the following table for details.

The request object contains fields defining the item properties:

Field Type Description
name String The name of the item. This name is displayed prominently in the purchase flow UI and can have no more than 50 characters.
description String Optional: Text that describes the item. This description is displayed in the purchase flow UI and can have no more than 100 characters.
price String The purchase price of the item, with up to 2 decimal places.
currencyCode String A 3-character currency code that defines the billing currency. Google will automatically convert the billing currency to the currency of your merchant account. The currently supported currencies are USD, EUR, CAD, GBP, AUD, HKD, JPY, DKK, NOK, SEK.
sellerData String Optional: Data to be passed to your success and failure callbacks. The string can have no more than 200 characters. You might want to include something that lets you identify the buyer. Examples of other information you might include are a promotion identifier or a SKU #.

You encode or decode the JWT using your Seller Secret, which you get as described in step 1 and step 7 of the Web tutorial.

Subscription JWT

The Subscription JWT your server-side code generates can have the following JSON fields and child objects. Unless otherwise noted, each field is required.

{
  "iss" : sellerIdentifier,
  "aud" : "Google",
  "typ" : "google/payments/inapp/subscription/v1",
  "exp" : int(time.time() + 3600),
  "iat" : int(time.time()),
  "request" :{
    "name" : "Weekly Cake",
    "description" : "Virtual chocolate cake to fill your virtual tummy every week",
    "sellerData" : "user_id:1224245,offer_code:3098576987,affiliate:aksdfbovu9j",
    "initialPayment" : {
      "price" : "1.49",
      "currencyCode" : "USD",
      "paymentType" : "prorated",
    },
    "recurrence" : {
      "price" : "4.99",
      "currencyCode" : "USD",
      "startTime" : int(time.time() + 2600000),
      "frequency" : "monthly",
      "numRecurrences" : "12",
    }
  }
}
Field Type Description
iss String Your Seller Identifier, which you get as described in step 1 and step 7 of the Web tutorial. The "iss" field is a standard JWT field that identifies the issuer of the JWT.
aud String Must be "Google". The "aud" field is a standard JWT field that identifies the target audience for the JWT.
exp String The time when the purchase will expire, specified in seconds since the epoch. This is a standard JWT field.
iat String The time when the JWT was issued, specified in seconds since the epoch. This is a standard JWT field.
typ String The type of request. Must be "google/payments/inapp/subscription/v1". This is a standard JWT field.
request Object The item being purchased. See the following table for details.

The request object contains fields defining the item properties:

Field Type Description
name String The name of the item. This name is displayed prominently in the purchase flow UI and can have no more than 50 characters.
description String Optional: Text that describes the item. This description is displayed in the purchase flow UI and can have no more than 100 characters.
sellerData String Optional: Data to be passed to your success and failure callbacks. The string can have no more than 200 characters. You might want to include something that lets you identify the buyer. Examples of other information you might include are a promotion identifier or a SKU #.
initialPayment Object Optional: Initial payment defines if there is a one time payment associated with the subscription. This can be a prorated amount or any one time charge.
recurrence Object Defines the recurrence item, frequency, duration and start date

The initialPayment object contains fields defining the item properties:

Field Type Description
price String The price of the initial payment, with up to 2 decimal places.
currencyCode String A 3-character currency code that defines the billing currency. Google will automatically convert the billing currency to the currency of your merchant account. The currently supported currencies are USD, EUR, CAD, GBP, AUD, HKD, JPY, DKK, NOK, SEK.
paymentType String Indicates the initial service being purchased. The currently supported service types are "free_trial" and "prorated".

The recurrence object contains fields defining the item properties:

Field Type Description
price String The price of the recurring item, with up to 2 decimal places.
currencyCode String A 3-character currency code that defines the billing currency. Google will automatically convert the billing currency to the currency of your merchant account. The currently supported currencies are USD, EUR, CAD, GBP, AUD, HKD, JPY, DKK, NOK, SEK.
startTime Number Optional: Time in seconds from epoch to start recurring the charge. The first recurrence will occur at the time specified in this field.
frequency String Indicates the frequency of the recurrence. The current supported frequency is "monthly".
numRecurrences String Optional: Number of times to recur the charge. If omitted the subscription will recur until cancelled.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.