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:

```bash
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

<iframe src="https://developers.devsite.google/frame/pay/merchant-api/guides/integration_471d46277a2b61f62eba50b06067d85c0fb0239b263174192ca06b5c40bf16d3.frame" class="framebox inherit-locale " allow="clipboard-write https://developers.devsite.google" allowfullscreen is-upgraded></iframe>

### 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

```bash
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

```json
{
  "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

```bash
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

```json
{
  "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

```bash
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

```json
{
  "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

```bash
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

```json
{
  "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

```bash
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

```bash
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

```bash
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

```json
{
  "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

```bash
curl -X GET \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://preprod-paymentsmerchant.googleapis.com/v1/merchants/BCR2DN6TXDT6ZJLK/webDomains
```

#### Response Example

```json
{
  "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.