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 at onboarding

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.

Creating Merchants & Acceptors using the merchantAcceptorTemplate

While creating Acceptors using the merchantAcceptorTemplate the merchant.merchantAcceptorTemplate.routes property can be used to specify the routes.

If no route is specified, only one Acceptor per network can be created and each acceptor will have by default an empty (“”) route.

Creating Merchants & Acceptors individually

While creating Acceptors individually, the acceptor.route property can be used to specify the unique route.

If no route is specified, then no validations are done and the acceptors are created without any route.

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.

Acceptors created with a “specified” Route

Charges can be processed using either the merchantAcceptorKey or the merchantKey and the “specified” route.

Acceptors created with an empty (“”) Route

Charges can be processed using either the merchantAcceptorKey or only the merchantKey. This is a common scenario when the acceptors are created using the merchantAcceptorTemplate without a route with only one acceptor per network.

Acceptors created without a Route

Charges can only be processed with the merchantAcceptorKey.

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.

American Express Specification

American Express has a specific requirement for clients onboarding merchants using the Payment Facilitator Model. The Card Acceptor Name (Field 43), which is the acceptor.doingBusinessAsName on the Silverflow API must be in the following format: constructed of two elements separated by an "=" delimiter (“Payment Facilitator=Seller DBA Name). The Payment Facilitator name used is typically a 3 character pre-fix that can be discussed with Amex during the onboarding process.

Hence, for all Amex merchant acceptors, clients must create the acceptor with the acceptor.doingBusinessAsName in the above format.

Example

Payment Facilitator name: Silverflow
Seller DBA name: AcmeCorp
acceptor.doingBusinessAsName: SWF=AcmeCorp