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: "0123456789"
  },
  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 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 authorization 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:
  • PAYMENT_AUTHORIZATION
  • SHIPPING_ADDRESS
  • SHIPPING_OPTION
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"
  },
  "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:
  • 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
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"
  },
  newShippingOptions: {
    defaultSelectedOptionId: "shipping-001",
    shippingOptions: [
      {
        "id": "shipping-001",
        "label": "Free: Standard shipping",
        "description": "Free Shipping delivered in 5 business days."
      }
    ]
  },
  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 your website is approved by Google. Required when PaymentsClient is initialized with an environment property of PRODUCTION. See the Integration checklist for more information about the approval process and how to obtain a Google merchant identifier.
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. Only CARD and PAYPAL currently are supported entries.

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. See PAYPALParameters for more information about expected values for the PAYPAL 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"
    }
  }
}
PAYPAL

The following example shows you how to support PAYPAL payment method.

{
  “type”: “PAYPAL”,
  parameters: {
  	"purchase_context": {
    	     "purchase_units": [{
        		"payee": {
          		      "merchant_id": "PAYPAL_ACCOUNT_ID"
                      	   }
       	       } ]
  	  }
    },
   “tokenizationSpecification”: {
	type: “DIRECT”  }
}


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. For PAYPAL PaymentMethod, use DIRECT with no parameter.

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

Gateway

Set type to PAYMENT_GATEWAY to retrieve payment and customer information from a payment gateway that's supported by the Google Pay API. 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 your 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 your specific "gateway": and "gatewayMerchantId": values for your supported gateway.

Gateway Parameters and documents
ACI
  "gateway": "aciworldwide"
  "gatewayMerchantId": "YOUR_ENTITY_ID"

Developer docs

Adyen
  "gateway": "adyen"
  "gatewayMerchantId": "YOUR_MERCHANT_ACCOUNT_NAME"

Developer docs

Alfa-Bank
  "gateway": "alfabank"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Assist
  "gateway": "assist"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Blue Media
  "gateway": "bluemedia"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

BlueSnap
  "gateway": "bluesnap"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Braintree
  "gateway": "braintree"
  "braintree:apiVersion": "v1"
  "braintree:sdkVersion": "braintree.client.VERSION"
  "braintree:merchantId": "YOUR_BRAINTREE_MERCHANT_ID"
  "braintree:clientKey": "YOUR_BRAINTREE_TOKENIZATION_KEY"

Developer docs

Braspag
  "gateway": "cielo"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

CardConnect
  "gateway": "cardconnect"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Cathay United Bank
  "gateway": "cathaybk"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Chase Paymentech
  "gateway": "chase"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Checkout.com
  "gateway": "checkoutltd"
  "gatewayMerchantId": "YOUR_PUBLIC_KEY"

Developer docs

CloudPayments
  "gateway": "cloudpayments"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Computop
  "gateway": "computop"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Cybersource
  "gateway": "cybersource"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Datatrans
  "gateway": "datatrans"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Dotpay
  "gateway": "dotpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

EasyPay
  "gateway": "easypay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

EBANX
  "gateway": "ebanx"
  "gatewayMerchantId": "YOUR_PUBLIC_INTEGRATION_KEY"

Developer docs

eCard
  "gateway": "ecard"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

ECPay
  "gateway": "ecpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

eGHL
  "gateway": "eghl"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

eSafe
  "gateway": "esafe"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

Evo Payment Gateway
  "gateway": "evopaymentgateway"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

Fat Zebra
  "gateway": "fatzebra"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

First Data
  "gateway": "firstdata"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Gestpay
  "gateway": "gestpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Global One Pay
  "gateway": "globalonepay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

Global Payments
  "gateway": "globalpayments"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

GMO Payment Gateway
  "gateway": "gmopg"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

GoPay
  "gateway": "gopay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

GP Webpay
  "gateway": "gpwebpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

HiTrust
  "gateway": "hitrustpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

IMSolutions
  "gateway": "imsolutions"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

iPay88
  "gateway": "ipay88"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

iQmetrix
  "gateway": "iqmetrixpaymentservicesgateway"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

JudoPay
  "gateway": "judopay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

LogPay
  "gateway": "logpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Lyra
  "gateway": "lyra"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Mastercard Payment Gateway Services
  "gateway": "mpgs"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

MOBI.Money
  "gateway": "mobimoney"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Molpay
  "gateway": "molpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

Moneris
  "gateway": "moneris"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Moneta
  "gateway": "moneta"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

Monext
  "gateway": "monext"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

Money.Mail.Ru
  "gateway": "moneymailru"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Multicarta
  "gateway": "mulitcarta"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Mundipagg
  "gateway": "mundipagg"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

MyCheck
  "gateway": "mycheck"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

MyPay
  "gateway": "mypay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

No developer docs available

Newebpay
  "gateway": "newebpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Nexi
  "gateway": "nexi"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

NMI
  "gateway": "creditcall"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Nuvei
  "gateway": "nuvei"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

PayLane
  "gateway": "paylane"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Payler
  "gateway": "payler"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Paysafe
  "gateway": "paysafe"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Payture
  "gateway": "payture"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

PayU
  "gateway": "payu"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Portmone
  "gateway": "portmonecom"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Przelewy24
  "gateway": "przelewy24"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

RBK.money
  "gateway": "rbkmoney"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Redsys
  "gateway": "redsys"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Sberbank
  "gateway": "sberbank"
  "gatewayMerchantId": "YOUR_ORGANIZATION_NAME"

Developer docs

