Support Multilocation Merchants

Larger merchants with multiple locations of operation are fairly common in retail and restaurant spaces, and you'll want to be sure that your system will be able to support them. This guide will onboard multilocation merchants and build custom reporting.

Onboard Multilocation Merchants

As outlined in the Clear Onboard Merchants articles, you'll first create a Legal Entity followed by an Account. For multilocation merchants, there should be one Legal Entity with multiple child Accounts, and each Account will represent one location.

You'll want to clearly identify which Account belongs to which location, and there are several ways to do this in the API. For instance, you can use the name field on Accounts, assuming that each location has a street or city location in their DBA. Alternatively, use the reference_id parameter, or create a location field in the Account's custom_data.

Provide Custom Reporting

Reporting for multilocation merchants presents some unique cases beyond the basics covered in our Reporting cookbook.

First, you'll want to clarify whether you'll provide reporting for each location, all locations combined, or some solution in between.

Reporting on each location independently of the other is straight forward, and is no different from merchant reporting discussed in the Reporting cookbook mentioned above. Aggregate location reporting for a merchant requires some additional steps:

1. Fetch all Account IDs belonging to the merchant

Send a GET /accounts request like so:

Copy

Copied

curl -X GET -G \
curl -L -g -X GET 'https://stage-api.wepay.com/accounts?owner_id={legal_entity_ID}' \
-H 'app-id: {app_id}' \
-H 'app-token: {app_token}' \
-H 'Content-Type: application/json' \
-H 'api-version: 3.0'

The response will contain an array of Accounts. Parse the response to fetch the id parameter from each, and identify whether more items are available by finding the next_page parameter (items per page defaults to 10).

2. Fetch all Transaction Records from a given time period for each Account ID

Send a GET /transaction_records request like so:

Copy

Copied

curl -L -g -X GET 'https://stage-api.wepay.com/transaction_records?create_time_start={unix_timestamp}&create_time_end={unix_timestamp}&account_id={location_account_id}' \
-H 'api-version: 3.0' \
-H 'app-token: {app_token}' \
-H 'app-id: {app_id}' \
-H 'Content-Type: application/json'

2.1. Fetch all Transaction Records from the past 7 days for each Account ID

Send a GET /transaction_records request like so:

Copy

Copied

curl -L -g -X GET 'https://stage-api.wepay.com/transaction_records?account_id={location_account_id}' \
-H 'api-version: 3.0' \
-H 'app-token: stage_OF84NzZmYjMwNC0xNGY4LTQwNjItOWJlNy0yMDU1MWZjNjIwYWQ' \
-H 'app-id: 153047' \
-H 'Content-Type: application/json'

3. Compile data

Compile responses from each Account ID into a single list. Since GET responses are not in chronological order, we recommend ordering transactions by the create_time response value.

Questions? Need help? Visit our support page!