Manage Google Pay domains through Primer

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

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.
You prove you control each domain and register it through the API.
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.
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. Request a Primer-managed merchant ID

Contact your Customer Success Manager or raise a ticket through the Support Portal. 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

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:

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

Step 3. Register your domains

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, contact your Customer Success Manager or raise a ticket through the Support Portal to switch to the new merchant ID.

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

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": "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.
`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`	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. 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.

​How it works

​Before you begin

​Step 1. Request a Primer-managed merchant ID

​Step 2. Serve the verification token

​Step 3. Register your domains

​Step 4. Switch to the new merchant ID

​Manage your domains

​List domains

​Remove a domain

​Test in sandbox

​Errors

​Limitations

How it works

Before you begin

Step 1. Request a Primer-managed merchant ID

Step 2. Serve the verification token

Step 3. Register your domains

Step 4. Switch to the new merchant ID

Manage your domains

List domains

Remove a domain

Test in sandbox

Errors

Limitations