Sipay
  "gateway": "sipay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Softbank Payment Service
  "gateway": "sbps"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Solid
  "gateway": "solid"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Sony Payment Services
  "gateway": "sonypaymentservices"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Square
  "gateway": "square"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Stripe
  "gateway": "stripe"
  "stripe:version": "2018-10-31"
  "stripe:publishableKey": "YOUR_PUBLIC_STRIPE_KEY"

Developer docs

TapPay
  "gateway": "tappay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Tinkoff
  "gateway": "tinkoff"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

TPay.com
  "gateway": "tpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Uniteller
  "gateway": "uniteller"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Vantiv
  "gateway": "vantiv"
  "vantiv:merchantPayPageId": "YOUR_PAY_PAGE_ID"
  "vantiv:merchantOrderId": "YOUR_ORDER_ID"
  "vantiv:merchantTransactionId": "YOUR_TRANSACTION_ID"
  "vantiv:merchantReportGroup": "*web"

Developer docs

Veritrans
  "gateway": "veritrans"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Vindicia
  "gateway": "vindicia"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

WayForPay
  "gateway": "wayforpay"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Wirecard
  "gateway": "wirecard"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Worldnet
  "gateway": "worldnet"
  "gatewayMerchantId": "YOUR_GATEWAY_MERCHANT_ID"

Developer docs

Worldpay
  "gateway": "worldpay"
  "gatewayMerchantId": "YOUR_WORLDPAY_MERCHANT_ID"

Developer docs

Yandex.Checkout
  "gateway": "yandexcheckout"
  "gatewayMerchantId": "YOUR_SHOP_ID"

Developer docs

Direct

Set type to DIRECT to decrypt a response directly on your servers. This configuration has additional data security requirements from Google and additional PCI DSS compliance complexity.

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.
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"]
}

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: "0",
  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 a transaction that determines a payer's ability to pay. It's used to present a payment authorization dialog. The following table details the properties of the object.

Property Type Necessity Description
currencyCode string Required ISO 4217 alphabetic currency code.
countryCode string Optional (Required for EEA countries)

ISO 3166-1 alpha-2 country code where the transaction is processed. This is required for merchants based in European Economic Area (EEA) countries.

transactionId string Optional A unique ID that identifies a transaction attempt. Merchants may use an existing ID or generate a specific one for Google Pay transaction attempts. This field is required when you send callbacks to the Google Transaction Events API.
totalPriceStatus string Required

The status of the total price used:

  • NOT_CURRENTLY_KNOWN: Used for a capability check. Do not use this property if the transaction is processed in an EEA country.
  • ESTIMATED: Total price may adjust based on the details of the response, such as sales tax collected based on a billing address.
  • FINAL: Total price doesn't change from the amount presented to the shopper.
totalPrice string Optional

Total monetary value of the transaction with an optional decimal precision of two decimal places. This field is required unless totalPriceStatus is set to NOT_CURRENTLY_KNOWN.

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

displayItems DisplayItem[] Optional All of the available charges for the current payment request. This is only 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.
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.

{
  displayItems: [
    {
      label: "Subtotal",
      type: "SUBTOTAL",
      price: "11.00",
    },
    {
      label: "Tax",
      type: "TAX",
      price: "1.00",
    }
  ],
    currencyCode: "USD",
    countryCode: "US",
    totalPriceStatus: "FINAL",
    totalPrice: "12.00",
    totalPriceLabel: "Total",
    checkoutOption: "DEFAULT",
    newShippingOptions: {
 	    defaultSelectedOptionId: "shipping-001",
      shippingOptions: [
        {
          "id": "shipping-001",
          "label": "Free: Standard shipping",
          "description": "Free Shipping delivered in 5 business days."
        }
      ]
    },
    error: {
   	  reason: "SHIPPING_ADDRESS_UNSERVICEABLE",
      message: "Cannot ship to the selected address",
      intent: "SHIPPING_ADDRESS"
    }
}

ButtonOptions

This object allows you to 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.
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
  • long: "Buy with Google Pay" button (default). A translated button label may appear if a language specified in the viewer's browser matches an available language.
  • short: Google Pay payment button without the "Buy with" text.

PayPal Parameters

This object allows you to define the PayPal parameters.

Property Type Necessity Description
purchase_context PurchaseContext Required Use information about the order for the description.

Example for PayPal

The following is an example of how to support the PayPal payment method:

{
  "purchase_context": {
    "purchase_units": [
      {
        "payee": {
          "merchant_id": "PAYPAL_ACCOUNT_ID"
        }
      }
    ]
  }
}

PurchaseContext

This object provides information about the order.

Property Type Necessity Description
purchase_units PurchaseUnit[] Required Describes the contract between the customer and the merchant.

PurchaseUnit

This object describes a contract between the PayPal customer and the PayPal merchant. See purchase_unit in the PayPal Order API documentation for more information.

Property Type Necessity Description
payee Payee Required The receipt of funds for this transaction.

Payee

This object provides information about the merchant that receives funds. See payee in the PayPal Orders API reference documentation for more details.

See Optional parameters for other supported parameters.

Example for PayPal

The following is an example of how to support the PayPal payment method.

{
  “type”: “PAYPAL”,
  parameters: {
  	"purchase_context": {
    	     "purchase_units": [{
        		"payee": {
          		      "merchant_id": "PAYPAL_ACCOUNT_ID"
                      	   }
       	       } ]
  	  }
    },
   “tokenizationSpecification”: {
	type: “DIRECT”  }
}

Example

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

{
  onClick: onGooglePaymentButtonClicked
}