A merchant record can hold an address for the legal entity, an address for mail, and a set of locations where the business operates. Each one answers a different question about the business, and each connection reads only the ones it needs.

Registered business address

The registered business address is the address on the business's official records. In the United States, that's the address the business filed with the state where it was formed, usually with the Secretary of State, and the address the IRS has on file for its Employer Identification Number (EIN).

Underwriting uses this address to confirm that the business exists and that it is the business it claims to be. When a connection underwrites a merchant, it checks the legal name, tax ID, and registered business address together against those records. If the address you send doesn't match the business's records, approval can take longer, or the connection can ask for more information.

For example, a landscaping company formed as an LLC in Texas files 400 Elm St, Austin, TX with the Texas Secretary of State and the IRS. Its registered business address in Preczn is 400 Elm St, even if the owner receives mail at a PO box.

Set it in the merchant's address object:

{
  "address": {
    "address": "123 Drive Way",
    "address2": "Unit 2",
    "city": "New York City",
    "region": "NY",
    "postal": "10001",
    "country": "USA"
  }
}

The boarding form collects the same fields with the business information, starting with Business Street Address.

🚧

The registered business address can't be a PO box

Use the street address where the business is located. The boarding form rejects a PO box in Business Street Address. If the business receives mail at a PO box, put the PO box in the mailing address instead.

Mailing address

The mailing address is where the business receives mail, such as a post office box or an accountant's office. It's optional. Most connections don't use it, so you only need it when a connection asks for it.

Set it in the merchant's mailingAddress object, which has the same fields as address:

{
  "mailingAddress": {
    "address": "PO Box 4021",
    "city": "New York City",
    "region": "NY",
    "postal": "10001",
    "country": "USA"
  }
}

When a connection requires a mailing address, its requirements list the mailing fields, and Preczn reports any that are missing. Synchrony is one connection that requires a mailing address. See Onboarding Data Requirements.

In the boarding form, the merchant can select The business mailing address is the same as the business address. The form then copies the registered business address into the mailing fields, so both are stored.

Locations

A location is a place where the business operates, such as a storefront, an office, or a service branch. The merchant stays one legal entity with one underwriting review, however many locations it has. Each location holds only what can differ from site to site:

A location's address can match the registered business address. For example, a business with one storefront at its registered address still uses that address for the location.

A location's address also can't be a PO box, because it describes where the site operates. The boarding form rejects a PO box in a location's street address.

Location IDs start with midLoc_. The merchant's locations array lists the ID of each of its locations. To read the full records, call List locations for a merchant.

Primary location

The merchant's primaryLocationId names its primary location. When primaryLocationId is empty, the merchant itself is treated as the primary location. You can't delete the location that's set as primary. To delete it, first set primaryLocationId to another location or clear it with Update Merchant.

Values are never copied from the merchant

Preczn stores each location exactly as you send it. It doesn't fill a location's name, address, MCC, or phone from the merchant record. If a location shares the registered business address, send that address in the location request.

The boarding form helps with this. Each location has a Copy business address action that fills the location's address from the registered business address.

Why only some connections use locations

Whether a connection uses locations depends on how the processor boards a business.

Most processors board a merchant as one business, with one address and one settlement account. They have nowhere to put a second site, so Preczn sends them the registered business address, and the mailing address if they ask for one. Locations you add to the merchant don't change what these connections receive.

Some processors board each site separately. For connections such as Jack Henry or Adyen for Platforms, Preczn sends the merchant's locations, and each connection uses the parts of a location it needs:

• Jack Henry needs at least one location, and accepts up to 500. Each location gives Jack Henry a settlement account and five ACH limits. Jack Henry doesn't receive the location's address. See Locations and ACH limits.
• Adyen for Platforms doesn't need locations. A merchant with no locations boards as one business. When the merchant has locations, Preczn creates an Adyen store for each one, using the location's name, address, and phone, and each location needs a bank account in bankingId.

A connection's requirements state whether it needs locations and which location fields must be filled in. See the Locations category in Onboarding Data Requirements.

📘

Transactions aren't assigned to a location

Locations describe the merchant for boarding. A transaction belongs to the merchant, not to one of its locations.

When a connection doesn't use locations

If a business needs a separate account for each site at a connection that doesn't use locations, create a separate merchant record for each site. See When a business needs two MIDs at the same provider.

For Adyen for Platforms, use locations instead. Add a location for each site to one merchant record, and Preczn creates a store for each location when it boards the merchant.

Add locations

Add a location with the API

To add a location, call Create a merchant location. name, address, mcc, and phone are required.

POST /v1/merchants/{merchantId}/locations

{
  "name": "Market Street Flagship",
  "address": {
    "address1": "1 Market St",
    "address2": "Suite 400",
    "city": "San Francisco",
    "region": "CA",
    "postal": "94105",
    "country": "USA"
  },
  "mcc": "5812",
  "phone": "+14155550188",
  "bankingId": "midBank_5kaft3yde39cssvv3w389kens8"
}

🚧

The street field name differs from the merchant's

A location's first street line is address.address1. On the merchant's address and mailingAddress objects, the same line is address.address.

To change a location, call Update a location. Fields you omit keep their stored values. You can clear bankingId with null, but you can't clear name, address, mcc, or phone.

To remove a location, call Delete a location.

Collect locations in a boarding form

When a boarding form template displays location fields, the boarding form shows a tab for each location, and the merchant can add as many as they need. Connections that need more for each location, such as Jack Henry's ACH limits, collect those values in their own step. See Boarding Form Templates.

Track location changes with webhooks

Subscribe to location.created, location.updated, and location.deleted to keep your records in sync. Each event carries the merchant ID and the full location record. See Subscribing to Webhooks.

Frequently asked questions