Request objects

This reference describes the Google Pay API request object options to use with your website. There are several request objects to configure to make requests to the Google Pay API. To configure the expected experience, a request object is passed to a class method in the Google Pay API client library.

PaymentOptions

Configure this object for a production environment once you've tested your implementation and you're ready to receive payments from shoppers.

If you set up Dynamic Price Updates in your integration, be sure to add MerchantInfo and PaymentDataCallbacks fields.

Property Type Necessity Description
environment string Optional
  • PRODUCTION: Used to return chargeable payment methods when a valid Google merchant ID is specified and configured for the domain.
  • TEST: Dummy payment methods that are suitable for testing (default).
merchantInfo MerchantInfo Optional This object provides information about the merchant that requests payment data.
paymentDataCallbacks PaymentDataCallbacks Optional This object declares the callbacks used for Dynamic Price Updates.

Example

The following example configuration uses non-chargeable payment methods that are suitable for a test environment. It includes the merchant info and payment data callback.

{
  environment: "TEST",
  merchantInfo: {
    merchantName: "Example Merchant",
    merchantId: "12345678901234567890"
  },
  paymentDataCallbacks: {
    onPaymentDataChanged: onPaymentDataChanged,
    onPaymentAuthorized: onPaymentAuthorized
  }
}

IsReadyToPayRequest

This object specifies which payment methods are supported.

Property Type Necessity Description
apiVersion number Required Major API version. The value is 2 for this specification.
apiVersionMinor number Required Minor API version. The value is 0 for this specification.
allowedPaymentMethods PaymentMethod[ ] Required

Specifies support for one or more payment methods supported by the Google Pay API.

A tokenizationSpecification isn't required to determine a viewer's readiness to pay. Provide all required parameters properties for each supported PaymentMethod.

existingPaymentMethodRequired boolean Optional

If set to true then the IsReadyToPayResponse object includes an additional paymentMethodPresent property that describes the visitor's readiness to pay with one or more payment methods specified in allowedPaymentMethods.

Example

This example shows you how to support payment cards and Android device tokens from all supported card networks.

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        "allowedCardNetworks": ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"]
      }
    }
  ]
}

PaymentDataRequest

Use this object to configure your site's support for the Google Pay API.

Property Type Necessity Description
apiVersion number Required Major API version. The value is 2 for this specification.
apiVersionMinor number Required Minor API version. The value is 0 for this specification.
merchantInfo MerchantInfo Required Information about the merchant that requests payment data.
allowedPaymentMethods PaymentMethod[ ] Required Specifies support for one or more payment methods supported by the Google Pay API.
transactionInfo TransactionInfo Required Details about the facilitation of the transaction based upon whether the user agrees to the transaction or not. Includes total price and price status.
callbackIntents string[ ] Optional Specifies the following callback intents for PaymentDataCallbacks:
  • OFFER
  • PAYMENT_AUTHORIZATION
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
offerInfo OfferInfo Optional Specifies which offers to apply when the payment sheet first loads.
emailRequired boolean Optional Set to true to request an email address.
shippingAddressRequired boolean Optional Set to true to request a full shipping address.
shippingAddressParameters ShippingAddressParameters Optional If shippingAddressRequired is set to true, specify shipping address restrictions.
shippingOptionRequired boolean Optional Set to true when the SHIPPING_OPTION callback intent is used. This field is required if you implement support for Authorize Payments or Dynamic Price Updates. For details, see ShippingOptionParameters.
shippingOptionParameters ShippingOptionParameters[ ] Optional Set default options.

Example

The following example shows you how to support payment cards and Android device tokens from all supported card networks. The payment cards are tokenized for an example gateway. The request is for a payment method to charge a final amount of 12.34 United States dollars.

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "merchantInfo": {
    "merchantName": "Example Merchant"
  },
  "offerInfo": {
    "offers": [
      {
        "redemptionCode": "exampleCode",
        "description": "example description of offer"
      }
    ]
  },
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
        "allowedCardNetworks": ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"]
      },
      "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "example",
          "gatewayMerchantId": "exampleGatewayMerchantId"
        }
      }
    }
  ],
  "transactionInfo": {
    "totalPriceStatus": "FINAL",
    "totalPrice": "12.34",
    "currencyCode": "USD"
  }
}

