Processor contracts
A contract connects a project to a processor or payment method: the identifiers, credentials, currencies and capture modes it uses.
A contract holds the terms under which a merchant accepts a payment method: the identifiers and credentials of the processor, the card brands and currencies, and the capture modes. Without a contract, a project can't process the payment method, even when it has permission to use it.
Only you, the platform operator, can create and change contracts, in the Admin portal or with the Boarding API. Merchants see their payment methods and switch them on or off, but they can't change a contract.
What a merchant needs to accept a payment method
Three things must be in place:
- Permission. The merchant has the payment method in its base permissions, and the project has permission to use it. See Merchant hierarchy.
- Contract. The project has a contract for the processor, with the identifiers you got from the processor.
- Boarding. The merchant is known at the processor. For Silverflow, Ginger can do this automatically when you save the contract: see Silverflow merchant boarding. For the other processors, you get the identifiers from the processor and put them in the contract.
After that, the merchant switches the payment method on or off per project. Switching it off doesn't end the contract.
Merchant and project contracts
Contracts are stored in contracts on the project, one entry per contract type. The processor contracts in the table
below are project contracts.
The merchant also has contracts, for settings that apply to all its projects. The main one is the merchant's
credit-card contract, with one-click and recurring payments and the card processor of the merchant, see
Merchant card settings.
Every contract has a begin_, an end_ and a funding_: the days to wait with funding after a sale or
capture.
Contract types
The contract type is the key in contracts, such as silverflow-v2. The fields of each type are in the
Boarding API reference; the processor-specific setup is on
the connector pages.
| Processor or payment method | Contract | What it holds | Details |
|---|---|---|---|
| Silverflow: Visa, Mastercard, Bancontact | silverflow-v2 | Boarding mode, per scheme the acceptor key, or the BIN key and MID; currencies, capture modes, dynamic 3DS rules | Silverflow, merchant boarding |
| Silverflow: original credit transactions (OCT) | silverflow-oct | Boarding mode, per scheme the acceptor key or BIN key and MID, payout type, funding source | Silverflow merchant boarding |
| Elavon | ginger-elavon | MID per brand (acceptor_, acceptor_, acceptor_), terminal ID, brands | Elavon |
| Rapyd | rapyd | Access key, secret key, brands, settlement currency, wallet ID, capture modes, dynamic 3DS rules | Rapyd |
| Shift4 | shift4 | Merchant ID, sub-merchant ID, signing key, brands, currencies, capture modes | Shift4 |
| IPG | credit-card, amex | Acceptor ID, brands, currencies, capture modes | IPG |
| Google Pay | google-pay | Your Google merchant ID. Payments run over the card contract | Payment methods |
| Apple Pay | apple-pay | Only the extra domain for host-to-host Apple Pay. Payments run over the card contract | Payment methods |
| Bancontact | bancontact | Bancontact options: QR and wallet-initiated payments. Bancontact through Silverflow runs over the bancontact scheme of silverflow-v2; ask your Ginger contact whether you also need this contract | Bancontact |
| Vipps MobilePay | vipps-mobilepay | Client ID, client secret, subscription key, merchant serial number, currencies | Vipps MobilePay |
| Swish | swish | Swish merchant ID (payee alias) | Swish |
Klarna (pay now, pay later and direct debit), PayPal and MobilePay have
contracts of their own. Allow the payment method in the project's permissions, and fill in its contract on the project's Payment Method Contracts tab.
Click to Pay runs over the card contract: set click_ in the credit-card contract to board the project
for Click to Pay.
Capture modes
A card payment is captured in one of three ways:
| Capture mode | What happens | How to enable |
|---|---|---|
| Sale (default) | The payment is authorised and captured at once | Always on |
| Manual | The amount is reserved; the merchant captures or voids it with the API | manual_ on the contract |
| Delayed | The amount is reserved and captured automatically at the end of the transaction's expiration period (1 hour to 7 days) | delayed_ on the contract |
The capture mode flags exist on the silverflow-v2, rapyd, shift4 and credit-card contracts. When a mode is
off, an order that asks for it is refused. If an order is refused although the mode is on in the processor's
contract, ask your Ginger contact which contract your platform checks. Merchants choose the mode per order with
capture_, see Pre-authorizations.
Low value exemptions
On the project's credit-card contract, low_ lists, per currency, the amount up to which Ginger
tries a low value exemption from 3DS, and whether for sales, recurring and one-click payments, or both. A threshold
of 0 switches the exemption off. See the credit-card fields of Update a project contract
in the API reference.
{
"low_value_exemptions": [
{ "threshold": 3000, "currency": "EUR", "applicable_to": ["sale"] }
]
}The issuer decides whether it accepts the exemption. See also Dynamic 3-D Secure rules.
IPG and Elavon read the low value exemptions from this contract. For other processors, ask your Ginger contact whether they apply.
Merchant card settings
The merchant's credit-card contract holds settings for all card payments of the merchant, whatever the project:
one_ and recurring_ switch on one-click and recurring payments, and gateway sets the card
processor of the merchant. See Update a merchant contract
in the API reference.
One-click and recurring are off by default, and apply to all card payment methods of the merchant, including Apple Pay and Google Pay.
gateway routes the merchant's card payments to another processor than your platform's default, for example when
most merchants run on one processor and a few on another. It only takes effect when routing per merchant is switched
on for your platform.
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/contracts/credit-card/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--request PUT \
--data '{ "one_click_enabled": true, "recurring_enabled": true }'See Recurring payments and One-click payments for how merchants use them.
Payout model and fee source
The credit-card and bancontact contracts also decide who pays the merchant and where the fees come
from: see Fields on merchants and contracts.
Change a contract
- Open the merchant, go to Projects and open the project.
- Open the Payment Method Contracts tab. Each row shows a contract with its begin date, end date and funding delay. The switch gives the project permission for the payment method.
- Click the contract, edit the fields and click Save contract.
The form shows the fields of the contract type, so it follows the same rules as the API.
For the merchant's contracts, open the merchant's Details page.
Update the project contract with the fields you want to set. The fields you send are merged into the contract; the fields you leave out stay as they are.
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 }'The response holds all fields of the contract. You can also send contracts in an update of the whole project, in
contracts.<type>.fields. See Update a project contract
in the API reference.
Legacy and retired contracts
Silverflow has a legacy contract, silverflow, with flat fields such as acceptor_. Ginger shows it as
silverflow-v2 and silverflow-oct, and a project can't have the legacy contract together with one of the new ones.
Use silverflow-v2 and silverflow-oct for new projects.
The contracts of retired payment methods (iDEAL, SEPA Direct Debit, bank transfer, SOFORT, giropay, Payconiq, Afterpay, Billink, Anyday, viacash) are no longer used. When you save permissions, Ginger removes the permissions of these payment methods.