> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Google Pay domains through Primer

> Register up to 950 Google Pay domains through Primer's API instead of the Google Pay & Wallet Console.

<Note>
  This feature is in beta. Contact your Customer Success Manager or raise a ticket through the [Support Portal](https://portal.support.primer.io/servicedesk/customer/portal/11) to enable it for your account.
</Note>

Google Pay on the web only appears on domains registered with Google. The Google Pay & Wallet Console, where Google calls them websites, limits how many domains a merchant ID can have and reviews each one manually.

If you need Google Pay on more domains than the Console allows, for example a platform with a site per sub-merchant, Primer can create a Google Pay merchant ID for you. You can then register up to 950 domains through Primer's API, with no manual review.

This is optional. If the Console covers your domains, you don't need to change anything.

## How it works

1. Primer creates a new Google Pay merchant ID for you. It is separate from any merchant ID you have in the Google Pay & Wallet Console, and you manage its domains only through Primer's API.
2. You prove you control each domain and register it through the API.
3. When all your domains are registered, Primer switches your Google Pay configuration to the new merchant ID.

## Before you begin

* Set up Google Pay with Primer. See [Google Pay](/docs/connections/payment-methods/google-pay/overview).
* Ask Primer to enable domain management for your account.
* Create an API key with the `google_pay_merchants:read` and `google_pay_merchants:write` scopes. See [Authentication](/docs/api-reference/get-started/authentication).

## Step 1. Request a Primer-managed merchant ID

Contact your Customer Success Manager or raise a ticket through the [Support Portal](https://portal.support.primer.io/servicedesk/customer/portal/11). Primer asks for:

* your company's legal name, display name, country of registration and registered address
* your website and merchant category code (MCC)
* your acceptance of the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos)

Google reviews the new merchant ID, which can take up to 24 hours. Primer then sends you a domain verification token.

## Step 2. Serve the verification token

Primer checks that you control a domain before registering it. Serve your token on every domain you register, including each subdomain:

* at `https://{domain}/.well-known/primer-google-pay-domain-verification`
* over HTTPS, with a valid certificate for the domain
* with status `200` and no redirect
* as the whole response body, uncompressed and under 1 KB

The token is the same for all your domains and doesn't change. The domain must resolve only to public IP addresses.

To check a domain, request the URL and confirm the response is your token:

```bash theme={"dark"}
curl https://shop.example.com/.well-known/primer-google-pay-domain-verification
```

## Step 3. Register your domains

Register one domain per request. Send the domain name only, without `https://`, a path or a wildcard.

```bash theme={"dark"}
curl --request POST \
     --url https://api.primer.io/v1/google-pay-domains \
     --header 'X-Api-Key: <YOUR_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '{"domain": "shop.example.com"}'
```

A successful request returns `201`:

```json theme={"dark"}
{
  "domain": "shop.example.com"
}
```

The domain is returned as registered, in lowercase. Registering a domain that is already registered also returns `201`, so you can safely re-run an interrupted batch.

## Step 4. Switch to the new merchant ID

When every domain you accept Google Pay on is registered, contact your Customer Success Manager or raise a ticket through the [Support Portal](https://portal.support.primer.io/servicedesk/customer/portal/11) to switch to the new merchant ID.

<Warning>
  After the switch, Google Pay only appears on domains registered through Primer. Domains registered in the Google Pay & Wallet Console no longer apply.
</Warning>

## Manage your domains

### List domains

```bash theme={"dark"}
curl --request GET \
     --url https://api.primer.io/v1/google-pay-domains \
     --header 'X-Api-Key: <YOUR_API_KEY>'
```

```json theme={"dark"}
{
  "data": [
    { "domain": "shop.example.com" },
    { "domain": "tickets.example.com" }
  ]
}
```

The response includes every domain registered through Primer, in one response.

### Remove a domain

```bash theme={"dark"}
curl --request DELETE \
     --url https://api.primer.io/v1/google-pay-domains/shop.example.com \
     --header 'X-Api-Key: <YOUR_API_KEY>'
```

A successful request returns `204` with no body. Removing a domain frees a slot for a new one. Removing a domain that isn't registered also returns `204`.

## Test in sandbox

Use `https://api.sandbox.primer.io` to test your integration with the API. Sandbox doesn't affect Google Pay in test mode, where Google doesn't require domains to be registered.

## Errors

Errors use Primer's standard [error payload](/docs/api-reference/get-started/api-responses):

```json theme={"dark"}
{
  "error": {
    "errorId": "GooglePayDomainLimitExceeded",
    "description": "You have reached the limit of 950 domains.",
    "diagnosticsId": "1234567890",
    "validationErrors": []
  }
}
```

Include the `diagnosticsId` when you contact Primer.

| Status | `errorId` | Meaning | What to do |
| - | - | - | - |
| `400` | `BadlyFormedJSONRequest` | The request body isn't valid JSON. | Fix the request body. |
| `401` | `InvalidAuthCredentials` | The API key is missing or invalid. | Check the `X-Api-Key` header. |
| `403` | `NotAuthorizedToAccessResource` | The API key doesn't have the required scope. | Add the `google_pay_merchants:read` or `google_pay_merchants:write` scope. |
| `404` | `GooglePayManagedMerchantNotFound` | Your account doesn't have a Primer-managed merchant ID. | Complete [Step 1](#step-1-request-a-primer-managed-merchant-id). |
| `404` | `GooglePayDomainsNotEnabled` | Domain management isn't enabled for your account. | Contact your Customer Success Manager or raise a ticket through the [Support Portal](https://portal.support.primer.io/servicedesk/customer/portal/11). |
| `409` | `GooglePayDomainLimitExceeded` | You have reached the limit of 950 domains. | Remove a domain before you register another. |
| `422` | `RequestValidationError` | The request body is missing `domain`. | Add `domain` to the request body. |
| `422` | `GooglePayInvalidDomain` | The domain isn't a valid domain name. | Send the domain name only, for example `shop.example.com`. |
| `422` | `GooglePayDomainVerificationFailed` | The domain doesn't serve your verification token. | Check the requirements in [Step 2](#step-2-serve-the-verification-token). The response doesn't say which one failed. |
| `502` | `GooglePayProviderError` | Google rejected the request. | Raise a ticket through the [Support Portal](https://portal.support.primer.io/servicedesk/customer/portal/11) with the `diagnosticsId`. |
| `503` | `GooglePayProviderUnavailable` | Google is temporarily unavailable. | Retry later. |
| `503` | `GooglePayQuotaExceeded` | Google is receiving too many requests. | Retry after the number of seconds in the `Retry-After` header. |
| `503` | `GooglePayDomainVerificationUnavailable` | Primer couldn't check the domain. | Retry later. |

## Limitations

* You can't register `*.example.com` to cover all subdomains. Register each subdomain separately, for example `shop.example.com` and `tickets.example.com`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.