# Google Pay for Payment Setup API

To accept Google Pay payments, you must:

1. Create a payment setup.
2. Update the payment setup with the Google Pay token.
3. Confirm the payment.

---

## Create a payment setup

Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) endpoint.

> **Information**
>
> The Payment Setup API supports [idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md). You can safely retry API requests without the risk of duplicate requests.

> **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/setups`

**Sandbox**

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

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "GBP",
  "amount": 2000,
  "reference": "ORDER_01234",
  "description": "Google Pay payment",
  "payment_type": "Regular",
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

In the request body, provide the following:

- `processing_channel_id` – The [processing channel's](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-processing-channels.md) unique identifier
- `amount` – The payment amount
- `currency` – The payment currency

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 2000,
  "currency": "GBP",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Google Pay payment",
  "payment_methods": {
    "googlepay": {
      "status": "action_required",
      "flags": [
        "token_or_token_data_required"
      ]
    }
  },
  "available_payment_methods": [
    "googlepay"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

The response returns a `payment_methods` object, which contains the payment methods enabled on your account.

For Google Pay, `payment_methods` contains the following fields:

- `status` – The [status of the payment method](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api#Payment_method_status).
- `flags` – An array of error codes or indicators that highlight missing or invalid information.

---

## Update the payment setup

When the customer selects Google Pay as the payment method on the checkout page:

 1. Use the [Google Pay API](https://developers.google.com/pay/api) to collect the payment token.
 2. Call the [Update a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/updateAPaymentSetup) endpoint to submit the token. The fields you must provide depends on the token you use:

**Checkout.com token**

| Field | Description |
| --- | --- |
| `amount`<br>`number` | The payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). <br><br>Minimum: 1 <br><br>**Required** |
| `currency`<br>`string` | Three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). <br><br>**Required** |
| `processing_channel_id`<br>`string` | The [processing channel's](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-processing-channels.md) unique identifier. <br><br>Pattern: `^(pc)_(\w{26})$` <br><br>**Required** |
| `settings.failure_url`<br>`string` | The URL to redirect the customer after a failed authorization. <br><br>Format: uri <br><br>**Required** |
| `settings.success_url`<br>`string` | The URL to redirect the customer after a successful authorization. <br><br>Format: uri <br><br>**Required** |
| `payment_methods.googlepay.token`<br>`object` | The Checkout.com Google Pay token. <br><br>**Required** |
| `payment_methods.googlepay.token.id`<br>`string` | The token identifier, prefixed by `tok_`. <br><br>Pattern: `^(tok)_(\w{26})$` <br><br>**Required** |
| `payment_methods.googlepay.token.expires_on`<br>`string` | The date and time at which the token expires. <br><br>Format: date-time |
| `payment_methods.googlepay.account_holder`<br>`object` | The Google Pay account holder details. |
| `payment_methods.googlepay.account_holder.first_name`<br>`string` | The account holder's first name. |
| `payment_methods.googlepay.account_holder.last_name`<br>`string` | The account holder's last name. |
| `payment_methods.googlepay.account_holder.middle_name`<br>`string` | The account holder's middle name. |
| `payment_methods.googlepay.account_holder.type`<br>`string` | Supported values:<br><br>- `individual`<br><br>- `corporate`<br><br>- `government` |
| `payment_methods.googlepay.account_holder.account_name_inquiry`<br>`boolean` | Indicates whether to perform an account name inquiry. |
| `payment_methods.googlepay.phone`<br>`object` | The customer's phone number details. |
| `payment_methods.googlepay.phone.country_code`<br>`string` | The international dialing code for the customer's phone number. |
| `payment_methods.googlepay.phone.number`<br>`string` | The customer's phone number. |
| `payment_methods.googlepay.store_for_future_use`<br>`boolean` | Indicates whether to store the payment details for future use. |

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "GBP",
  "amount": 2000,
  "reference": "ORDER_01234",
  "description": "Google Pay payment",
  "payment_type": "Regular",
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  },
  "payment_methods": {
    "googlepay": {
      "token": {
        "id": "tok_hilxnnylkxtutoswkxx2425lzi",
        "expires_on": "2026-09-15T16:12:05Z"
      }
    }
  }
}
```

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 2000,
  "currency": "GBP",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Google Pay payment",
  "payment_methods": {
    "googlepay": {
      "status": "ready",
      "token": {
        "id": "tok_hilxnnylkxtutoswkxx2425lzi",
        "expires_on": "2026-09-15T16:12:05Z"
      }
    }
  },
  "available_payment_methods": [
    "googlepay"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

The response returns a `ready` status when the token has been successfully validated. The payment is ready to confirm.

**Google Pay token data**

| Field | Description |
| --- | --- |
| `amount`<br>`number` | The payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). <br><br>Minimum: 1 <br><br>**Required** |
| `currency`<br>`string` | Three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). <br><br>**Required** |
| `processing_channel_id`<br>`string` | The [processing channel's](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-processing-channels.md) unique identifier. <br><br>Pattern: `^(pc)_(\w{26})$` <br><br>**Required** |
| `settings.failure_url`<br>`string` | The URL to redirect the customer after a failed authorization. <br><br>Format: uri <br><br>**Required** |
| `settings.success_url`<br>`string` | The URL to redirect the customer after a successful authorization. <br><br>Format: uri <br><br>**Required** |
| `payment_methods.googlepay.token_data`<br>`object` | The Google Pay payment token data object, returned by the Google Pay API. <br><br>**Required** |
| `payment_methods.googlepay.token_data.protocol_version`<br>`string` | Identifies the encryption and signing scheme used to create the message. <br><br>**Required** |
| `payment_methods.googlepay.token_data.signature`<br>`string` | Verifies that the message came from Google. The signature is created using ECDSA. <br><br>**Required** |
| `payment_methods.googlepay.token_data.signed_message`<br>`string` | A serialized JSON string containing the `encryptedMessage`, `ephemeralPublicKey`, and `tag`. <br><br>**Required** |
| `payment_methods.googlepay.token_data.tokenization_key`<br>`string` | The public key provided to the Google API in the `tokenizationSpecification.parameters.gatewayMerchantId` field. <br><br>**Required** |
| `payment_methods.googlepay.account_holder`<br>`object` | The Google Pay account holder details. |
| `payment_methods.googlepay.account_holder.first_name`<br>`string` | The account holder's first name. |
| `payment_methods.googlepay.account_holder.last_name`<br>`string` | The account holder's last name. |
| `payment_methods.googlepay.account_holder.middle_name`<br>`string` | The account holder's middle name. |
| `payment_methods.googlepay.account_holder.type`<br>`string` | Supported values:<br><br>- `individual`<br><br>- `corporate`<br><br>- `government` |
| `payment_methods.googlepay.account_holder.account_name_inquiry`<br>`boolean` | Indicates whether to perform an account name inquiry. |
| `payment_methods.googlepay.phone`<br>`object` | The customer's phone number details. |
| `payment_methods.googlepay.phone.country_code`<br>`string` | The international dialing code for the customer's phone number. |
| `payment_methods.googlepay.phone.number`<br>`string` | The customer's phone number. |
| `payment_methods.googlepay.store_for_future_use`<br>`boolean` | Indicates whether to store the payment details for future use. |

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "GBP",
  "amount": 2000,
  "reference": "ORDER_01234",
  "description": "Google Pay payment",
  "payment_type": "Regular",
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  },
  "payment_methods": {
    "googlepay": {
      "token_data": {
        "protocol_version": "ECv1",
        "signature": "MEYCIQC9AHUSzVopjzKTrDpGdZyANA291Zn03gXhEnnNXZquxAIhAKh5zoY1oUiwdmtVkg1FN/ieA8/1QMsJgeiprsYrK1Jw",
        "signed_message": "{\"encryptedMessage\":\"KBft9um...\",\"ephemeralPublicKey\":\"BJ/dNhZM...\",\"tag\":\"2FYxP20a...\"}",
        "tokenization_key": "pk_vsef5t73xviedhriex4lrw3c3y"
      }
    }
  }
}
```

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 2000,
  "currency": "GBP",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Google Pay payment",
  "payment_methods": {
    "googlepay": {
      "status": "ready",
      "token": {
        "id": "tok_hilxnnylkxtutoswkxx2425lzi",
        "expires_on": "2026-09-15T16:12:05Z"
      }
    }
  },
  "available_payment_methods": [
    "googlepay"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

The response returns a `ready` status when the token data is successfully validated and the payment is ready to confirm.

> **Information**
>
> The API returns `payment_methods.googlepay.status: unavailable` for all non-validation technical failures occurring during the tokenization process.

---

## Confirm the payment

When the payment status changes to `ready`, confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:

- The payment setup `id` as the `{id}` path parameter.
- `googlepay` as the `{payment_method_name}` path parameter.

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/googlepay`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}/confirm/googlepay`