The Google Pay API introduced new object structures for
PaymentDataRequest
and
IsReadyToPayRequest
objects in July 2018. This guide explains how to update
objects formatted for Google Pay API version 1 to objects formatted for version 2.
Payment methods
An API version is specified with each request object in version 2 of the Google Pay API.
Version 1 of the Google Pay API supported cards as the only form of payment. The
CARD
payment method
is one of multiple possible payment method options in version 2 of the Google Pay API. Sites that
previously specified an allowedPaymentMethods
value of CARD
must now set
an allowedAuthMethods
value of PAN_ONLY
. Sites that previously specified
an allowedPaymentMethods
value of TOKENIZED_CARD
must now set an
allowedAuthMethods
value of CRYPTOGRAM_3DS
.
Allowed card networks are specified alongside supported authentication methods for cards on those networks.
apiVersion 1
{ allowedPaymentMethods: [ 'CARD', 'TOKENIZED_CARD' ], cardRequirements: { allowedCardNetworks: [ 'AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA' ] } }
apiVersion 2
{ apiVersion: 2, apiVersionMinor: 0, allowedPaymentMethods: [{ type: 'CARD', parameters: { allowedAuthMethods: [ 'PAN_ONLY', 'CRYPTOGRAM_3DS' ], allowedCardNetworks: [ 'AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA' ] } }] }
Allowed card networks and their authentication methods are included in an
IsReadyToPayRequest
for a CARD
payment method.
Card payment data tokenization
The Google Pay API returns encrypted card data that's referenced by your specified gateway or
decrypted on your servers. Version 2 of the Google Pay API moves
payment method tokenization
inside the CARD
payment method.
apiVersion 1
{ paymentMethodTokenizationParameters: { tokenizationType: 'PAYMENT_GATEWAY', parameters: { 'gateway': 'example', 'gatewayMerchantId': 'exampleMerchantId' } } }
apiVersion 2
{ allowedPaymentMethods: [{ type: 'CARD', tokenizationSpecification: { type: 'PAYMENT_GATEWAY', parameters: { 'gateway': 'example', 'gatewayMerchantId': 'exampleMerchantId' } } }] }
Google merchant ID
A Google merchant ID was a top-level property in version 1 of the Google Pay API. Now, the
Google merchant ID is placed inside a
MerchantInfo
object
with an optional merchant name.
apiVersion 1
{ merchantId: '12345678901234567890' }
apiVersion 2
{ merchantInfo: { merchantId: '12345678901234567890' } }
Billing address
An optional billing address and a billing phone number are associated with a CARD
payment method.
If a site requests a billing address, any configuration related to the expected response is placed inside a
BillingAddressParameters
object.
apiVersion 1
{ cardRequirements: { billingAddressRequired: true, billingAddressFormat: 'FULL' }, phoneNumberRequired: true }
apiVersion 2
{ allowedPaymentMethods: [{ type: 'CARD', parameters: { billingAddressRequired: true, billingAddressParameters: { format: 'FULL', phoneNumberRequired: true } } }] }
Shipping address
An optional shipping address requirement remains at the top level of the
PaymentDataRequest
object.
The shippingAddressRequirements
property has been renamed
shippingAddressParameters
.
Earlier Google Pay API responses might have returned a phone number as part of the shipping address when a phone number was requested. A shipping phone number is no longer supported by the Google Pay API in any version. Any response handlers that expect a shipping phone number must be updated.
apiVersion 1
{ shippingAddressRequired: true, shippingAddressRequirements: { allowedCountryCodes: [ 'US', 'CA' ] } }
apiVersion 2
{ shippingAddressRequired: true, shippingAddressParameters: { allowedCountryCodes: [ 'US', 'CA' ] } }
PaymentData response
The PaymentData
object response
for sites that set an apiVersion
property value of 2
in
PaymentDataRequest
has changed to reference cards as one of multiple possible payment data responses.
The apiVersion
and apiVersionMinor
properties included in the
PaymentDataRequest
object
appear in the
PaymentData
response to indicate
the expected format.
apiVersion 1
{ // no version specified }
apiVersion 2
{ apiVersion: 2, apiVersionMinor: 0 }
Information about a selected payment method and its tokenization is placed inside the
paymentMethodData
property.
Two properties have been removed from the card payment method's cardInfo
object:
cardClass
and cardImageUri
.
apiVersion 1
{ cardInfo: { cardDescription: 'Visa •••• 1234', cardNetwork: 'VISA', cardDetails: 1234 }, paymentMethodToken: { tokenizationType: 'PAYMENT_GATEWAY', token: 'examplePaymentMethodToken' } }
apiVersion 2
{ paymentMethodData: { type: 'CARD', description: 'Visa •••• 1234', info: { cardNetwork: 'VISA', cardDetails: '1234' }, tokenizationData: { type: 'PAYMENT_GATEWAY', token: 'examplePaymentMethodToken' } } }
Encrypted message response
Sites that specify a DIRECT
payment method tokenization type and accept an
API version 1 payment method of TOKENIZED_CARD
must update how they handle the
decrypted encryptedMessage
property. The site must do this to continue to forward
Android device tokens authenticated with a 3-D Secure cryptogram and optional electronic commerce
indicator (ECI) to your gateway or processor. Cards are a paymentMethod
of
CARD
, with additional information about the selected card's authentication method in
paymentMethodDetails.authMethod
.
apiVersion 1
{ "paymentMethod": "TOKENIZED_CARD", "paymentMethodDetails": { "authMethod": "3DS", "dpan": "1111222233334444", "expirationMonth": 10, "expirationYear": 2020, "3dsCryptogram": "AAAAAA...", "3dsEciIndicator": "eci indicator" } }
apiVersion 2
{ "paymentMethod": "CARD", "paymentMethodDetails": { "authMethod": "CRYPTOGRAM_3DS", "pan": "1111222233334444", "expirationMonth": 10, "expirationYear": 2020, "cryptogram": "AAAAAA...", "eciIndicator": "eci indicator" } }