Silverflow
Process card payments through Silverflow as an acquirer: how Ginger and Silverflow work together, the contracts, the setup steps and the test cards.
For acquirers with their own scheme membership who process on Silverflow. Silverflow is the card processor: it holds your BINs, your merchants and their acceptors, and connects to Visa, Mastercard and Bancontact. Ginger is the gateway in front of it: it boards your merchants at Silverflow, runs the payment pages and 3-D Secure (3DS), keeps card data in its vault, and sends authorisations, captures and refunds to Silverflow with your API keys.
How it works
| At Silverflow | In Ginger |
|---|---|
| Your BINs, each with a BIN key | A merchant with one or more projects |
| A Silverflow merchant, with a merchant key | The merchant_ in the project's Silverflow contract |
| One acceptor per scheme, with an acceptor key | The schemes of the project's Silverflow contract, each with its acceptor_, bin_ and mid |
A Ginger merchant maps to one Silverflow merchant. Each project gets its own acceptors, one per scheme.
Contracts
A project processes on Silverflow when it has a Silverflow contract. There are two:
| Contract | Admin portal name | For |
|---|---|---|
silverflow-v2 | Silverflow | Card payments: purchases, and Account Funding Transactions. Visa, Mastercard and Bancontact |
silverflow-oct | Silverflow OCT | Original Credit Transactions (OCT): payouts to a card. Visa and Mastercard |
A project can have both. Both contracts have:
boarding_: how the merchant and acceptors are created at Silverflow. See Board merchants on Silverflow.mode merchant_: the Silverflow merchant.key schemes: one entry per scheme (visa,mastercard, andbancontactinsilverflow-v2), with theacceptor_, or thekey bin_andkey midthat Ginger uses to create the acceptor.
silverflow-v2 also has currencies, dynamic_ (see 3-D Secure rules),
manual_ and delayed_ (see Contracts). Per scheme,
charge_ is charge for purchases or funding-charge for AFTs.
silverflow-oct sets per scheme the payout_, the funding_ (required for Mastercard), and the sender of the
funds: sender_, or sender_ and sender_.
See the silverflow-v2 and silverflow-oct fields of
Update a project contract in the API reference.
Example
A project with Visa and Mastercard. Ginger creates the merchant and its acceptors at Silverflow:
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",
"currencies": ["EUR"],
"schemes": {
"visa": { "charge_type": "charge", "bin_key": "bin-EXAMPLEBIN00000001", "mid": "4321" },
"mastercard": { "charge_type": "charge", "bin_key": "bin-EXAMPLEBIN00000002", "mid": "1234" }
}
}'If you created the acceptors at Silverflow yourself, set boarding_ to disabled and send the acceptor_ of
each scheme instead. See Boarding modes.
The project also needs permission for / with POST, and for /: see
Permissions.
The legacy silverflow contract
Projects set up before silverflow-v2 may still have a silverflow contract, with flat fields such as
acceptor_ and is_. Ginger still accepts it and shows it as silverflow-v2 (and as silverflow-oct when
OCT was on). A project can't have the legacy contract together with silverflow-v2 or silverflow-oct: when you save
one of the new contracts, Ginger replaces the legacy one. Use silverflow-v2 and silverflow-oct for new projects.
Set up Silverflow
Create your Silverflow API keys
Create a sandbox key and a production key with the right permissions, and share them with your Ginger contact. See Create Silverflow API keys.
Board a merchant
Create the merchant, a user as its general contact, and a project, in the Admin portal or with the Boarding API. See Board a merchant.
Add the Silverflow contract
Add silverflow-v2 (and silverflow-oct for payouts) to the project. Let Ginger create the merchant and acceptors at
Silverflow, or enter the acceptor keys you created yourself. See
Board merchants on Silverflow.
Test in the sandbox
A project in active-testing processes in the Silverflow sandbox. Test with the test cards below, then
your flows: AFT, your own 3DS,
Bancontact.
Go live
Create the merchant's live project, in active-production, with its Silverflow contract. Ginger processes it in the
Silverflow production environment, with your production key, and boards the merchant and acceptors there. Check that
the contract shows Boarding succeeded, then make a first live payment. See Go live.
Scheme compliance
Ginger forwards the data the schemes require through Silverflow: the Mastercard 3DS data, the Mastercard TLID, the sender and receiver data of AFTs and OCTs, and the network references. As the acquirer, you own the compliance. See Scheme compliance.
Your own 3-D Secure
If you run 3-D Secure (3DS) yourself, for example in your own payment page, you send the authentication result
instead of letting Ginger run 3DS. This works with a silverflow-v2 contract, for credit-card and bancontact
transactions. Ginger takes the card from its vault and sends it to Silverflow with your authentication values, without
running 3DS again. The values show on the transaction under external_.
Make sure your PCI DSS compliance covers every system the card details pass through. When the customer's browser sends the card to the vault, the card details don't reach your servers.
For the requests, see External 3-D Secure in the payment acceptance docs.
Test cards
Use these cards in the Silverflow sandbox, with a project in active-testing. For every card use CVC 196 and an
expiry date in the future.
The amount decides the 3DS flow:
| Amount (in cents) | 3DS flow |
|---|---|
| Less than 3000 | Frictionless: no action from the customer |
| More than 3000 | Challenge: enter code 1234 to authenticate. Any other code fails |
Don't use exactly 3000: its flow is undefined.
| Network | Card number | AVS required | CVC required | EEA | 3DS | BIN country |
|---|---|---|---|---|---|---|
| Mastercard | 5413530000000501 | No | Yes | Yes | 2.1 | Belgium |
| Mastercard | 5413530000000402 | No | Yes | Yes | 2.2 | Belgium |
| Mastercard | 5413530000000303 | Yes | Yes | Yes | 2.2 | Belgium |
| Mastercard | 5286940020000304 | No | Yes | No | None | USA |
| Mastercard | 5286940020000205 | No | No | No | None | USA |
| Mastercard | 5286940020000106 | Yes | Yes | No | None | USA |
| Mastercard | 5286940020000007 | Yes | No | No | None | USA |
| Mastercard | 5286940020000908 | No | Yes | No | 2.1 | USA |
| Mastercard | 5286940020000809 | No | Yes | No | 2.2 | USA |
| Visa | 4200350000000801 | No | Yes | Yes | 2.1 | Germany |
| Visa | 4200350000000702 | No | Yes | Yes | 2.2 | Germany |
| Visa | 4200350000000603 | Yes | Yes | Yes | 2.2 | Germany |
| Visa | 4761070000000004 | No | Yes | No | None | USA |
| Visa | 4761070000000905 | No | No | No | None | USA |
| Visa | 4761070000000806 | Yes | Yes | No | None | USA |
| Visa | 4761070000000707 | Yes | No | No | None | USA |
| Visa | 4761070000000608 | No | Yes | No | 2.1 | USA |
| Visa | 4761070000000509 | No | Yes | No | 2.2 | USA |
| Bancontact | 4200351948256042 (co-badged Visa) | — | No | Yes | Yes | Belgium |
| Bancontact | 5413530000000006 (co-badged Mastercard) | — | No | Yes | Yes | Belgium |
Cards with 3DS None authorise without authentication, whatever the amount: use them to test authorisation on its own.
To test 3DS, use the EEA cards.
Ask your Ginger contact which test cards the sandbox treats as Bancontact.
Test outcomes
In the sandbox the amount, not the card, decides whether a payment is declined. Any amount that isn't in Silverflow's sandbox tables is approved. Some amounts that work for Visa and Mastercard:
| Amount (in cents) | Result |
|---|---|
123 | Approved |
100005 | Declined: do not honour |
100051 | Declined: insufficient funds |
100165 | Soft decline: authentication required |
The decline amounts are above the challenge threshold: complete the challenge with 1234 first. Silverflow's sandbox
documentation lists all amounts.