Skip to content

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

flowchart
At SilverflowIn Ginger
Your BINs, each with a BIN keyA merchant with one or more projects
A Silverflow merchant, with a merchant keyThe merchant_key in the project's Silverflow contract
One acceptor per scheme, with an acceptor keyThe schemes of the project's Silverflow contract, each with its acceptor_key, bin_key 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:

ContractAdmin portal nameFor
silverflow-v2SilverflowCard payments: purchases, and Account Funding Transactions. Visa, Mastercard and Bancontact
silverflow-octSilverflow OCTOriginal Credit Transactions (OCT): payouts to a card. Visa and Mastercard

A project can have both. Both contracts have:

  • boarding_mode: how the merchant and acceptors are created at Silverflow. See Board merchants on Silverflow.
  • merchant_key: the Silverflow merchant.
  • schemes: one entry per scheme (visa, mastercard, and bancontact in silverflow-v2), with the acceptor_key, or the bin_key and mid that Ginger uses to create the acceptor.

silverflow-v2 also has currencies, dynamic_3ds_rules (see 3-D Secure rules), manual_capture_enabled and delayed_capture_enabled (see Contracts). Per scheme, charge_type is charge for purchases or funding-charge for AFTs.

silverflow-oct sets per scheme the payout_type, the funding_source (required for Mastercard), and the sender of the funds: sender_is_receiver, or sender_account_number and sender_account_number_type.

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_mode to disabled and send the acceptor_key of each scheme instead. See Boarding modes.

The project also needs permission for /payment-methods/credit-card/ with POST, and for /orders/**: see Permissions.

The legacy silverflow contract

Projects set up before silverflow-v2 may still have a silverflow contract, with flat fields such as acceptor_key_visa and is_aft. 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_authentication_details.

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 3000Frictionless: no action from the customer
More than 3000Challenge: enter code 1234 to authenticate. Any other code fails

Don't use exactly 3000: its flow is undefined.

NetworkCard numberAVS requiredCVC requiredEEA3DSBIN country
Mastercard5413530000000501NoYesYes2.1Belgium
Mastercard5413530000000402NoYesYes2.2Belgium
Mastercard5413530000000303YesYesYes2.2Belgium
Mastercard5286940020000304NoYesNoNoneUSA
Mastercard5286940020000205NoNoNoNoneUSA
Mastercard5286940020000106YesYesNoNoneUSA
Mastercard5286940020000007YesNoNoNoneUSA
Mastercard5286940020000908NoYesNo2.1USA
Mastercard5286940020000809NoYesNo2.2USA
Visa4200350000000801NoYesYes2.1Germany
Visa4200350000000702NoYesYes2.2Germany
Visa4200350000000603YesYesYes2.2Germany
Visa4761070000000004NoYesNoNoneUSA
Visa4761070000000905NoNoNoNoneUSA
Visa4761070000000806YesYesNoNoneUSA
Visa4761070000000707YesNoNoNoneUSA
Visa4761070000000608NoYesNo2.1USA
Visa4761070000000509NoYesNo2.2USA
Bancontact4200351948256042 (co-badged Visa)—NoYesYesBelgium
Bancontact5413530000000006 (co-badged Mastercard)—NoYesYesBelgium

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
123Approved
100005Declined: do not honour
100051Declined: insufficient funds
100165Soft decline: authentication required

The decline amounts are above the challenge threshold: complete the challenge with 1234 first. Silverflow's sandbox documentation lists all amounts.

Next steps