PaymentDataCallbacks

If you set up Dynamic Price Updates in your integration, be sure to add the following onPaymentDataChanged and onPaymentAuthorized callbacks:

Property Type Necessity Description
onPaymentDataChanged function Optional Invoked when the following callbackIntents values are set in PaymentDataRequest:
  • OFFER
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
onPaymentAuthorized function Required Invoked when the following callbackIntents values are set in PaymentDataRequest: PAYMENT_AUTHORIZATION

Example

The following example configuration uses the callbacks needed to set up Dynamic Price Updates:

{
  "onPaymentDataChanged": onPaymentDataChanged,
  "onPaymentAuthorized": onPaymentAuthorized
}

PaymentDataRequestUpdate

This object specifies new transaction info, shipping options and error to update the payment sheet.

Property Type Necessity Description
newOfferInfo OfferInfo Optional Updates the offers currently active in the payment sheet.
newTransactionInfo TransactionInfo Optional Updates the transaction info in the payment sheet.
newShippingOptionParameters ShippingOptionParameters Optional Updates the shipping options in the payment sheet.
error PaymentDataError Optional Adds an error message to the payment sheet.

Example

The following example shows you all of the payment data request updates that can be returned to Google Pay API.

{
  "newTransactionInfo": {
    "displayItems": [
      {
        "label": "Subtotal",
        "type": "SUBTOTAL",
        "price": "11.00"
      },
      {
        "label": "Tax",
        "type": "TAX",
        "price": "1.00"
      }
    ],
    "currencyCode": "USD",
    "totalPriceStatus": "FINAL",
    "totalPrice": "12.00",
    "totalPriceLabel": "Total"
  },
  "newShippingOptionParameters": {
    "defaultSelectedOptionId": "shipping-001",
    "shippingOptions": [
      {
        "id": "shipping-001",
        "label": "Free: Standard shipping",
        "description": "Free Shipping delivered in 5 business days."
      }
    ]
  },
  "newOfferInfo": {
    "offers": [
      {
        "redemptionCode": "exampleCode",
        "description": "example description of offer"
      }
    ]
  },
  "error": {
    "reason": "SHIPPING_ADDRESS_UNSERVICEABLE",
    "message": "Cannot ship to the selected address",
    "intent": "SHIPPING_ADDRESS"
  }
}

MerchantInfo

This object provides information about the merchant that requests payment data.

Property Type Necessity Description
merchantId string Required A Google merchant identifier issued after registration with the Google Pay & Wallet Console. Required when PaymentsClient is initialized with an environment property of PRODUCTION. See Request production access for more information about the approval process and how to obtain a Google merchant identifier. The merchantID can have 12-18 characters.
merchantName string Optional Merchant name encoded as UTF-8. Merchant name is rendered in the payment sheet. In TEST environment, or if a merchant isn't recognized, a “Pay Unverified Merchant” message is displayed in the payment sheet.

Example

The following example shows a merchantInfo object with merchantName.

"merchantInfo": {
    "merchantName": "Example Merchant"
}

PaymentMethod

This object specifies one or more payment methods supported by the Google Pay API and accepted by your website.

Property Type Necessity Description
type string Required

A short identifier for the supported payment method. CARD is the only supported value for this parameter.

parameters object Required Parameters required to configure the provided payment method type. See CardParameters for more information about expected values for the CARD payment method.
tokenizationSpecification PaymentMethodTokenizationSpecification Optional

Configure an account or decryption provider to receive payment information.

This property is required for the CARD payment method.

This property has no effect if it's included as part of an IsReadyToPayRequest.

CARD

The following example shows you how to support payment cards and Android device tokens from all supported card networks. This example shows tokenization through an example gateway.

