Are you interested in attending a Google Pay launchathon in your city? Let us know!

Object reference

Options for using the Google Pay API.

Request objects

PaymentOptions

Configure for a production environment once you have tested your implementation and are ready to receive payments from shoppers.

Property Type Necessity Description
environment string optional
  • PRODUCTION: return chargeable methods of payment when a valid Google merchant ID is specified.
  • TEST: dummy payment methods returned suitable for testing (default)

Example

Request dummy payment methods suitable for testing.

{
  environment: 'TEST'
}

IsReadyToPayRequest

Specify supported payment response types.

Property Type Necessity Description
allowedPaymentMethods string[] required

Specify support for a subset of available payment methods.

  • CARD: payment cards
  • TOKENIZED_CARD: Android device tokens

Example

Support payment cards and Android device tokens.

{
  allowedPaymentMethods: ['CARD', 'TOKENIZED_CARD']
}

PaymentDataRequest

Configure your site's support for the Google Pay API.

Property Type Necessity Description
merchantId string required A Google merchant identifier issued after your website is approved by Google. See Test and Deploy for more information.
transactionInfo TransactionInfo required The transaction amount requested.
paymentMethodTokenizationParameters PaymentMethodTokenizationParameters required The expected response from Google's servers. Payment information and customer data may be passed through your payment gateway or directly decrypted.
cardRequirements CardRequirements required Supported card networks, supported card types, and optional billing address information.
allowedPaymentMethods string[] required

Specify support for a subset of available payment methods.

  • CARD: Payment cards
  • TOKENIZED_CARD: Android device tokens
phoneNumberRequired boolean optional Set to true to request a phone number.
emailRequired boolean optional Set to true to request an email address.
shippingAddressRequired boolean optional Set to true to request a full shipping address.
shippingAddressRequirements ShippingAddressRequirements optional If shippingAddressRequired set to true, specify shipping address restrictions.

PaymentMethodTokenizationParameters

The Google Pay API can configure a response to be handled by a payments gateway supported by Google or a response decrypted by a merchant's servers for direct processing.

Gateway

Set tokenizationType to PAYMENT_GATEWAY to retrieve payment and customer information from a payment gateway supported by Google. Define parameters properties as described by your gateway; typical properties include the gateway's identifier issued by Google, your gateway account ID, and the version of your gateway's SDK used to process the response.

Example
paymentMethodTokenizationParameters: {
  tokenizationType: 'PAYMENT_GATEWAY',
  properties: {
    'gateway': 'example',
    'gatewayMerchantId': 'abc123'
   }
 }
    
Adyen
paymentMethodTokenizationParameters: {
  tokenizationType: 'PAYMENT_GATEWAY',
  properties: {
    'gateway': 'adyen',
    'gatewayMerchantId': 'YOUR_MERCHANT_ACCOUNT_NAME'
  }
}
    
Braintree
paymentMethodTokenizationParameters: {
  tokenizationType: 'PAYMENT_GATEWAY',
  properties: {
    'gateway': 'braintree',
    'braintree:apiVersion': 'v1',
    'braintree:merchantId': 'YOUR_BRAINTREE_MERCHANT_ID',
    'braintree:clientKey': 'YOUR_BRAINTREE_TOKENIZATION_KEY'
  }
}
    
EBANX
paymentMethodTokenizationParameters: {
  tokenizationType: 'PAYMENT_GATEWAY',
  properties: {
    'gateway': 'ebanx',
    'gatewayMerchantId': 'YOUR_PUBLIC_INTEGRATION_KEY'
  }
}
    
Paysafe
paymentMethodTokenizationParameters: {
  tokenizationType: 'PAYMENT_GATEWAY',
  properties: {
    'gateway': 'paysafe',
    'gatewayMerchantId': 'YOUR_PAYSAFE_TOKEN_API_KEY'
  }
}
    
Stripe
paymentMethodTokenizationParameters: {
  tokenizationType: 'PAYMENT_GATEWAY',
  properties: {
    'gateway': 'stripe',
    'stripe:version': Stripe.version,
    'stripe:publishableKey': 'YOUR_PUBLIC_STRIPE_KEY'
  }
}
    
Vantiv
paymentMethodTokenizationParameters: {
  tokenizationType: 'PAYMENT_GATEWAY',
  properties: {
    'gateway': 'vantiv',
    'vantiv:merchantPayPageId': 'YOUR_PAY_PAGE_ID',
    'vantiv:merchantOrderId': 'YOUR_ORDER_ID',
    'vantiv:merchantTransactionId': 'YOUR_TRANSACTION_ID',
    'vantiv:merchantReportGroup': '*web'
  }
}
    
