A location is a site where a business accepts card payments, with its own address, processing profile, industry (MCC), and bank accounts. One legal entity can run many locations, each its own merchant ID (MID) with its own processing profile and features. Locations are needed only for card processing (payin.card); Treasury and payout services don't use them. For the full field list, jump to the Request reference.

Common use cases

• Add a single location with its processing profile. See Scenario 1.
• Run many locations under one business, each with its own MID. See Scenario 1.
• Add a location later and enable its service independently of the others. See Scenario 2.
• Give a location its own funding and billing accounts. See Bank accounts for a location.

Scenarios

One EIN is one business; locations are how that one business operates in more than one place. Each location becomes its own merchant ID (MID) and carries its own processing profile and features.

Before you begin (all scenarios)

• You have the businessId the location belongs to.
• You have the site's address. Only name and address are required; the processing profile, industry, and contact fields are optional.

Scenario 1: Add a location

Make a POST request to /v1/businesses/{businessId}/locations.

curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/locations \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Online store",
    "address": {
      "line1": "901 Commerce St",
      "city": "Austin",
      "stateProvince": "TX",
      "postalCode": "78701",
      "countryCode": "US"
    },
    "phone": "+15555550121",
    "processingProfile": {
      "estimatedMonthlyVolume": 50000.00,
      "avgTicket": 150.00,
      "highTicket": 5000.00,
      "cardMix": {
        "swipedPercent": 0,
        "motoPercent": 10,
        "ecomPercent": 90
      }
    },
    "industry": {
      "mccCode": "5969",
      "description": "Direct marketing retailer"
    },
    "bankAccounts": [
      {
        "id": "ba_5e9c21",
        "purposes": ["funding", "billing"]
      }
    ]
  }'

Response: 201 Created.

{
  "id": "loc_1d6b84",
  "uri": "/v1/businesses/{businessId}/locations/loc_1d6b84",
  "name": "Online store"
}

A location carries its own address, a processingProfile, and an industry (MCC code and description). The processingProfile holds estimated monthly volume, average and high ticket, and a cardMix of swiped, MOTO, and eCommerce. Volume and card mix live here because they are per-site facts. Seasonal sites also carry an operational block (isSeasonal, and openMonths when seasonal).

Scenario 2: Add a location later and enable its service

Add a second site to a business that already exists, then enable its service independently of the others.

# 1. Add the new location
curl -X POST https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/locations \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Airport kiosk",
    "address": {
      "line1": "3600 Presidential Blvd",
      "city": "Austin",
      "stateProvince": "TX",
      "postalCode": "78719",
      "countryCode": "US"
    },
    "industry": {
      "mccCode": "5814",
      "description": "Fast food"
    }
  }'

Enable a service at the location with a PATCH request to /v1/businesses/{businessId}/locations/{locationId}/services/{serviceCode}. Use payin.card for card processing.

# 2. Enable the card service on this location
curl -X PATCH https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}/locations/loc_1d6b84/services/payin.card \
  -H "x-api-key: <your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

The same business can run different features at different locations: one storefront on surcharge, another on 3-D Secure. For the feature codes you can set, see Configure services and Supported services and features.

When is it one business or two?

The test is the tax ID. Sites that share one EIN are one business with many locations; a different EIN is a separate business, onboarded on its own.

• Same EIN: one business with multiple locations, each added under the same businessId.
• Different EIN: a separate business, onboarded on its own.

Manage locations

Location status

A location does not carry a status of its own. Its readiness shows on the location's services and features: read services on the location, for example services.payin.card.status and the status on each feature. These use the same values as the business's services and features. See Service lifecycle for the service and feature statuses, and Status lifecycle for the business-level flow.

Get the entity ID and merchant ID after approval

Once a location's card service is set up, PCE returns two identifiers on the location's payin.card service, under services.payin.card.referenceIds:

Read them from either endpoint:

• GET /v1/businesses/{businessId}/locations/{locationId}
• GET /v1/businesses/{businessId}/locations/{locationId}/services

{
  "services": {
    "payin": {
      "card": {
        "referenceIds": {
          "entityId": "37a9cfc6-4004-5d52-9e44-8133be770e58",
          "merchantId": "1000247986"
        }
      }
    }
  }
}

These IDs can appear while the service is still under review, so read them only once the service status is ENABLED.

Bank accounts for a location

A location can link to the bank accounts it uses, so each location can have its own funding and billing accounts, or share them. Card processing needs a funding and a billing account at each location. Send bankAccounts when you add or update a location, or inline on each location when you create the business.

A location doesn't fall back to the business's accounts. If a location links no funding and billing account, its card service can't go to underwriting.

Each entry in bankAccounts is one of these. Don't send both in the same entry.

• An existing account: the id of one of the business's bank accounts, plus purposes.
• A new account: the account details (accountNumber, routingNumber, accountType, bankName, and optionally countryCode), plus purposes. The new account becomes a bank account of the business, so other locations can link to it too.

This request links one existing account for funding and adds a new account for billing. Make a PATCH request to /v1/businesses/{businessId}/locations/{locationId}:

{
  "bankAccounts": [
    {
      "id": "ba_5e9c21",
      "purposes": ["funding"]
    },
    {
      "accountNumber": "000000000000",
      "routingNumber": "000000000",
      "accountType": "savings",
      "bankName": "Example Bank",
      "countryCode": "US",
      "purposes": ["billing"]
    }
  ]
}

Rules for location bank accounts

• purposes is required on every entry: funding, billing, or both.
• One account can be shared across locations, with different purposes at each.
• You can't change an account's details through a location update. A location update only changes which accounts the location links to and their purposes.
• The location returns each linked account masked, with only the last four digits of the account number, plus the purposes this location uses it for.
• The business's own bankAccounts list every account of the business, without the purposes each location uses.

If purposes is missing or invalid, the request fails with 422:

{
  "errorCode": "REQUEST_VALIDATION_FAILED",
  "message": "Validation failed",
  "errors": [
    {
      "field": "bankAccounts[0].purposes",
      "code": "REQUIRED",
      "message": "bankAccounts[0].purposes is required"
    },
    {
      "field": "bankAccounts[1].purposes",
      "code": "INVALID_ENUM_VALUE",
      "message": "bankAccounts[1].purposes must be one of the following values: funding, billing"
    }
  ]
}

Request reference

Next steps

See also

• Create a business: build the business and its locations in one call
• Supported services and features: the features you can set per location
• Businesses: how locations fit the entity model