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_ (Boarding mode in the Admin portal):
| Mode | What Ginger does | You provide |
|---|---|---|
full-merchant | Creates the Silverflow merchant and an acceptor per scheme | Per scheme the bin_ and mid |
acceptors-only | Creates an acceptor per scheme under an existing Silverflow merchant, and updates that merchant | The merchant_, and per scheme the bin_ and mid |
disabled | Nothing: no boarding | Per scheme the acceptor_ you created at Silverflow |
- BIN key (
bin_): the reference to your BIN at Silverflow, such askey bin-EXAMPLEBIN00000001. - MID (
mid): the merchant ID you assign to the merchant for that scheme. - Merchant key (
merchant_): the Silverflow merchant, such askey mct-EXAMPLEMERCHANT0001. - Acceptor key (
acceptor_): the acceptor of the project for one scheme, such askey 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-testingis boarded in the Silverflow sandbox, a project inactive-productionin 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
schemesare 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.
| Where | Required |
|---|---|
| Merchant | Company name. A billing address with address line 1, postal code, city and country. A website URL |
| Phone number | An international phone number, such as +31201234567, of the merchant's general contact person, or else of the merchant |
| Project | Trade name, description, MCC, and status active-testing or active-production |
| Silverflow contract | boarding_, and per scheme the bin_ and mid. With acceptors-only, also the merchant_ |
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.
Board the merchant as described in Board a merchant, up to Add the contracts. Then add the Silverflow contract to the project.
Check the merchant and its contact
Get the merchant and check that it has a company_, a
website_, a billing address in addresses, and a general user in contact_.
Get that user and check that it has an international number in
phone_, such as +31201234567.
Add the contract to the project
Make sure the project has its mcc, with an update of the project.
Then set the silverflow-v2 contract. With full-merchant:
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/contracts/silverflow-v2/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
"boarding_mode": "full-merchant",
"schemes": {
"visa": { "charge_type": "charge", "bin_key": "bin-EXAMPLEBIN00000001", "mid": "4321" },
"mastercard": { "charge_type": "charge", "bin_key": "bin-EXAMPLEBIN00000002", "mid": "1234" }
}
}'See Update a project contract in the API reference.
To add the project under a specific Silverflow merchant, use acceptors-only with its merchant key:
{
"boarding_mode": "acceptors-only",
"merchant_key": "mct-EXAMPLEMERCHANT0001",
"schemes": {
"visa": { "charge_type": "charge", "bin_key": "bin-EXAMPLEBIN00000001", "mid": "4322" }
}
}For payouts, set the silverflow-oct contract the same way. It needs a payout_ per scheme and a funding_
for Mastercard.
Check the boarding status
After up to a minute, get the contract:
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/contracts/silverflow-v2/ \
--user "$API_KEY:"The contract now holds the keys and the status of each step:
{
"boarding_mode": "full-merchant",
"boarding_status": "Boarding succeeded",
"merchant_key": "mct-EXAMPLEMERCHANT0001",
"schemes": {
"visa": {
"acceptor_key": "mac-EXAMPLEACCEPTOR004",
"boarding_status": "Boarding succeeded"
}
}
}The response is shortened.
Errors
The contract validation rejects a contract that can't be boarded:
| Contract | Rejected when |
|---|---|
| Any mode | boarding_ or schemes is missing, or a scheme other than visa, mastercard or (in silverflow-v2 only) bancontact |
full-merchant or acceptors-only | A scheme has no bin_ or mid |
acceptors-only | merchant_ is missing |
disabled | A scheme has no acceptor_ |
When boarding itself fails, Ginger saves the reason in boarding_, 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 names | Fix |
|---|---|
Merchant - company name | The merchant's company name |
Merchant - billing address: ... | The merchant's billing address: address line 1, postal code, city or country |
Merchant - website URL | The merchant's website URL |
Merchant - general contact person's phone number | The phone number of the general contact person, in international format |
Project - MCC, Project - trade name, Project - description | The project's mcc, trade_ or description |
Project Silverflow Contract - MID (per scheme) | schemes.<scheme>.mid |
Project Silverflow contract - BIN key (per scheme) | schemes.<scheme>.bin_ |
Fix the field and save the project again: Ginger retries the boarding.
Next steps
- Silverflow: test the project in the sandbox.
- Set up Account Funding Transactions
- Bancontact: add the
bancontactscheme.