{
  "type": "CARD",
  "parameters": {
    "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
    "allowedCardNetworks": ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"]
  },
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "example",
      "gatewayMerchantId": "exampleGatewayMerchantId"
    }
  }
}

TokenizationSpecification

This object allows you to configure an account to receive chargeable payment information.

Property Type Necessity Description
type string Required

A payment method tokenization type is supported for the given PaymentMethod. For CARD payment method, use PAYMENT_GATEWAY or DIRECT.

parameters object Required Parameters specific to the selected payment method tokenization type.

Gateway

To retrieve payment and customer information from a payment gateway that's supported by the Google Pay API, set type to PAYMENT_GATEWAY. Define the parameters properties as described by your gateway. Typical properties include the gateway's identifier, which is issued by Google, and your gateway account ID, which is provided by the gateway.

The following example shows how to retrieve information from a payment gateway:

"tokenizationSpecification": {
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "example",
    "gatewayMerchantId": "exampleGatewayMerchantId"
  }
}

Use the following table to find the specific "gateway": and "gatewayMerchantId": values for your supported gateway.

Gateway Parameters and documents
ABA PayWay
  "gateway": "ababank"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

accept.blue
  "gateway": "acceptblue"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

ACI
  "gateway": "aciworldwide"
  "gatewayMerchantId": "YOUR_ENTITY_ID"

Developer docs

ACpay
  "gateway": "acpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Acquired.com
  "gateway": "acquired"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Direct

To decrypt a response directly on your servers, set type to DIRECT.

Property Type Necessity Description
protocolVersion string Required The version of the encryption/signature protocol expected in the response. Currently, ECv2 is supported. See Payment data cryptography for more information about available encryption and signature protocols.
publicKey string Required Base64-encoded elliptic curve public key. See the Encryption public key format section in our merchant cryptography documentation for more information.
Example

In the following example, the publicKey value is abbreviated for readability.

"tokenizationSpecification": {
  "type": "DIRECT",
  "parameters": {
    "protocolVersion": "ECv2",
    "publicKey": "BOdoXP1aiNp.....kh3JUhiSZKHYF2Y="
  }
}

Card Parameters

This object allows you to define the accepted payment card types. Google filters a payer's available payment cards based on your configured options.

Property Type Necessity Description
allowedAuthMethods string[ ] Required

Fields supported to authenticate a card transaction.

  • PAN_ONLY: This authentication method is associated with payment cards stored on file with the user's Google Account. Returned payment data includes personal account number (PAN) with the expiration month and the expiration year.
  • CRYPTOGRAM_3DS: This authentication method is associated with cards stored as Android device tokens. Returned payment data includes a 3-D Secure (3DS) cryptogram generated on the device.
allowedCardNetworks string[ ] Required

One or more card networks that you support, also supported by the Google Pay API.

  • AMEX
  • DISCOVER
  • INTERAC
  • JCB
  • MASTERCARD
  • VISA
allowPrepaidCards boolean Optional Set to false if you don't support prepaid cards. Default: The prepaid card class is supported for the card networks specified.
allowCreditCards boolean Optional (Required for UK Gambling merchants) Set to false if you don't support credit cards. Default: The credit card class is supported for the card networks specified.
assuranceDetailsRequired boolean Optional Set to true to request assuranceDetails. This object provides information about the validation performed on the returned payment data.
billingAddressRequired boolean Optional Set to true if you require a billing address. A billing address should only be requested if it's required to process the transaction. Additional data requests can increase friction in the checkout process and lead to a lower conversion rate.
billingAddressParameters BillingAddressParameters Optional The expected fields returned if billingAddressRequired is set to true.

Example for CARD

The following is an example of how to support all available card networks and card authentication methods:

{
  "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
  "allowedCardNetworks": ["AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"],
  "assuranceDetailsRequired": true
}

BillingAddressParameters

This object allows you to set additional fields to be returned for a requested billing address.

Property Type Necessity Description
format string Optional

