Loading...
The grouped merchant boarding model supports secure merchant delegation, scalable portfolio management, and a consistent API experience across single or multiple merchant portfolios. The boarding model separates ownership, authorization, and merchant resources into distinct layers.
The boarding model for grouped merchants contains a hierarchy that separates the following:
The boarding model contains the following entities:
The key design principle is that applications are not part of the merchant hierarchy. Instead, applications are an authorization of objects that provide access to the hierarchy.
| Entity | Description | Responsibilities |
|---|---|---|
| Grouped (PAR_ID) | Grouped is the highest-level entity in the grouped model. It represents an external organization that integrates with the API and manages a portfolio of merchants. | * Owns merchant management accounts * Owns applications * Authenticates through the API * Performs actions on behalf of merchants * Manages merchant portfolios |
| Merchant Management Account (MMA_ID) | A merchant management account is a merchant portfolio owned by a grouped. It acts as the operational boundary that determines which merchants can access. | * Groups merchants together * Defines the merchant portfolio * Controls merchant visibility * Provides an authorization scope for applications |
| Merchant (MER_ID) | A merchant represents the merchant business. It contains the payment processing configuration necessary to process transactions and other actions. | * Owns platforms and accounts * Performs transaction processing * Represents the merchant business record |
| Platform (PFC_ID) | Platforms represent integrations with downstream systems. Within the API, a platform acts as the connection layer between the API and the processing system. | Examples: * PORTICO * GPECOM * Future Platforms |
| Account (TRA_ID, TKA_ID, etc.) | Accounts are created under platforms and enable capabilities that are exposed through the platform. | Examples: * Card present processing * Card not present processing * Settlement configuration * Regional processing configuration * Currency-specific processing |
| Application (APP_ID) | Applications provide authentication and access to the API. An application is not a business entity. Instead, it is an authorization mechanism that provides access to resources. | * Generates tokens * Authenticates API requests * Provides access to MMA portfolios * Determines which merchants can be accessed |
Merchants own platforms and accounts.
The application does not own merchants. Instead, the application is granted access to an MMA account which determines the merchants that are accessible.
The Application gains access to merchants through its association with the MMA account.
Create grouped.
The support team creates the Grouped. The Grouped ID is then provided to the customer.
Create merchant management account.
A Merchant Management Account (MMA_ID) is created under the Grouped (PAR_ID). The MMA account is used to organize and manage merchants.
Create grouped application.
An app (APP_ID) is created under the Grouped (PAR_ID). This app is used to generate access tokens.
Associate an application to a merchant management account (MMA).
The app (APP_ID) is linked to the MMA account (MMA_ID). This association gives application access to merchants managed under that MMA account.
Merchant onboarding can occur through two different paths:
Option A: self-service
To board merchants, the Grouped uses the API.
Option B: support assisted
To onboard merchants, the support team uses administrative tools.
Merchant association.
Each merchant (MER_ID) must be attached to an MMA Account (MMA_ID). This association is required for grouped access to the function.
Without the association:
In a standalone configuration, the merchant owns the application (App ID/Key).
The merchant context is determined from the authenticated application.
| HTTP Method | URL |
|---|---|
| POST | https://apis.globalpay.com/ucp/transactions |
When the Grouped owns only one MMA account, you do not need to explicity provide the MMA account.
The merchant context is automatically determined from the authenticated application.
| HTTP Method | URL |
|---|---|
| POST | https://apis.globalpay.com/ucp/merchants/{MER_ID}/transactions |
Example: HTTP POST https://apis.globalpay.com/ucp/merchants/MER_12345/transactions
If a Grouped owns multiple accounts, the MMA context must be explicity specified.
The merchant context is automatically determined from the authenticated application.
| HTTP Method | URL |
|---|---|
| POST | https://apis.globalpay.com/ucp/accounts/{MMA_ID}/merchants/{MER_ID}/transactions |
Example: HTTP POST https://apis.globalpay.com/ucp/accounts/MMA_10001/merchants/MER_20001/transactions