Skip to content

Ginger fraud rules

Block payments by card BIN, card country, customer country, IP range or card, per project.

Ginger fraud rules are a denylist per project. By default every payment is accepted. You add rules to block payments by card BIN, by the country that issued the card, by the customer's country or IP address, or by a single card. Ginger fraud rules are always on: you don't need to enable them on your platform, only add rules to a project.

They run next to an external integration such as SEON or Cybersource, if the project has one.

Rule types

Rule typeBlocks a payment whenApplies to
BIN countryThe card was issued in this country.Card payments
BINThe card number starts with this BIN, 2 to 6 digits.Card payments
GeoIP countryThe customer's IP address is located in this country.Payments with a customer IP address
IP rangeThe customer's IP address is in this range, in CIDR notation. IPv4 and IPv6.Payments with a customer IP address
CardThe payment uses this card, identified by the vault token of an earlier order.Card payments

The customer's IP address is the customer.ip_address of the order. When an order has no IP address, the GeoIP country and IP range rules don't apply to it.

Country lookups aren't exact

BIN country: banks sometimes issue cards from the BIN ranges of other banks, and virtual cards and digital banks make mismatches more likely. GeoIP country: Ginger locates IP addresses with MaxMind, which is about 99.8% accurate at country level. IP addresses of mobile networks, business VPNs and privacy networks can be located in another country than the customer.

To block a single card, you need its vault token. Find it in the payment method details of an earlier transaction with that card, in the Admin portal or with the Search API. The rule then shows the card's brand and masked number.

When the rules run

Ginger checks the rules of the project when a transaction starts, before it goes to the processor. A matching rule declines the transaction. Ginger checks in this order: IP range, GeoIP country, BIN country, then BIN and card. The first match declines the transaction.

The rules don't apply to refunds and chargebacks. When a check can't be completed, for example because the card's country is unknown, the transaction continues.

Manage the rules

In the Admin portal, open the merchant, then the project, and go to the Fraud prevention tab. It lists the rules of the project with their type, value and rule ID.

  • To add a rule, select Add rule, choose the rule type and enter the value.
  • To delete a rule, select Delete next to it. The rule stops blocking payments right away. You can't undo this.

Blocked transactions

A transaction declined by a rule gets:

  • A reason that names the rule, such as Blocked by IP: 192.0.2.10 in cidr 192.0.2.0/24.
  • An event declined_by_fraud_prevention with the source ginger_fraud_prevention, a detail with the value that matched, such as the country or IP address, and the rule_type and rule_id of the rule.

Use the rule_id to find the rule, for example to delete it when it blocked a good customer. A transaction declined by an external integration gets the source external_fraud_prevention instead. See Fraud prevention.

Next steps