Billing address format required to complete the transaction.

  • MIN: Name, country code, and postal code (default).
  • FULL: Name, street address, locality, region, country code, and postal code.
phoneNumberRequired boolean Optional Set to true if a phone number is required to process the transaction.

Example

The following is an example for a request of a minimal version of the billing address, which is the current default value of the property.

{
  "format": "MIN"
}

ShippingAddressParameters

This object is used to set shipping restrictions.

Property Type Necessity Description
allowedCountryCodes string[ ] Optional ISO 3166-1 alpha-2 country code values of the countries where shipping is allowed. If this object isn't specified, all shipping address countries are allowed.
phoneNumberRequired boolean Optional Set to true if a phone number is required for the provided shipping address.

Example

The following example is a request for a shipping address in the United States.

{
  "allowedCountryCodes": ["US"]
}

ShippingOptionParameters

Property Type Necessity Description
shippingOptions SelectionOption Required All of the shipping options available for the current request.
defaultSelectedOptionId String Optional An identifier to the default selected shipping option. If this field isn't provided, the first option is the default option.

Example

The following example shows you all of the shipping options for the payment sheet and a default shipping option.

{
  "defaultSelectedOptionId": "shipping-001",
  "shippingOptions": [
    {
      "id": "shipping-001",
      "label": "$0.00: Free shipping",
      "description": "Free Shipping delivered in 5 business days."
    },
    {
      "id": "shipping-002",
      "label": "$1.99: Standard shipping",
      "description": "Standard shipping delivered in 3 business days."
    },
    {
      "id": "shipping-003",
      "label": "$1000: Express shipping",
      "description": "Express shipping delivered in 1 business day."
    }
  ]
}

SelectionOption

Property Type Necessity Description
id String Required The developer can put any value that needs to be returned in PaymentData.
label String Required The label to be displayed as the option.
description String Optional A descriptive text that is displayed below the option label.

Example

The following example shows a shipping option.

{
  "id": "shipping-003",
  "label": "$10: Express shipping",
  "description": "Express shipping delivered in 1 business day."
}

TransactionInfo

This object describes the transaction details. The following table details the properties of the object.

Property Type Necessity Description
currencyCode string Required

The ISO 4217 alphabetic currency code.

countryCode string Optional (required for EEA countries)

The ISO 3166-1 alpha-2 country code where the transaction is processed. This property is required for merchants who process transactions in European Economic Area (EEA) countries and any other countries that are subject to Strong Customer Authentication (SCA). Merchants must specify the acquirer bank country code.

transactionId string Optional

A unique ID that identifies a facilitation attempt. Merchants can use an existing ID or generate a specific one for Google Pay facilitation attempts.

totalPriceStatus string Required

The status of the total price used:

  • ESTIMATED: Total price might adjust based on the details of the response, such as sales tax collected that's based on a billing address.
  • FINAL: Total price doesn't change from the amount presented to the shopper.
totalPrice string Required

Total monetary value of the transaction with an optional decimal precision of two decimal places.

The format of the string should follow the regex format: ^[0-9]+(\.[0-9][0-9])?$

displayItems DisplayItem[ ] Optional*

A list of cart items shown in the payment sheet (e.g. subtotals, sales taxes, shipping charges, discounts etc.). This is typically populated in the payment sheet if you use Authorize Payments or Dynamic Price Updates.

This field is required if you implement support for Authorize Payments or Dynamic Price Updates.

totalPriceLabel string Optional*

Custom label for the total price within the display items.

This field is required if displayItems are defined.

checkoutOption string Optional

Affects the submit button text displayed in the Google Pay payment sheet.

  • DEFAULT: Standard text applies for the given totalPriceStatus (default).
  • COMPLETE_IMMEDIATE_PURCHASE: The selected payment method is charged immediately after the payer confirms their selections. This option is only available when totalPriceStatus is set to FINAL.

Final price example

The following is an example of a final price in United States dollars.

