Integration Guide

  • Use the create API to establish a merchant record, and then store the merchant_id for subsequent API interactions.

  • Utilize the patch API to modify merchant data as needed and get API to retrieve the merchant data.

  • Employ the addInstrument API to incorporate instrument information for the merchant.

  • Incorporate the addUsers API to assign merchant users to the merchant account.

  • Enable Google Pay products for the merchant by calling the enableMerchant API.

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.