Skip to content

Board merchants on Silverflow

Let Ginger create your merchants and acceptors at Silverflow automatically, or enter the acceptor keys yourself, in the Admin portal or with the Boarding API.

For acquirers on Silverflow. Before a project can process payments, its merchant and one acceptor per scheme must exist at Silverflow. Ginger can create them for you when you save the project's Silverflow contract, or you create them yourself and enter the acceptor keys. This works for both Silverflow contracts, silverflow-v2 and silverflow-oct.

Boarding modes

You choose the mode with boarding_mode (Boarding mode in the Admin portal):

ModeWhat Ginger doesYou provide
full-merchantCreates the Silverflow merchant and an acceptor per schemePer scheme the bin_key and mid
acceptors-onlyCreates an acceptor per scheme under an existing Silverflow merchant, and updates that merchantThe merchant_key, and per scheme the bin_key and mid
disabledNothing: no boardingPer scheme the acceptor_key you created at Silverflow
  • BIN key (bin_key): the reference to your BIN at Silverflow, such as bin-EXAMPLEBIN00000001.
  • MID (mid): the merchant ID you assign to the merchant for that scheme.
  • Merchant key (merchant_key): the Silverflow merchant, such as mct-EXAMPLEMERCHANT0001.
  • Acceptor key (acceptor_key): the acceptor of the project for one scheme, such as mac-EXAMPLEACCEPTOR003.

A Ginger merchant maps to one Silverflow merchant. With full-merchant, Ginger reuses the merchant key of another project of the same merchant with the same status, so a second project doesn't create a second Silverflow merchant.

Automatic boarding is always on

Automatic boarding is switched on for every platform. If a saved contract doesn't get a boarding status, contact Ginger support.

When boarding runs

Ginger boards each time you create or update a project that has a Silverflow contract with full-merchant or acceptors-only, and a status of active-testing or active-production. Boarding runs in the background and usually takes up to a minute.

  • A project in active-testing is boarded in the Silverflow sandbox, a project in active-production in production.
  • When the contract already has a merchant key or acceptor keys, Ginger updates the merchant and acceptors at Silverflow with the current details instead of creating new ones.
  • Only the schemes in schemes are boarded. Add a scheme later and save to board it.

What boarding needs

Fill in these fields before you save the contract. A missing field fails the boarding.

WhereRequired
MerchantCompany name. A billing address with address line 1, postal code, city and country. A website URL
Phone numberAn international phone number, such as +31201234567, of the merchant's general contact person, or else of the merchant
ProjectTrade name, description, MCC, and status active-testing or active-production
Silverflow contractboarding_mode, and per scheme the bin_key and mid. With acceptors-only, also the merchant_key

Silverflow receives the company name as the merchant's name, the trade name as the acceptor's doing-business-as name, and the project description as the acceptor's description.

Add the Silverflow contract

Board the merchant

Follow Board a merchant up to Add the contracts: it covers the contact person, the billing address, the card permissions and the project's MCC that boarding needs.

Configure the Silverflow contract

Go to Payment Method Contracts, switch on Silverflow and open it. Choose the Boarding mode:

  • full-merchant for every project. For a merchant's next project, Ginger reuses the Silverflow merchant of its other projects with the same status, test or live.
  • acceptors-only only to add the project to a specific Silverflow merchant. Enter its Merchant key: copy it from the Silverflow contract of a project of the merchant with the same status: the sandbox and production have their own merchant keys.

Under Schemes, add each scheme the project accepts. For each scheme, set Charge type and enter the Bin Key and the Mid. Leave Acceptor Key empty: Ginger fills it in.

Save and check the boarding status

Select Save. After up to a minute, refresh the page. The contract shows Boarding Status Boarding succeeded, the Merchant Key, and per scheme the Acceptor Key and Boarding Status.

Errors

The contract validation rejects a contract that can't be boarded:

ContractRejected when
Any modeboarding_mode or schemes is missing, or a scheme other than visa, mastercard or (in silverflow-v2 only) bancontact
full-merchant or acceptors-onlyA scheme has no bin_key or mid
acceptors-onlymerchant_key is missing
disabledA scheme has no acceptor_key

When boarding itself fails, Ginger saves the reason in boarding_status, on the contract and per scheme. Boarding status Boarding failed. Missing ... names the fields that were empty; ... is invalid means Silverflow rejected the value, for example a phone number that isn't an international number. A scheme whose acceptor failed shows Error. ....

The message namesFix
Merchant - company nameThe merchant's company name
Merchant - billing address: ...The merchant's billing address: address line 1, postal code, city or country
Merchant - website URLThe merchant's website URL
Merchant - general contact person's phone numberThe phone number of the general contact person, in international format
Project - MCC, Project - trade name, Project - descriptionThe project's mcc, trade_name or description
Project Silverflow Contract - MID (per scheme)schemes.<scheme>.mid
Project Silverflow contract - BIN key (per scheme)schemes.<scheme>.bin_key

Fix the field and save the project again: Ginger retries the boarding.

Next steps