"transactionInfo": {
  "currencyCode": "USD",
  "countryCode": "US",
  "totalPriceStatus": "FINAL",
  "totalPrice": "12.00",
  "checkoutOption": "COMPLETE_IMMEDIATE_PURCHASE"
}

DisplayItem

Property Type Necessity Description
label String Required The label to be displayed for the given option.
type String Required

Type of displayed line item:

  • LINE_ITEM
  • SUBTOTAL
price String Required The monetary value of the cart item with an optional decimal precision of two decimal places. Negative values are allowed.
status String Optional

The following variables define price variance:

  • FINAL
  • PENDING

Default to FINAL if not provided.

Example

This example shows a list of cart items that can be shown from the payment sheet.

{
  "displayItems": [
    {
      "label": "Subtotal",
      "type": "SUBTOTAL",
      "price": "11.00"
    },
    {
      "label": "Tax",
      "type": "TAX",
      "price": "1.00"
    },
    {
      "label": "Shipping",
      "type": "LINE_ITEM",
      "price": "0", // Won't be displayed since status is PENDING
      "status": "PENDING"
    }
  ]
}

OfferDetail

This object provides information about any Offers currently applied to a transaction.

Property Type Necessity Description
redemptionCode string Required The promotional code associated with the Offer. Should be the same as the code entered into the payment sheet.
description string Required A description of the promotion applied by the Offer code.

Example

The following example shows an OfferDetail object with redemptionCode and description values.

"offerDetail": {
    "redemptionCode": "PROMOTIONALCODE",
    "description": "An excellent discount"
}

OfferInfo

This object provides information about any Offers currently applied to a transaction.

Property Type Necessity Description
offers OfferDetail[ ] Required All of the applied offers for the current transaction

ButtonOptions

This object lets you configure a Google Pay payment button. For more information about button types, colors, and display requirements, see Google's Brand guidelines.

Property Type Necessity Description
onClick

function or Object

Required An event listener callback to call when a click event is delivered to the <button> target.
allowedPaymentMethods PaymentMethod[ ] Optional

Determines which payment methods can be displayed on the Google Pay button. If this parameter is not set, any payment methods saved to the user's account may be displayed.

A tokenizationSpecification isn't required to determine a viewer's readiness to pay. Provide all required parameters properties for each supported PaymentMethod.

buttonColor string Optional
  • default: A Google-selected default value. Currently black but it may change over time (default).
  • black: A black button suitable for use on white or light backgrounds.
  • white: A white button suitable for use on colorful backgrounds.
buttonType string Optional
  • book: The "Book with Google Pay" payment button.
  • buy: The "Buy with Google Pay" payment button (default).
  • checkout: The "Checkout with Google Pay" payment button.
  • donate: The "Donate with Google Pay" payment button.
  • order: The "Order with Google Pay" payment button.
  • pay: The "Pay with Google Pay" payment button.
  • plain: The Google Pay payment button without the additional text.
  • subscribe: The "Subscribe with Google Pay" payment button.
buttonRadius number Optional

Specifies the button corner radius in pixels. The minimum is 0 and the maximum depends on the height of the button. If the height is 40px (default height) then the maximum value for the buttonRadius is 20.

buttonLocale string Optional

The ISO 639-1 code represents the desired button language.

Supported locales include en, ar, bg, ca, cs, da, de, el, es, et, fi, fr, hr, id, it, ja, ko, ms, nl, no, pl, pt, ru, sk, sl, sr, sv, th, tr, uk, and zh.

The default is set to the browser or operating system language settings.

buttonSizeMode string Optional
  • static: Button has a static width and height (default).
  • fill: Button size changes to fill the size of its container.
buttonRootNode HTMLDocument or ShadowRoot Optional

Specifies how to append Google Pay resources, such as <style> tags, in the DOM. Its default value is document.

Use this property to integrate Google Pay with Web Components and the shadow DOM. Set its value to the result of container.getRootNode().

Example

This example generates a Google Pay payment button with a click event handler and default display options.

{
  onClick: onGooglePaymentButtonClicked
}