# Google Pay for Unified Payments API

To accept Google Pay payments, you must:

1. Retrieve the Google Pay payment data.
2. Tokenize the payment data.
3. Request a Google Pay payment.

If your [PCI compliance](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/pci-compliance.md) enables you to handle encrypted data directly, you can decrypt the Google Pay token yourself and send it to Checkout.com for processing.

---

## Before you start

1. Follow the integration guides, depending on the platform you are integrating:
    - [Android](https://developers.google.com/pay/api/android/overview)
    - [Web](https://developers.google.com/pay/api/web/overview)
2. Register your domain and obtain your Google merchant ID through the [Google Pay & Wallet Console](https://pay.google.com/business/console/). For web integrations, you can use the [Enroll an entity to the Google Pay Service](https://api-reference.checkout.com/#tag/Google-Pay) endpoint instead.

> **Note**
>
> Android integrations do not support domain registration through the [Enroll an entity to the Google Pay Service](https://api-reference.checkout.com/#tag/Google-Pay) endpoint.

---

## Retrieve Google Pay payment data

When you submit a payment data request to the Google Pay API, you must configure your `PaymentDataRequest` Google pay object setting the following parameters:

- `gateway` set to `checkoutltd`
- `gatewayMerchantId` set to your public key
- `allowedCardNetworks` set to the card schemes you want to accept

### Request example

**Android Google Pay API request**

```kotlin
private fun cardParameters(): JSONObject {
    return JSONObject().apply {
        put("allowedAuthMethods", JSONArray(listOf("PAN_ONLY", "CRYPTOGRAM_3DS")))
        put("allowedCardNetworks", JSONArray(listOf("AMEX", "DISCOVER", "MASTERCARD", "VISA")))
    }
}

private fun gatewayTokenizationSpecification(): JSONObject {
    return JSONObject().apply {
        put("type", "PAYMENT_GATEWAY")
        put("parameters", JSONObject(mapOf(
            "gateway" to "checkoutltd",
            "gatewayMerchantId" to "pk_sbox_o2nulev4vbo43i4qkb5p7lfijap"
        )))
    }
}

private fun cardPaymentMethod(): JSONObject {
    return JSONObject().apply {
        put("type", "CARD")
        put("parameters", cardParameters())
        put("tokenizationSpecification", gatewayTokenizationSpecification())
    }
}
```

For more information about Google Pay API `PaymentDataRequest` object, see the Google Developer documentation for [Android](https://developers.google.com/pay/api/android/reference/request-objects)

**Web Google Pay API request**

```json
{
  "type": "CARD",
  "parameters": {
    "allowedAuthMethods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
    "allowedCardNetworks": ["AMEX", "DISCOVER", "MASTERCARD", "VISA"]
  },
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "checkoutltd",
      "gatewayMerchantId": "pk_sbox_o2nulev4vbo43i4qkb5p7lfijap"
    }
  }
}
```
For more information about Google Pay API `PaymentDataRequest` object, see the Google Developer documentation for [Web](https://developers.google.com/pay/api/web/object-reference)

### Response example

The `tokenizationData.token` property returned in the `PaymentMethodData` object contains the payment data.

```json
{
  "type": "CARD",
  "description": "Visa••••1234",
  "info": {
    "cardNetwork": "VISA",
    "cardDetails": "1234"
  },
  "tokenizationData": {
    "type": "PAYMENT_GATEWAY",
    "token": "examplePaymentMethodToken"
  }
}
```

## Tokenize the Google Pay payment data

When you receive the payment data from Google, call the [Request a token](https://api-reference.checkout.com/tag/Tokens/#operation/requestAToken) endpoint to tokenize the encrypted payment data.

> **Note**
>
> To process Google Pay transactions, you must authenticate your request using the same public key you provided to the Google Pay API in the `gatewayMerchantId` parameter.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/tokens`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/tokens`

### Request example

```json
{
  "type": "googlepay",
  "token_data": {
    "protocolVersion": "ECv1",
    "signature": "TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ",
    "signedMessage": "{\"encryptedMessage\": \"ZW5jcnlwdGVkTWVzc2FnZQ==\", \"ephemeralPublicKey\": \"ZXBoZW1lcmFsUHVibGljS2V5\", \"tag\": \"c2lnbmF0dXJl\"}"
  }
}
```

### Response example

```json
{
  "type": "googlepay",
  "token": "tok_ubfj2q76miwundwlk72vxt2i7q",
  "expires_on": "2026-09-15T11:14:15Z"
}
```

Use the token value from the `token` field in your payment request.

---

## Request a payment

Call the [Request a payment](https://api-reference.checkout.com/tag/Payments#operation/requestAPaymentOrPayout) endpoint, setting the following fields, depending on the token format you want to use:

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

**Using the Checkout.com token**

To request a payment using the Checkout.com token, set the following fields:

- `source.type` set to `token`
- `token` set to the value of the `token` field in you got in the tokenize the Google Pay payment data response.

### Request example

```json
{
  "source": {
    "type": "token",
    "token": "tok_ubfj2q76miwundwlk72vxt2i7q"
  },
  "amount": 1000,
  "currency": "USD"
}
```

**Using a pre-decrypted Google Pay token**

Checkout.com supports payments using Google Pay tokens that you have decrypted. To use this feature, set the following fields:

- `source.type` set to `network_token`
- `token_type` set to `googlepay`.

This source type lets you provide the token details, as well as the cryptogram and [Electronic Commerce Indicator (ECI)](https://www.checkout.com/docs/developer-resources/codes/eci-values.md) value obtained from the Google Pay token.

> **Note**
>
> To decrypt the Google Pay token yourself, set `tokenizationSpecification.type` to `DIRECT` when you [retrieve Google Pay payment data](#Retrieve_Google_Pay_payment_data).

### Request example

```json
{
  "source": {
    "type": "network_token",
    "token": "4242424242424242",
    "token_type": "googlepay",
    "expiry_month": "10",
    "expiry_year": "2025",
    "eci": "06",
    "cryptogram": "AgAAAAAAAIR8CQrXcIhbQAAAAAA="
  },
  "amount": 1000,
  "currency": "USD"
}
```

### Response example

If the `approved` field is `true`, your authorization was successful. A failed authorization can indicate the payment used an invalid or expired card, or a card with an insufficient available balance.

A successful response includes a `payment_account_reference` value, which is a unique reference to the underlying card for network tokens. If the card scheme provides an `eci` value, the response includes it. The value indicates the security level that the card scheme decided to request the payment with.

---

## Test Google Pay

To test Google Pay payments, first [create a test Checkout.com account](https://www.checkout.com/get-test-account).

Use Google's built-in [test card suite](https://developers.google.com/pay/api/android/guides/resources/test-card-suite#mock-testing) to add mock test cards to your wallet and simulate different payment flows.

You can [disable the test card suite](https://developers.google.com/pay/api/android/guides/resources/test-card-suite#disable-the-test-card-suite) to test with your real cards. In this case, Google mocks the response using a generic test card.

If you perform a payment with a real card in Google's sandbox environment, Google Pay provides a test card in the encrypted payment data. This ensures that no actual transaction takes place. This automatic payment data encryption for testing is unique to Google Pay. Do not perform tests for any other payment method using real card numbers or card details in your sandbox environment.

> **Note**
>
> Google validates your Google merchant ID in the Production environment, but not in the Sandbox environment. Register with the [Google Pay & Wallet Console](https://pay.google.com/business/console/) and obtain a valid merchant ID before moving to Production. For web integrations, you can optionally register your domain and merchant ID through the [Enroll an entity to the Google Pay Service](https://api-reference.checkout.com/#tag/Google-Pay) endpoint instead.