Merchant Onboarding

Creating Merchants

In order to onboard a new merchant to process charges, a new merchant entity and new acceptor entities need to be created. A new merchant can be created using the Create a Merchant endpoint.

Creating Acceptors

There are two options to create acceptors:

Use the Create an Acceptor endpoint: In this option, merchant acceptors can be created individually for the particular merchant. This allows the acceptors to have specific properties underneath the same merchant.

Use the Create a Merchant endpoint using merchant acceptor template. With this option, merchants and corresponding acceptors can be created with a single API call. A merchant acceptor template is used to create the merchant acceptors in bulk using an array of BINs. The created acceptors will have the same properties like MID, doingBusinessAsName and MCC.

Merchant Screening

Merchant screening is mandated by certain card networks to check whether a newly onboarded merchant or its beneficiary was not recently blacklisted. Silverflow provides the Merchant Screening endpoint as a network agnostic interface. Currently the following network screening services are supported:

MATCH
VMSS

Acquirers have the option to perform merchant screening directly via the card network portals.

Please contact your Silverflow representative about how to handle this on the Silverflow platform.

Updating Acceptors

Merchant acceptors are versioned and must be kept up to date by the client to ensure the information used in processing of charges is accurate. To safeguard erroneous updates from affecting processing, there is a two step process for updating the acceptor:

Use the Update an Acceptor endpoint to update the required information on the acceptor. This creates a draft version of the acceptor with the changes required.

Once the changes are ready to be rolled out, call the Activate an Acceptor endpoint with an empty body in the request.

Updating merchants

In order to update any information on the merchant entity, follow the steps:

Use the Update a Merchant endpoint to update the required information on the acceptor.
Call the Update an Acceptor endpoint with an empty body for the changes on the Merchant to be reflected in the Acceptor.
Call the Activate an Acceptor endpoint to activate the previously created draft version with the new merchant details.

Adding Routes

A route is an optional string property on merchant acceptors. The route can be used where for a given merchant and card network, multiple acceptors need to be created. In such a situation, a route is used to enforce uniqueness of merchant acceptors at the time of creating charges. Routes can be specified at the time of creation of merchant acceptors or at a later point in time by updating the acceptors using the steps described above.

Processing Charges using Routes

When creating charges, there are 2 options within the merchantAcceptorResolver property:

Use the merchantAcceptorKey: This will uniquely identify the merchant acceptor and does not require a route to also be specified in any scenario.

Use merchantKey with optional route: This uses the route in combination with the merchant key and network to identify the unique merchant acceptor. This will allow the charges to be routed to the correct and desired Network and BIN.

Using Acceptors without a Route

The merchantAcceptorResolver will also work on a merchant level without a route if a unique acceptor can be determined. If for example a Visa card is submitted and only a single Visa acceptor is connected to the merchant.

When a Merchant Acceptor is created or updated without a route field, it means multiple Merchant Acceptors with the same data can be created. In such situations, the merchantAcceptorKey needs to be used for processing charges otherwise the request will fail.

Using Acceptors with a Route

When a Merchant Acceptor is created or updated without a route field, multiple acceptors with the same data but the same route will not be created. In this situation, both the merchantAcceptorKey or the merchantKey with route can be used for processing for charges.

Using Acceptors with an Empty Route

A merchant acceptor can also be created or updated with an empty (“”) route. If the merchantAcceptorTemplate is used for creating merchant acceptors, this will be the default scenario. In this situation, both the merchantAcceptorKey or the merchantKey with route can be used for processing for charges. Note that multiple acceptors with the same data and an empty “” route cannot be created. In such scenarios, a unique route must be provided.

Blocking an Acceptor

Clients can temporarily restrict a merchant from processing new charges. This restriction needs to be set at the merchant acceptor level. This provides you the flexibility to only restrict charges for a merchant for one card scheme or for one MCC. As a result, if a legal merchant needs to be blocked then all the acceptors must be blocked individually. The process to block a merchant acceptor is:

Call the Update an Acceptor endpoint with restrictions.blockCharges set to true.

Call the Activate an Acceptor endpoint to activate the previously created draft version.

An acceptor can be unblocked by repeating the above process and setting the restrictions.blockCharges to false.

Note: Restricting the acceptor will only block new charges, not actions on existing charges, for example a reversal or a refund.

Archiving an Acceptor

In order to permanently stop a legal merchant from processing new charges, all the merchant acceptors underneath the merchant needs to be archived. This can be done by calling the Archive an Acceptor endpoint.

Note: Archiving the merchant entity will not automatically archive the acceptors underneath it. Archiving is an irreversible action.

Routing

To create merchants and merchant acceptors, there are 2 options:

Use merchant-level endpoints to use the same properties for all merchant acceptors for a single merchant.
Use merchant acceptor-level endpoints to set different properties for each merchant acceptor for a single merchant.

The two options to configure clients can be used interchangeably. If configuration is specified on merchant level, a merchant acceptor template is used in order to configure the underlying merchant acceptors as the merchant acceptors will still be used for correctly processing charges.A route needs to be specified if you create multiple merchant acceptors for the same card network under the same merchant. This is specified through the combination of a merchant key, a card network and an optional route. When creating charges, there are 2 options.

When using merchant-level endpoints, specify the merchantKey in the merchantAcceptorSelector.
When using merchant acceptor-level endpoints, specify the merchantAcceptorKey in the merchantAcceptorSelector.

This will allow the charges to be routed to the correct and desired Network and BIN.