Dynamic 3-D Secure rules
Decide per project when a card payment asks for 3-D Secure, based on the country that issued the card.
By default, Ginger authenticates every card payment with 3-D Secure (3DS), except merchant-initiated transactions. With dynamic 3DS rules you change that per project: for example, prefer not to request 3DS for cards issued outside the EEA, where Strong Customer Authentication doesn't apply.
For projects that process cards through Silverflow or Rapyd. The rules live in the project's contract of that processor.
How rules work
A rule has a name, one or more conditions, an action, and an on/off switch.
| Part | Options |
|---|---|
| Condition | The country that issued the card is one of (in) or is not one of (not_) a list of countries (ISO 3166-1 alpha-2 codes) |
| Action | Always request 3DS (always) or Prefer not to request 3DS (prefer_) |
| Enabled | Only enabled rules are evaluated |
Ginger evaluates the rules when a card payment starts:
- The rules are evaluated in order. The first enabled rule whose conditions all match decides; later rules are ignored.
- When no rule matches, or when Ginger can't determine the issuing country, the payment asks for 3DS.
- Rules apply to card payments (
credit-card) and Google Pay (google-pay). - Prefer not is a preference, not a guarantee: whether the payment is authenticated without 3DS also depends on the processor and the issuer.
The result is recorded on the transaction as a dynamic_ event, with dynamic_ set to
skip_ or require_.
Add rules
- Open the merchant, go to Projects and open the project.
- Open the Payment Method Contracts tab and click the Silverflow or Rapyd contract.
- Edit the contract. In the dynamic 3DS rules field, add a rule:
- Name: a label, for example
Non EU cards, skip 3DS. - Enabled: tick Evaluate this rule on incoming payments.
- Conditions: pick is one of or is not one of and the countries. All conditions must match.
- The action: Always request 3DS or Prefer not to request 3DS.
- Name: a label, for example
- Order the rules with the arrows. The first matching rule wins.
- Click Save contract.
Send the rules in dynamic_ with an update of the project contract. Use the contract silverflow-v2 for Silverflow and rapyd for Rapyd. The list you send replaces the existing rules;
the other fields of the contract stay as they are.
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 '{
"dynamic_3ds_rules": [
{
"name": "Skip 3DS for US and CA cards",
"conditions": [
{ "field": "card_issuing_country", "operator": "in", "value": ["US", "CA"] }
],
"action": { "request_3ds": "prefer_not" },
"enabled": true
}
]
}'The response holds the fields of the contract. To remove all rules, send an empty list. See Update a project contract in the API reference.
Related
- Processor contracts
- 3-D Secure in the payment acceptance docs
- Dynamic 3DS rules for Silverflow (July 2025) and for Rapyd (October 2025) in the changelog