Page Summary
-
Use the
createAPI to establish a merchant record, and then store themerchant_idfor subsequent API interactions. -
Utilize the
patchAPI to modify merchant data as needed andgetAPI to retrieve the merchant data. -
Employ the
addInstrumentAPI to incorporate instrument information for the merchant. -
Incorporate the
addUsersAPI to assign merchant users to the merchant account. -
Enable Google Pay products for the merchant by calling the
enableMerchantAPI.
This guide describes how to integrate with the Merchant API and complete the onboarding flow for a merchant.
Service Endpoints
Use the following endpoints to interact with the Merchant API:
| Environment | Endpoint | Description |
|---|---|---|
| Sandbox | https://preprod-paymentsmerchant.googleapis.com |
For testing and integration development. |
Authentication
All API requests require authorization. For testing, you can use gcloud to generate an access token with the required scope:
https://www.googleapis.com/auth/payments.merchant
Example using a service account:
ACCESS_TOKEN=$(gcloud auth --impersonate-service-account=$SERVICE_ACCOUNT print-access-token --scopes="https://www.googleapis.com/auth/payments.merchant")
Onboarding Flow
The following diagram and steps represent the standard onboarding flow for a merchant.
Onboarding Sequence
1. Create Merchant
Call the merchants.create API to create a new merchant record. The merchantId returned in the response must be stored and used for all subsequent actions.
Newly created merchants are in the INACTIVE state.
Request Example
curl -X POST \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ https://preprod-paymentsmerchant.googleapis.com/v1/merchants \ -d '{ "merchantNames": [{ "name": "Example Merchant", "tags": ["DISPLAY_NAME", "REGISTERED_NAME"] }], "merchantAddresses": [{ "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "95117", "administrativeArea": "CA", "locality": "San Jose", "addressLines": ["1600 Amphitheatre Parkway"] }, "tags": ["REGISTERED_ADDRESS"] }], "merchantContact": { "websiteUrl": "example.com" }, "merchantTaxInfo": { "pan": "ABCDE1234F" }, "merchantCategory": { "merchantCategoryCode": "1234" } }'
Response Example
{ "name": "merchants/BCR2DN6TXDT6ZJLK", "merchantId": "BCR2DN6TXDT6ZJLK", "merchantNames": [ { "name": "Example Merchant", "tags": [ "DISPLAY_NAME", "REGISTERED_NAME" ] } ], "merchantAddresses": [ { "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "95117", "administrativeArea": "CA", "locality": "San Jose", "addressLines": [ "1600 Amphitheatre Parkway" ] }, "tags": [ "REGISTERED_ADDRESS" ] } ], "merchantContact": { "websiteUrl": "example.com" }, "merchantTaxInfo": { "pan": "ABCDE1234F" }, "merchantCategory": { "merchantCategoryCode": "1234" }, "state": "INACTIVE" }
2. Accept Terms of Service (ToS)
The merchant must accept the Terms of Service (ToS) before they can be enabled.
Request Example
curl -X POST \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ https://preprod-paymentsmerchant.googleapis.com/v1/merchants/BCR2DN6TXDT6ZJLK/toses:accept \ -d '{ "tosAcceptanceTime": { "seconds" : "1721722060" }, "emailAddress": "user@example.com" }'
Response Example
{ "tos": { "emailAddress": "user@example.com", "tosUri": "https://payments.developers.google.com/terms/sellertos", "tosAcceptanceTime": "2024-07-23T08:07:40Z" } }
3. Enable Merchant for Product
Call the enableMerchant API to enable a specific Google Pay product (e.g., GOOGLE_PAY_API) for the merchant. After this step, the merchant state transitions to ACTIVE.
Request Example
curl -X POST \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ https://preprod-paymentsmerchant.googleapis.com/v1/merchants/BCR2DN6TXDT6ZJLK:enableMerchant \ -d '{ "product": "GOOGLE_PAY_API" }'
Response Example
{ "name": "merchants/BCR2DN6TXDT6ZJLK", "merchantId": "BCR2DN6TXDT6ZJLK", "merchantNames": [ { "name": "Example Merchant", "tags": [ "DISPLAY_NAME", "REGISTERED_NAME" ] } ], "merchantAddresses": [ { "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "95117", "administrativeArea": "CA", "locality": "San Jose", "addressLines": [ "1600 Amphitheatre Parkway" ] }, "tags": [ "REGISTERED_ADDRESS" ] } ], "merchantContact": { "websiteUrl": "example.com" }, "merchantCategory": { "merchantCategoryCode": "1234" }, "state": "ACTIVE" }
4. Add Web Domains
For integration with the Google Pay API, you must register the web domains where the Google Pay button will be displayed.
Request Example
curl -X POST \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ https://preprod-paymentsmerchant.googleapis.com/v1/merchants/BCR2DN6TXDT6ZJLK/webDomains \ -d '{ "webDomain": "www.example.com" }'
Response Example
{ "webDomain": "www.example.com" }
Additional Merchant Management
These APIs are available for managing the merchant resource after onboarding.
Get Merchant Details
Retrieve the merchant data by merchant ID.
Request Example
curl -X GET \ -H "Authorization: Bearer $ACCESS_TOKEN" \ https://preprod-paymentsmerchant.googleapis.com/v1/merchants/BCR2DN6TXDT6ZJLK
Update Merchant Details
Update specific fields of the merchant record.
Request Example
curl -X PATCH \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ https://preprod-paymentsmerchant.googleapis.com/v1/merchants/BCR2DN6TXDT6ZJLK \ -d '{ "merchantContact": { "websiteUrl": "new-example.com" } }'
Fetch Accepted Terms of Service
Retrieve the list of accepted Terms of Service for the merchant.
Request Example
curl -X POST \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H "Content-Type: application/json" \ https://preprod-paymentsmerchant.googleapis.com/v1/merchants/BCR2DN6TXDT6ZJLK/toses:fetch
Response Example
{ "tos": [ { "emailAddress": "user@example.com", "tosUri": "https://payments.developers.google.com/terms/sellertos", "tosAcceptanceTime": "2024-07-23T08:07:46.318436Z" } ] }
List Web Domains
Retrieve all registered web domains for the merchant.
Request Example
curl -X GET \ -H "Authorization: Bearer $ACCESS_TOKEN" \ https://preprod-paymentsmerchant.googleapis.com/v1/merchants/BCR2DN6TXDT6ZJLK/webDomains
Response Example
{ "webDomains": [ { "webDomain": "www.example.com" } ] }
Add Payment Instrument (India Only)
Associate a payment instrument (e.g., VPA) with the merchant. This is required for merchants onboarding in India.
Add Administrative Users
Grant administrative access to the merchant record for specific Google Accounts.