Update to latest version

  • Google Pay API PaymentDataRequest and IsReadyToPayRequest objects have been updated with new structures in version 2, requiring updates to existing integrations.

  • Version 2 introduces explicit API versioning and expands payment methods beyond just cards, requiring adjustments to allowedPaymentMethods and allowedAuthMethods.

  • Payment method tokenization, Google merchant ID, billing address configuration, and shipping address parameters have been relocated within the new object structure.

  • The PaymentData response format has been revised to include API version information and nest card details within paymentMethodData.

  • Handling of encrypted message responses for tokenized cards requires updates to accommodate the new paymentMethod and paymentMethodDetails structure.

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