Board a merchant
From a signed merchant to one that is ready to test: its permissions, users, test project and contracts, and the hand-over. In the Admin portal or with the Boarding API.
A new merchant has signed with you and needs to take payments. Boarding gets it ready: you record who it is and what it may do, give its staff a login, add its webshop or app, connect it to a processor and set up how it gets paid. You do each step in the Admin portal, or your developers automate it with the Boarding API.
When you're done, the merchant has a project in test mode, its staff can log in, and its developers have what they need to integrate. Then you test it.
Before you begin
- You have access to the Admin portal, or an admin API key for the Boarding API.
- Acquirers on Silverflow: your BIN key and the merchant's MID per card scheme.
- PayFacs and ISOs: ask your processor to board the merchant now, as that can take a while. You need the merchant's credentials from your processor when it goes live.
- You know how merchants, projects, users and roles relate: see Merchant hierarchy.
Acquirers on Silverflow: collect these details first
Ginger boards the merchant at Silverflow when you save the contract, and the boarding fails without: a website URL and
a billing address on the merchant, an international phone number (such as +31201234567) of its general contact
person or else of the merchant, and the merchant category code (MCC) of the project. See
what boarding needs.
Board the merchant
Create the merchant and its permissions
- Go to Merchants and click Create Merchant.
- Enter the Company name, the Email and, optionally, an External ID: your own identifier of the merchant.
- Click Create Merchant. The merchant starts with status
pending. - Open the merchant, edit its permissions and give it the payment methods it may use. These base permissions are the boundary for the permissions of its projects, roles and users. Click Save permissions.
Create the merchant. Set base_, the most the merchant and its projects, roles and users may ever do,
and give it the payment methods it may use, as / paths.
curl https://api.example.com/v1/admin/merchants/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"company_name": "Acme Coffee B.V.",
"status": "pending",
"email": "ops@example.com",
"base_permissions": {
"/merchants/self/": { "GET": true },
"/orders/**": { "*": true },
"/payment-methods/credit-card/": { "POST": true }
}
}'The response is the merchant with its id: use it as $MERCHANT_ in the next steps. See
Create a merchant in the API reference for the company details,
addresses and the other fields.
Create roles and users
Give the merchant an admin role with full access, and other roles as needed, such as support or finance. Then create the merchant's first user, its admin and primary contact, and give it the admin role. Each email address can be used by one user only.
A merchant created in the Admin portal already has four roles: Merchant Administrator, Merchant Support, Merchant Manager and Merchant Member. Use Merchant Administrator for the admin, or add your own roles:
- Go to Roles, click Create Role, enter a Name and Description, and save. Edit the Role permissions: they can't exceed the merchant's permissions.
- Go to Users, click Create User, enter the Name, the Email and a phone number in international
format, such as
+31201234567, and pick the Roles. Type a Password for the user, or click Generate new password, and pass it on to the user safely. The user's Status isactiveunless you choose another. Save.
Create a role with its permissions:
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/roles/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"name": "Merchant administrator",
"permissions": {
"/merchants/self/": { "GET": true },
"/merchants/self/*/**": { "*": true },
"/orders/**": { "*": true }
}
}'See Create a role in the API reference.
Then create a user with the id of the role:
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/users/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"legal_name": "Alex Example",
"email": "alex@example.com",
"roles": ["'"$ROLE_ID"'"]
}'See Create a user in the API reference.
Complete the details
- Open the merchant, go to Details and click Edit.
- Fill in the Website URL, Phone numbers, Addresses (with a Billing address), Locale, VAT number and Chamber of commerce number, and optionally tags. Select the user you created as the primary contact: Silverflow calls it the general contact person. Click Save changes.
Update the merchant with the fields you didn't send yet. An update merges what you send into the merchant; fields you
leave out keep their value. company_ is required in every update. Set the general, technical and
financial contact persons in contact_, as user IDs. See
Update a merchant in the API reference.
Create the test project
A project is one webshop or app of the merchant, with its own API key, webhook URL and payment methods. A merchant has
a test project and a live project for each. Create the test project now, with status active-testing: it takes test
payments only. You create the live project when the merchant goes live. See
Project statuses.
- Go to Projects and click Create Project.
- Enter the Trade Name (the name shoppers see), Description, Website URL, Webhook URL, Status and, optionally, the External Project ID.
- Click Create Project.
- On Silverflow: open the project, click Edit, add the MCC and save.
Create a project. trade_, description, website_ and status are required. Without permissions, the
project gets the merchant's base permissions.
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"trade_name": "Acme Coffee",
"description": "Acme Coffee webshop",
"status": "active-testing",
"website_url": "https://www.example.com/",
"webhook_url": "https://www.example.com/webhook/",
"mcc": "5814"
}'mcc is the merchant category code; Silverflow needs it. The response holds the project id and its apikey. Give the API key to the merchant; it's what the merchant uses
with the Order API. See Create a project
in the API reference.
Add the contracts
Give the test project the contract of each processor or payment method it uses. The fields depend on the contract type: see Processor contracts and the connector pages.
The test credentials of your card processors are set on your platform: PayFacs and ISOs don't enter the merchant's credentials on a test project. Vipps MobilePay and Swish are the exception: see their pages. You enter those in the live project's contract when the merchant goes live.
- Acquirers on Silverflow: you don't enter credentials either, but Ginger boards the merchant at Silverflow. Choose
the boarding mode
full-merchant, and per card scheme enter your BIN key and the merchant's MID. When you save, Ginger creates the merchant in the Silverflow sandbox. Check that the boarding status is "Boarding succeeded". See Add the Silverflow contract. - PayFacs and ISOs: switch on your processor's contract and set its currencies, card brands and capture mode. See the contract of Elavon, Rapyd, Shift4 or IPG.
If the merchant takes one-click or recurring card payments, switch them on in the merchant's card settings: they're off by default.
- Open the project and go to the Payment Method Contracts tab.
- Switch on the payment method to give the project permission for it.
- Click the contract, fill in the fields and click Save contract.
Update the project contract. For example, the Rapyd contract of a test project:
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/contracts/rapyd/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--request PUT \
--data '{ "brands": ["visa", "mastercard"], "manual_capture_enabled": true }'See Update a project contract in the API reference for the fields of each contract type.
For Silverflow, send the silverflow-v2 contract with a boarding_: see
Add the Silverflow contract.
Set up 3-D Secure and fraud prevention
Optional. Ginger fraud rules always apply to every project. Add rules, or screen the project's payments with SEON or Cybersource too: see Fraud prevention. To decide when 3-D Secure runs, see Dynamic 3-D Secure rules.
Set up payouts and fees
Only when your platform pays out the merchant with Ginger Payout, for acquirers on Silverflow. Your Ginger contact switches Ginger Payout on for your platform on request. Add a payout configuration with a schedule, a bank account and a price plan. See Payouts and fees.
Activate the merchant
Set the merchant's status to active. Its test project still takes test payments only.
Open the merchant, go to Details, click Edit, set the Status to active and click Save changes.
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
"company_name": "Acme Coffee B.V.",
"status": "active"
}'See Update a merchant in the API reference.
Hand over to the merchant
Send the merchant what it needs to start:
- Its login. The email address and password of its admin user, through a secure channel. Its staff log in to the Merchant portal.
- Its API key. The project's API key is on the project's Integration tab, and in the merchant's own Merchant portal. Its developers use it with the Order API.
- The payment acceptance docs. Send its developers to the payment acceptance docs and their go-live checklist.
Next steps
- Processor contracts: what each contract holds, capture modes and card settings.
- Take a test payment with the merchant's test project.
- Terminate a merchant when it stops.
- Style the hosted payment page of the project: optional.