For applications looking to support multiple terminals for merchants with multiple locations or franchises, it is important to understand how PayJunction accounts are structured.

MID vs PJMID

WEBHOOK SUBSCRIPTIONS ARE LIMITED TO 5 PER PJMID

While these terms are not as important for understanding and using the API, it is important for understanding how accounts are structured in PayJunction. PayJunction processes its merchants' transactions through a processing company, which assigns a Merchant ID (MID) for each Merchant Account. PayJunction also assigns its own unique ID, the PayJunction Merchant ID (PJMID) for each merchant. A PJMID will have at least one MID attached to it, but can potentially have many.

TIP: The following does not apply to billing and fees for an account, only the logical structure for purposes of using the API.

All the data for an account, including login credentials, API connections, transaction and customer history, etc. is tied to the PayJunction account (PJMID). Because this information is specifically tied to the PJMID, PayJunction can swap out Merchant Numbers (MIDs) and terminals while leaving all other data in place. Any of the following reasons can trigger a swap out of MIDs and terminals:

• A business restructures itself (ex. A business restructures itself from a Sole Proprietorship to a Limited Liability Company).
• Change of Ownership for a business.
• IRS Mismatch of legal name and/or federal tax ID requires a new MID.

Therefore it is highly recommended to never hardcode the ids for terminals or Smart Terminals and instead to use GET /terminals and GET /smartterminals to retrieve these ids to prevent PayJunction maintenance work from breaking the integration.

The following diagram shows how the account hierarchy ties different features to each respective level:

Example Account Structures

Single PayJunction Account, Single Merchant Account, Single Terminal (Basic Setup)

For the above example, there are no special considerations in regards to the Transactions API used for manually keyed transactions as all transactions will default to the lone terminal. However, the terminal id is always required for sending payment requests via the Smart Terminal API even though there is only one terminal on the account.

Single PayJunction Account, Single Merchant Account, Multiple Terminals

If our example business decides to add an additional terminal to separate the transactions for the sales department from the service department, here's how the PayJunction account structure will look.

If we want to support this for the merchant, we must now send the terminal id to process through for each transaction request, regardless of whether it is being processed through a Smart Terminal.

Single PayJunction Account, Multiple Merchant Accounts, Multiple Terminals

Our example merchant is doing very well, and decides to open a new location. In order to access both accounts from one set of login credentials, the merchant decides to attach another MID to the existing PayJunction account and PJMID. Here's how the PayJunction account structure will look.

Even though we now technically have two merchant accounts, they are all accessible via one set of API credentials and can be referenced in the API by their unique terminal id values.

Multiple PayJunction Accounts, Multiple Merchant Accounts, Multiple Terminals

Having grown their brand name, our example merchant decides to open a franchise on the East Coast. However, they don't want the franchise owner to have access to the bank deposit and merchant statement information for the West Coast account, so they open a separate PayJunction account:

In this scenario, api@xyzcarsales.com can access the terminals and data for the LA and SF terminals, but not the NYC and Albany terminals. This handy support article explains how to create additional API Credentials. Additionally, make sure to restrict terminal access for each API Credential as explained in the support article.

Restricting Smart Terminal usage to a TID

Options for restricting a Smart Terminal to a specific TID:

• In PayJunction: create a API user that only has permission to use that Smart Terminal and the assigned TID (account).
• In your Application: leave the API with unrestricted access, and only tie the Smart Terminal to a Specific TID on your application.

If you want to impose very strict rules, you can implement both options simultaneously.