Implementing a Merchant Boarding API Integration
The Merchant Boarding API allows you to automatically board merchants onto the MCB Payment Gateway. By integrating the Merchant Boarding API with your business application, you can create, update, and approve merchant accounts without having to manually configure a merchant in Merchant Manager. This is useful when you have merchant data readily available in your business application (a Customer Relationship Management or Sales management tool) or provided directly by the merchant entering it in an online form. The Merchant Boarding API thereby allows you to increase the rate of merchant boarding by reducing the time lag between data collection and account activation.
How to use the Merchant Boarding API
The Merchant Boarding API allows you to board merchants onto MCB Payment Gateway using a series of requests. When boarding is complete, you will be able to complete your own merchant boarding processes (for example, provision the merchant in their billing system, and send a welcome email to the merchant).
- Update Merchant: It allows you to create or update a merchant account and set general details.
- Update Acquirer Link: It allows you to add or update the configuration for an acquirer link that is used by the merchant for payment processing.
- Update Payment Details: It allows you to add or update payment configuration details for an existing merchant.
- Create or Update Merchant: It allows you to
- create or update a merchant account and set general details.
- add or update the configuration for an acquirer link that is used by the merchant for payment processing.
- add or update payment configuration details for an existing merchant.
You can initiate requests for updating merchant details in any order after you have successfully created the merchant using the Update Merchant or Create or Update Merchant request. You must send the Approve Merchant request to enable the changes to take effect.
Note the following before building your integration:
- All the requests for the Merchant Boarding API are idempotent, which means if you re-submit an identical request, the Merchant Boarding 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 account, if you do not provide a field in the request, then the Merchant Boarding API overwrites the existing value for that field with NULL. For example, if you have created a merchant account with the trading identifier (merchant.tradingId), and you do not provide this field in a subsequent Update Merchant or Create or Update Merchant request, then the existing value for the trading identifier is erased.
- 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 Merchant Boarding API and Merchant Manager may be used interchangeably to create/update merchant account details at any time throughout the merchant boarding process. For functionality that is currently not supported via the Merchant Boarding API, but via Merchant Manager only, see the last section.
Benefits of Create Or Update Merchant operation
- The CreateOrUpdate API operation enables the MSO to add or update a merchant account in a single API call.
- The API is aligned with the Retrieve Merchant API response, enabling an MSO to retrieve a merchant configuration and submit the entire merchant configuration with any changes.
- The API operation allows you to add or update multiple acquirer links, removing the need to submit multiple API calls and supports the removal of acquirer links.
Update a Merchant Account Information
When updating or creating a merchant account, you must submit all merchant fields that you want to retain. If you omit a field, such as merchant address or acquirer link, the field is set to NULL and the data is removed. It is recommended to use the following steps for integration.
For any change such as update field, delete field, and add field to the merchant configuration:
- Call the Retrieve Merchant operation. It will return actual values for the fields that are populated. Fields that are left blank will not be returned.
- Make the necessary changes to all fields that it returns.
- Changes: update the returned value with a new value.
- Deletions: remove the field from the next step.
- Additions: provide the name of the new field and its value. For more information about all available fields, refer to CreateOrUpdate operation.
All mandatory fields must be completed for the Create or Update operation to succeed. - Submit all fields, including updated fields, through the Create or Update operation.
Limitations of the Merchant Boarding API
In the current release of the Merchant Boarding API, the following limitations apply to creating/updating merchant accounts. You can use Merchant Manager to work around these limitations.
- You cannot delete a merchant.
You can delete merchant accounts (irrespective of whether they are approved or not) in Merchant Manager only if you have the privilege 'Delete Merchant Profile' and if there are no transactions against that merchant account. - If you create a new merchant account with the same identifier as an existing account, the new account details override the existing account details.
- You cannot update an existing token repository.
- You cannot update an existing Interceptas tenant profile. In addition, you cannot change the Interceptas tenant profile assigned to a merchant if the mechant currently has a profile assigned and is the lead merchant for that profile.