Merchant Onboarding

Creating Merchants and Acceptors

A new merchant entity and new acceptor entities must be created to onboard a new merchant for processing charges. Here are the steps and methods for doing so:

Creating Merchants

A new merchant can be created using the Create a Merchant endpoint:

Creating Acceptors

There are two options for creating acceptors:

Create an Acceptor Individually. Use the Create an Acceptor endpoint to create individual acceptors for a specific merchant:

Create Merchants and Acceptors Using a Template Use the Create a Merchant endpoint with a merchant acceptor template to create merchants and their corresponding acceptors in a single API call. A merchant acceptor template creates multiple merchant acceptors in bulk using an array of BINs. The created acceptors will share the same properties, such as mid, doingBusinessAsName, and mcc.

Merchant Screening

Specific card networks mandate merchant screening to ensure that newly onboarded merchants or their beneficiaries are not blacklisted. Silverflow provides the Merchant Screening endpoint for this purpose. Currently, supported network screening services include:

MATCH
VMSS

Acquirers can also perform merchant screening directly via the card network portals. For specific instructions on handling this on the Silverflow platform, contact your Silverflow representative.

Updating Acceptors

Merchant acceptors are versioned and must be updated to ensure accurate information for processing charges. The update process involves two steps:

Update an Acceptor:

Call the Activate an Acceptor endpoint with an empty body to finalize the changes.

Updating merchants

To update merchant information, follow these steps:

Update a Merchant endpoint to change the necessary details on the merchant entity.
Update an Acceptor endpoint with an empty body to apply changes on the Merchant to the Acceptor.
Activate an Acceptor endpoint to activate the updated version.

Adding Routes

A route is an optional string property for merchant acceptors. It ensures the uniqueness of merchant acceptors when multiple acceptors are created for a given merchant and card network. Routes can be specified at creation or updated later by updating acceptors.

Processing Charges Using Routes

When creating charges, use the merchantAcceptorResolver property in one of two ways:

Using merchantAcceptorKey:

Using merchantKey with optional route:

This method combines the route with the merchant key and network to identify the unique merchant acceptor. This ensures that charges are routed to the correct and desired network and BIN.

Using Acceptors Without a Route

If a unique acceptor can be determined, the merchantAcceptorResolver can operate at the merchant level without a route. For example, if only one Visa acceptor is connected to the merchant, it will work without specifying a route.

Using Acceptors With a Route

If a route is used, multiple acceptors with the same data but unique routes can be created. Both merchantAcceptorKey and merchantKey with the route can be used for processing charges.

Using Acceptors With an Empty Route

Creating or updating a merchant acceptor with an empty route allows for multiple acceptors with the same data and an empty route. This scenario requires specifying a unique route for creating additional acceptors with the same data.

Blocking an Acceptor

To temporarily restrict a merchant from processing new charges, set restrictions.blockCharges to true at the merchant acceptor level and activate the draft version. Unblock by setting blockCharges to false and reactivating.

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

Restricting the acceptor will only block new charges; it will not affect actions on existing charges, such as reversals or refunds.

Archiving an Acceptor

Archiving is an irreversible action. To permanently stop a merchant from processing new charges, archive all merchant acceptors by calling the Archive an Acceptor endpoint.

Archiving the merchant entity will not automatically archive the acceptors underneath it.

Routing Configuration Options

There are two options for configuring merchants and merchant acceptors:

Merchant-Level Endpoints: Use the same properties for all merchant acceptors under a single merchant.
Merchant Acceptor-Level Endpoints: Set different properties for each acceptor.

Routes need to be specified when creating multiple merchant acceptors for the same card network under the same merchant, multiple binKeys under the same card network.

For charge routing:

Use merchantKey in merchantAcceptorSelector for merchant-level endpoints.
Use merchantAcceptorKey in merchantAcceptorSelector for acceptor-level endpoints.