JSON request objects

This reference page describes the Google Pay API request object options to use with your application.

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 isReadyToPay() class method will return true if the current viewer is ready 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 app'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 Optional 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.
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 shippingAddressParameters is set to true, specify shipping address restrictions.

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

MerchantInfo

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

Property Type Necessity Description
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 app.

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
  public static final HashMap<String, String> DIRECT_TOKENIZATION_PARAMETERS =
      new HashMap<String, String>() {{
        put("protocolVersion", "ECv2");
        put("publicKey", DIRECT_TOKENIZATION_PUBLIC_KEY);
      }};
  private static JSONObject getDirectTokenizationSpecification()
      throws JSONException, RuntimeException {
    if (Constants.DIRECT_TOKENIZATION_PARAMETERS.isEmpty()
        || Constants.DIRECT_TOKENIZATION_PUBLIC_KEY.isEmpty()
        || Constants.DIRECT_TOKENIZATION_PUBLIC_KEY == null
        || Constants.DIRECT_TOKENIZATION_PUBLIC_KEY == "REPLACE_ME") {
      throw new RuntimeException(
          "Please edit the Constants.java file to add protocol version & public key.");
    }
    JSONObject tokenizationSpecification = new JSONObject();

    tokenizationSpecification.put("type", "DIRECT");
    JSONObject parameters = new JSONObject(Constants.DIRECT_TOKENIZATION_PARAMETERS);
    tokenizationSpecification.put("parameters", parameters);

    return tokenizationSpecification;
  }

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

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])?$

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

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
ButtonConstants.ButtonType Int 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.
ButtonConstants.ButtonTheme Int Optional
  • DARK (default)
  • LIGHT
cornerRadius Int Optional

The radius, in dp units, for the rounded corners on the button.

allowedPaymentMethods String 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.

Example

JSONArray paymentMethods = new JSONArray().put(getBaseCardPaymentMethod());
googlePayPaymentButton.initialize(
       ButtonOptions.newBuilder()
               .setButtonTheme(ButtonConstants.ButtonTheme.DARK)
               .setButtonType(ButtonConstants.ButtonType.BUY)
               .setCornerRadius(100)
               .setAllowedPaymentMethods(paymentMethods.toString())
               .build()