Implementing a Merchant Organization API Integration
A Merchant Organization (MO) is a grouping of gateway merchant profiles to align with your business structure and meet your operational needs. For example, if your business has two divisions, LIFE_INSURANCE and BUSINESS_INSURANCE, and let's say the LIFE_INSURANCE division has three gateway merchant profiles for different settlement and transacting purposes. You can define one MO that can view transactions across all three of the gateway merchant profiles for the LIFE_INSURANCE division. This is useful when you have a complex organization structure as it enables you to effectively manage your merchant profiles based on your business structure.
The Merchant Organization (MO) API allows you to create, retrieve, update, and delete MOs and and its relationships with other MOs and merchant profiles without having to manually do this via Merchant Manager. You can integrate it to your business application where the merchant profile data is readily available, for example, a Customer Relationship Management or Sales management tool.
You can only update MOs and assign parent MOs to an MO for which you are the owner. You can manage the relationship between a merchant and an MO using the Update Merchant operation in the Merchant Boarding API.
How to use the Merchant Organization API
The MO API offers the following operations to create/update, retrieve, or delete MOs.
UPDATE_MERCHANT_ORGANIZATION: Allows you to create or update an MO. See Update Merchant Organization.RETRIEVE_MERCHANT_ORGANIZATION: Allows you to retrieve the details of a specified merchant organization, its relationships with other merchant organizations and merchants. See Retrieve Merchant Organization.DELETE_MERCHANT_ORGANIZATION: Allows you to delete an existing merchant organization and its relationships to the MSO, merchants and other merchant organizations. See Delete Merchant Organization.
Note the following before building your integration:
- All the requests for the MO API are idempotent, which means if you re-submit an identical request, the MO API will return the same response as the first request. This means that if you did not receive a response for a request, you can re-submit the same request without having to worry about the side effects.
- When updating any details for a merchant organization, if you do not provide a field in the request, then the MO API overwrites the existing value for that field with NULL. Examples:
- If you have created a merchant organization with the email (
merchantOrganization.email), and you do not provide this field in a subsequent Update Merchant Organization request, then the existing value for the email is erased. - If the field
merchantOrganization.parentMerchantOrganizations[n]is absent when you create a new MO, no parent merchant organizations will be assigned to the MO. If an MO already has parent MOs assigned to it, and if this field is absent in the Update Merchant Organization request then the existing set will be retained. However, if the field is present, any existing parent merchant organizations will be replaced with this set.
- If you have created a merchant organization with the email (
- Some fields in the requests such as identifiers and passwords can contain sensitive data; hence please ensure that your business application handles them securely.
- The MO API and Merchant Manager may be used interchangeably to create/update merchant organization details at any time throughout the merchant organization boarding process.