WorldPay
paymentMethodTokenizationParameters: {
  tokenizationType: 'PAYMENT_GATEWAY',
  properties: {
    'gateway': 'worldpay',
    'gatewayMerchantId': 'YOUR_WORLDPAY_MERCHANT_ID'
  }
}
    

Direct

Set tokenizationType 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
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

The example publicKey value is abbreviated for readability.

paymentMethodTokenizationParameters: {
  tokenizationType: 'DIRECT',
  parameters: {
    publicKey: 'BOdoXP1aiNp.....kh3JUhiSZKHYF2Y='
  }
}

CardRequirements

Define the payment methods you accept. Google will filter a shopper's available payment methods and address selector based on your configured options.

Property Type Necessity Description
allowedCardNetworks string[] required

One or more card networks you support.

  • AMEX
  • DISCOVER
  • JCB
  • MASTERCARD
  • VISA
billingAddressRequired boolean optional Set to true if you require a billing address.
billingAddressFormat string optional

The expected fields returned if billingAddressRequired set to true.

  • MIN: name, country code, and postal code (default)
  • FULL: name, street address, locality, region, country code, and postal code

Example

Support all available card networks.

{
  allowedCardNetworks: ['AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA']
}

ShippingAddressRequirements

Set shipping restrictions. If not specified, all shipping addresses are allowed.

Property Type Necessity Description
allowedCountryCodes string[] optional ISO 3166-1 alpha-2 country code values of the countries to which shipping is allowed.

Example

Request a shopper provide an address in the United States.

{
  allowedCountryCodes: ['US']
}

TransactionInfo

Describe a transaction to determine a shopper's ability to pay or to present in a payment authorization dialog.

Property Type Necessity Description
totalPriceStatus string required

The status of the total price used:

  • NOT_CURRENTLY_KNOWN: used for a capability check
  • 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 will not 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. Required unless totalPriceStatus=NOT_CURRENTLY_KNOWN

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

currencyCode string optional ISO 4217 alphabetic currency code.

Example

A final price in United States dollars.

{
  totalPriceStatus: 'FINAL',
  totalPrice: '12.34',
  currencyCode: 'USD'
}

Response objects

PaymentData

A response object returned by Google after a shopper approves payment.

Property Type Always exists Description
paymentMethodToken PaymentMethodToken yes A chargeable token suitable for collecting payment through your gateway or processor.
cardInfo CardInfo yes Information about the card selected by the shopper.
shippingAddress UserAddress no Shipping address, if shippingAddressRequired was set to true in the PaymentDataRequest.
email string no Email address, if emailRequired was set to true in the PaymentDataRequest.

CardInfo

Information about the selected payment method.

Property Type Always exists Description
cardDescription string yes A payment method and method identifier suitable for communication to a shopper in a confirmation screen or purchase receipt.
cardClass string yes

Class of payment method:

  • CREDIT
  • DEBIT
cardDetails string yes The last four digits of the selected payment account number.
cardNetwork string yes The payment card network of the selected payment. Returned values match the formatting of allowedCardNetworks in CardRequirements.
billingAddress UserAddress no The billing address associated with the provided payment method, if billingAddressRequired was set to true in CardRequirements.

UserAddress

Information about a requested postal address. All properties are strings.

A MIN address format may be returned if billingAddressFormat is set to MIN. A shipping address is returned in the FULL address format. All properties in a MIN formatted response exist in a FULL formatted response.

Property Address format Description
name MIN The full name of the adressee.
postalCode MIN The postal or ZIP code.
countryCode MIN ISO 3166-1 alpha-2 country code.
phoneNumber MIN A telephone number, if phoneNumberRequired was set to true in the PaymentDataRequest.
companyName FULL The company name of the addressee.
address1 FULL The first line of the address.
address2 FULL The second line of the address.
address3 FULL The third line of the address.
address4 FULL The fourth line of the address.
address5 FULL The fifth line of the address.
locality FULL City, town, neighborhood, or suburb.
administrativeArea FULL A country subdivision (e.g. state or province).
sortingCode FULL The sorting code.

PaymentMethodToken

Token used for payment method.

Property Type Always exists Description
tokenizationType string yes Requested tokenizationType as set in paymentMethodTokenizationParameters
token string yes

A token response varies based on the tokenizationType.

Errors

PaymentsError

Errors returned by client JavaScript methods.

Property Type Description
statusCode string Short code describing the type of error.
statusMessage string Developer-facing message describing the error encountered and possible steps to correct.

Common errors

Errors you may encounter across all JavaScript methods.

Status Code Description
BUYER_ACCOUNT_ERROR The current Google user is unable to provide payment information.
DEVELOPER_ERROR A passed parameter was improperly formatted. An error message may appear in the browser console for all configured environments.
INTERNAL_ERROR General server error.

Send feedback about...

Google Pay API