Understanding Submerchants in PayOS

In the context of PayOS and payment orchestration, submerchants serve as an optional feature that allows merchants to distinguish between multiple transacting entities under a single PayOS merchant account. This feature is particularly useful for businesses that operate under different submerchant names or have multiple business units, each requiring separate transaction tracking and reporting.

Key Features of Submerchants

• Optional Configuration: The use of submerchants is entirely optional. Merchants can choose to enable this feature based on their business needs.

• Transaction Differentiation: When submerchants are enabled, merchants must specify which submerchant a transaction is associated with. This ensures that each transaction is correctly attributed to the appropriate entity within the merchant’s ecosystem.

• Enhanced Reporting: By distinguishing transactions by submerchant, merchants can generate more detailed reports, providing insights into the performance of each submerchant or business unit.

How to Use Submerchants

1. Enable Submerchants: Merchants can enable the submerchants feature through their PayOS account settings. This setup allows them to define and manage multiple submerchants under their account.

2. Specify Submerchant in Transactions: Once enabled, merchants need to indicate the submerchant for each transaction they initiate. This is typically done by including a submerchant identifier in the transaction request.

3. Manage Submerchants: Merchants can add, update, or remove submerchants as their business evolves, ensuring that their payment orchestration setup remains aligned with their operational structure.

Example: Create Checkout Session Request with Submerchant ID

When creating a checkout session, you can include a submerchant_id to specify the submerchant associated with the session. Below is an example of a “Create Checkout Session” request with a submerchant_id:

1
{
2
  "amount": 150.00,
3
  "currency": "USD",
4
  "merchantReference": "ORDER12345",
5
  "redirectUrl": "https://merchant.com/redirect",
6
  "payerName": "John Doe",
7
  "payerEmailAddress": "john.doe@example.com",
8
  "payerLocation": "ZAF",
9
  "merchantLocation": "AE",
10
  "integrationType": "hosted",
11
  "submerchant_id": "SUBMERCHANT_12345"
12
}

In this example, the submerchant_id field is used to indicate the specific submerchant for which the checkout session is being created. This allows the session and any subsequent transactions to be tracked and reported under the correct submerchant within the merchant’s account.

By leveraging the submerchants feature, merchants can achieve greater flexibility and control over their payment processes, ensuring that each transaction is accurately tracked and reported according to their unique business structure.