# Google Pay for web

Accept Google Pay payments on your website with [Flow](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website.md), our pre-built, customizable payment user interface.

Flow enables you to accept payments using Checkout.com's global network of payment methods with a single integration.

Set up your client-side and server-side configuration to integrate with Checkout.com's payment gateway and enable payments on your website.

---

## How it works

1. The customer lands on the checkout page.
2. You perform a server-side request to create a payment session.
3. You use the payment session data on the client-side to mount Flow.
4. Flow displays Google Pay as a payment method to the customer.
5. When the customer clicks the _Pay_ option, Flow performs a payment request and handles any additional actions. For example, additional actions required for [3D Secure (3DS)](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure.md) authentication, or a third-party payment page redirect.
6. You receive a webhook notifying you of the payment status.

---

## Before you start

To offer Google Pay with Flow, complete the following prerequisites:

- Follow Google's integration guide for [Google Pay Web](https://developers.google.com/pay/api/web/overview).
- Contact your account manager and provide them with your Google Pay Merchant ID.
- Comply with the Google Pay [payment method rules](https://www.checkout.com/legal/payment-methods-rules).

> **Information**
>
> You can optionally register your domain using the [Enroll an entity to the Google Pay Service](https://api-reference.checkout.com/#tag/Google-Pay) endpoint.

You also need a Checkout.com [test account](https://www.checkout.com/get-test-account).

Create a [public key and a secret key](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md) in the Dashboard, with the following key scopes:

- Public key – `payment-sessions:pay` and `vault-tokenization`
- Secret key – `payment-sessions`

To receive webhooks for the [payment events](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway), [configure your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md).

> **Information**
>
> Some operating systems may not fully support Google Pay if you integrate Flow within a WebView.

### Enroll your entity and domain to Google Pay `Optional`

To process Google Pay payments, enroll your Checkout.com entity with Google Pay services, and register the domains on which you want to process Google Pay payments.

1. Call the [Enroll an entity to the Google Pay Service](https://api-reference.checkout.com/tag/Google-Pay/#operation/GooglePayEnrollMerchant) endpoint. In the request body, provide the following:

   - `entity_id` – The Checkout.com entity ID you want to enroll.
   - `email_address` – The email address of the user who accepted the [Google terms of service](https://payments.developers.google.com/terms/sellertos).
   - `accept_terms_of_service` – Set to `true`.

**Production**

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

**Sandbox**

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

### Request example

```json
{
  "entity_id": "ent_uzm3uxtssvmuxnyrfdffcyjxeu",
  "email_address": "hannah.bret@example.com",
  "accept_terms_of_service": true
}
```

2. Call the [Register a web domain for an enrolled entity](https://api-reference.checkout.com/tag/Google-Pay/#operation/GooglePayRegisterDomain) endpoint and provide the entity ID as the `{id}` path parameter. Set the `web_domain` field to the domain you want to register.

**Production**

`POST` `https://{prefix}.api.checkout.com/googlepay/enrollments/{entity_id}/domain`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/googlepay/enrollments/{entity_id}/domain`

### Request example

```json
{
  "web_domain": "example.com"
}
```

If you receive a `204` response, the domain registration was successful.

### Content Security Policy

If you have a Content Security Policy (CSP) on your website, Checkout.com requires the following directives:

```
connect-src, https://*.checkout.com
frame-src, https://*.checkout.com
script-src, https://*.checkout.com
img-src, https://*.checkout.com
```

---

## Create a new Payment Session `Server side`

When the customer is ready to pay, call the [Create a Payment Session](https://api-reference.checkout.com/tag/Flow/#operation/CreatePaymentSession) endpoint to securely create a `PaymentSession` object.
The `PaymentSession` contains the information required to handle all steps of the payment flow.

In your request:

- Set `billing.address.country` to a country supported by Google Pay. See Google Pay Help – [Countries or regions in which you can make payments with Google](https://support.google.com/googlepay/answer/12429287?hl=en-GB).
- Set `currency` to the selected country's [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md).

> **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/payment-sessions`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payment-sessions`

### Request example

```json
{
  "amount": 1000,
  "currency": "GBP",
  "reference": "ORD-123A",
  "display_name": "Online shop",
  "billing": {
    "address": {
      "country": "GB"
    }
  },
  "customer": {
    "name": "Jia Tsang",
    "email": "jia.tsang@example.com"
  },
  "success_url": "https://example.com/payments/success",
  "failure_url": "https://example.com/payments/failure"
}
```

### Response example

```json
{
  "id": "ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ",
  "payment_session_secret": "pss_9823241e-2cec-4c98-b23d-7b29ow4e2e34",
  "payment_session_token": "YmFzZTY0:eyJpZCI6InBzXzJVbjZJNmxScElBaUlFd1FJeXhXVm5WOUNxUSIsImFtb3VudCI6MTAwMCwibG9jYWxlIjoiZW4tR0IiLCJjdXJyZW5jeSI6IkdCUCIsInBheW1lbnRfbWV0aG9kcyI6W3sidHlwZSI6ImNhcmQiLCJjYXJkX3NjaGVtZXMiOlsiVmlzYSIsIk1hc3RlcmNhcmQiLCJBbWV4Il19XSwicmlzayI6eyJlbmFibGVkIjp0cnVlfSwiX2xpbmtzIjp7InNlbGYiOnsiaHJlZiI6Imh0dHBzOi8vYXBpLnNhbmRib3guY2hlY2tvdXQuY29tL3BheW1lbnQtc2Vzc2lvbnMvcHNfMlVuNkk2bFJwSUFpSUV3UUl5eFdWblY5Q3FRIn19fQ==",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payment-sessions/ps_2Un6I6lRpIAiIEwQIyxWVnV9CqQ"
    }
  }
}
```

---

## Initialize and mount Flow `Client side`

You can install the `@checkout.com/checkout-web-components` package via npm:

```bash
npm install @checkout.com/checkout-web-components --save
```

Alternatively, you can load the package directly via a script:

```html
<script src="https://checkout-web-components.checkout.com/index.js" />
```

> **Note**
>
> To remain PCI compliant, always load the script directly from `https://checkout-web-components.checkout.com`. Do not download or host the script yourself, or include it in a bundle.

The client side initializes an instance of `CheckoutWebComponents` with configuration information and the payment session data retrieved when you created the payment session.

```javascript
// Insert your public key here
const publicKey = 'pk_sbox_o2nulev4vbo43i4qkb5p7lfijap';

const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  environment: 'sandbox',
});
```

### Configuration options

You can use the following configuration options to instantiate an instance of `CheckoutWebComponents`:

| JavaScript key | Description |
| --- | --- |
| `appearance` | Enables you to customize the visual appearance of the `CheckoutWebComponents` elements.<br><br>For customization options, see [Appearance options](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-flow-integration.md#Appearance_options). |
| `componentOptions` | Enables you to customize the options for the individual Flow components. For example, you can change the position of the cardholder field in the `card` component.<br><br>For customization options, see [Component options](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference/checkoutwebcomponents.md#Initialization). |
| `environment` | Sets the environment you want the library to point, and send requests to. This can be one of:<br><br>- `production`<br>- `sandbox` |
| `locale` | Sets the customer's locale. Explicitly setting this value overrides the `locale` returned by the `PaymentSession`.<br><br>For supported languages, see [Localization](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/add-localization-to-your-flow-integration.md). |
| `onAuthorized` | [Inspect the payment details the customer provided in Google Pay](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-payment-process.md#Inspect_wallet_payment_details), when the customer triggers a payment submission. |
| `paymentSession`<br><br>`required` | The response from the `PaymentSession`. |
| `publicKey`<br><br>`required` | Your public API key, prefixed with `pk_`. |
| `translations` | Enables you to provide custom text translations for natively supported languages, or add custom text for locales and languages not natively supported by Flow.<br><br>For how to add translations, see [Add localization to your Flow integration](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/add-localization-to-your-flow-integration.md). |

Use `CheckoutWebComponents` to create a `googlepay` object.

```javascript
const googlepayComponent = checkout.create("googlepay");
```

Mount Flow to the website using the `mount()` method. The method takes an [Element selector](https://developer.mozilla.org/en-US/docs/Web/API/Element) or an [Element](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors) as an argument. For example, `#flow-container` or `document.getElementById(#flow-container)`, respectively.

**Mount Flow to a Selector**

```javascript
if (await googlepayComponent.isAvailable()) {
  googlepayComponent.mount('#googlepay-container');
}
```

**Mount Flow to an Element**

```javascript
const googlepayElement = document.getElementById('googlepay-container');

if (await googlepayComponent.isAvailable()) {
  googlepayComponent.mount(googlepayElement);
}
```

> **Note**
>
> You cannot embed Flow within an iframe or onto a Shadow DOM.

---

## Handle the payment response `Client side`

Google Pay supports both asynchronous and synchronous payment flows. The asynchronous flow requires a customer redirect, while the synchronous flow does not.

### Asynchronous payments

The customer is redirected to a success or failure URL on your website depending on the payment outcome and the result of any additional payment authentication. For example, 3DS authentication.

You can retrieve the payment result using the [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails) endpoint. Use the `cko-payment-id` value from the success or failure URL as the `{id}` path parameter. For example:

```
https://example.com/success?cko-payment-id=pay_mbabizu24mvu3mela5njyhpasd
```

If you've [configured your webhook server](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md), we send a [Gateway](https://www.checkout.com/docs/developer-resources/event-notifications/event-types.md#Gateway) webhook to your server. The webhook we send depends on the status of the payment. Wait for the webhook callback before you start your order fulfillment process.

The `PaymentSession` ID is returned in the webhook payload's `data.metadata.cko_payment_session_id` field.

### Synchronous payments

The `onPaymentCompleted` event triggers when a payment is successfully completed. You can use the event data to notify the customer of the payment status.

Add the event handler to the Flow initialization code:

```javascript
const publicKey = 'pk_sbox_o2nulev4vbo43i4qkb5p7lfijap';

const checkout = await CheckoutWebComponents({
  paymentSession,
  publicKey,
  environment: 'sandbox',

  onPaymentCompleted: async (_self, paymentResponse) => {
    // Handle synchronous payments
    await handlePayment(paymentResponse.id);
  },
});
```

The `PaymentSession` ID is returned in the webhook payload's `data.metadata.cko_payment_session_id` field.

---

## Test the integration

Use [test cards](https://www.checkout.com/docs/developer-resources/testing/test-cards.md) to simulate different payment flows and ensure your integration is set up correctly and behaving as expected.

To check the status of a payment:

1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Payments_ > _Processing_ > _All payments_.
3. Select the test payment to view its details.

---

## Next steps

**[Customize your Flow integration](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/customize-your-flow-integration.md)**

Learn how to customize your Flow integration.

**[Flow library reference](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-on-your-website/flow-library-reference.md)**

See the configuration options and error handling steps for Flow.