Manage Google Pay domains through Primer

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

This feature is in beta. Contact your Customer Success Manager or raise a ticket through the Support Portal to enable it for your account.

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. You create a Primer-managed Google Pay merchant ID in the Dashboard. 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, you switch your Google Pay configuration to the new merchant ID in the Dashboard.

​

Before you begin

• Set up Google Pay with Primer. See Google Pay.
• 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.

​

Step 1. Create a Primer-managed merchant ID

In the Dashboard, open the Google Pay Managed by Primer card and submit:

• 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

Each Primer account can have one Primer-managed merchant ID, and it can’t be deleted, so check your details before you submit.

Google reviews the new merchant ID, which can take up to 24 hours. When it’s active, the card shows your new merchant ID and your 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.

If your site blocks requests from unknown IP addresses, contact your Customer Success Manager for the addresses Primer checks domains from, and allow them.

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

curl https://shop.example.com/.well-known/primer-google-pay-domain-verification

​

Step 3. Register your domains

Register one domain per request, and send requests one at a time: wait for each to finish before you send the next. Primer refuses a registration or removal while another one for your account is still in progress. Send the domain name only, without https://, a path or a wildcard.

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:

{
  "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, open your Google Pay integration in the Dashboard and replace the merchant ID with the one on the Google Pay Managed by Primer card.

After the switch, publish your checkout again in the Checkout Builder.

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

To switch back, enter your previous merchant ID from the Google Pay & Wallet Console in the same field, and publish your checkout again. Creating a Primer-managed merchant ID doesn’t change your previous merchant ID or the domains registered on it, so keep them until you’re sure you won’t switch back.

Switching doesn’t affect payments you’ve already taken. You can still refund payments taken under the previous merchant ID.

​

Manage your domains

​

List domains

curl --request GET \
     --url https://api.primer.io/v1/google-pay-domains \
     --header 'X-Api-Key: <YOUR_API_KEY>'

{
  "data": [
    { "domain": "shop.example.com" },
    { "domain": "tickets.example.com" }
  ]
}

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

​

Remove a domain

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:

{
  "error": {
    "errorId": "GooglePayDomainLimitExceeded",
    "description": "The merchant has reached its Google Pay web domain limit.",
    "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.
404	GooglePayDomainsNotEnabled	Domain management isn’t enabled for your account.	Contact your Customer Success Manager or raise a ticket through the Support Portal.
409	GooglePayDomainLimitExceeded	Google refused the domain because your merchant ID is at its domain limit.	Remove a domain before you register another. If you have fewer than 950 domains registered, raise a ticket through the Support Portal with the diagnosticsId.
409	GooglePayDomainOperationInProgress	Another registration or removal for your account is still in progress.	Wait for it to finish, then retry. Send requests one at a time.
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. The response doesn’t say which one failed.
502	GooglePayProviderError	Google rejected the request.	Raise a ticket through the Support Portal 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.