The Google Pay API introduced new object structures for
[`PaymentDataRequest`](https://developers.google.com/pay/api/web/reference/request-objects#PaymentDataRequest) and
[`IsReadyToPayRequest`](https://developers.google.com/pay/api/web/reference/request-objects#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](https://developers.google.com/pay/api/web/reference/request-objects#PaymentMethod)
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

```javascript
{
  allowedPaymentMethods: [
    'CARD',
    'TOKENIZED_CARD'
  ],
  cardRequirements: {
    allowedCardNetworks: [
      'AMEX',
      'DISCOVER',
      'JCB',
      'MASTERCARD',
      'VISA'
    ]
  }
}
```

### apiVersion 2

```javascript
{
  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`](https://developers.google.com/pay/api/web/reference/request-objects#IsReadyToPayRequest) for a `CARD`
[payment method](https://developers.google.com/pay/api/web/reference/request-objects#PaymentMethod "Object reference: 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](https://developers.google.com/pay/api/web/reference/request-objects#PaymentMethodTokenizationSpecification "Object reference: PaymentMethodTokenizationSpecification")
inside the `CARD` payment method.

### apiVersion 1

```javascript
{
  paymentMethodTokenizationParameters: {
    tokenizationType: 'PAYMENT_GATEWAY',
    parameters: {
      'gateway': 'example',
      'gatewayMerchantId': 'exampleMerchantId'
    }
  }
}
```

### apiVersion 2

```javascript
{
  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`](https://developers.google.com/pay/api/web/reference/request-objects#MerchantInfo) object
with an optional merchant name.

### apiVersion 1

```javascript
{
  merchantId: '12345678901234567890'
}
```

### apiVersion 2

```javascript
{
  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`](https://developers.google.com/pay/api/web/reference/request-objects#BillingAddressParameters) object.

### apiVersion 1

```javascript
{
  cardRequirements: {
    billingAddressRequired: true,
    billingAddressFormat: 'FULL'
  },
  phoneNumberRequired: true
}
```

### apiVersion 2

```javascript
{
  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`](https://developers.google.com/pay/api/web/reference/request-objects#PaymentDataRequest) object.
The `shippingAddressRequirements` property has been renamed
[`shippingAddressParameters`](https://developers.google.com/pay/api/web/reference/request-objects#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

```javascript
{
  shippingAddressRequired: true,
  shippingAddressRequirements: {
    allowedCountryCodes: [
      'US',
      'CA'
    ]
  }
}
```

### apiVersion 2

```javascript
{
  shippingAddressRequired: true,
  shippingAddressParameters: {
    allowedCountryCodes: [
      'US',
      'CA'
    ]
  }
}
```

## PaymentData response

The [`PaymentData`](https://developers.google.com/pay/api/web/reference/response-objects#PaymentData) object response
for sites that set an `apiVersion` property value of `2` in
[`PaymentDataRequest`](https://developers.google.com/pay/api/web/reference/request-objects#PaymentDataRequest)
has changed to reference cards as one of multiple possible payment data responses.
The `apiVersion` and `apiVersionMinor` properties included in the
[`PaymentDataRequest`](https://developers.google.com/pay/api/web/reference/request-objects#PaymentDataRequest) object
appear in the
[`PaymentData`](https://developers.google.com/pay/api/web/reference/response-objects#PaymentData) response to indicate
the expected format.

### apiVersion 1

```javascript
{
  // no version specified
}
```

### apiVersion 2

```javascript
{
  apiVersion: 2,
  apiVersionMinor: 0
}
```

Information about a selected payment method and its tokenization is placed inside the
[`paymentMethodData`](https://developers.google.com/pay/api/web/reference/response-objects#PaymentMethodData) property.
Two properties have been removed from the card payment method's `cardInfo` object:
`cardClass` and `cardImageUri`.

### apiVersion 1

```javascript
{
  cardInfo: {
    cardDescription: 'Visa •••• 1234',
    cardNetwork: 'VISA',
    cardDetails: 1234
  },
  paymentMethodToken: {
    tokenizationType: 'PAYMENT_GATEWAY',
    token: 'examplePaymentMethodToken'
  }
}
```

### apiVersion 2

```javascript
{
  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

```javascript
{
  "paymentMethod": "TOKENIZED_CARD",
  "paymentMethodDetails": {
    "authMethod": "3DS",
    "dpan": "1111222233334444",
    "expirationMonth": 10,
    "expirationYear": 2020,
    "3dsCryptogram": "AAAAAA...",
    "3dsEciIndicator": "eci indicator"
  }
}
```

### apiVersion 2

```javascript
{
  "paymentMethod": "CARD",
  "paymentMethodDetails": {
    "authMethod": "CRYPTOGRAM_3DS",
    "pan": "1111222233334444",
    "expirationMonth": 10,
    "expirationYear": 2020,
    "cryptogram": "AAAAAA...",
    "eciIndicator": "eci indicator"
  }
}
```