Skip to content

Fraud prevention rules API

List, create and delete the Ginger fraud rules of a project.

Manage the Ginger fraud rules of a project from your own systems: block a card BIN, the country that issued a card, a country by IP address, an IP range or a single card. The rules work as a denylist. The concepts, and what happens when a rule matches, are in Ginger fraud rules. This page covers the endpoints.

You can manage the same rules in the Admin portal, on the Fraud prevention tab of a project.

Base path and authentication

Every rule belongs to one project:

/v1/merchants/{merchant_id}/projects/{project_id}/fraud-prevention/rules/

Authenticate with an API key or a token, as described in Authentication. The account needs GET, POST and DELETE permissions on /merchants/self/projects/self/fraud-prevention/**: give them to the merchant, and to each project that manages its own rules. See Permissions.

As an admin, use the same paths under /v1/admin/, such as /v1/admin/merchants/{merchant_id}/projects/{project_id}/fraud-prevention/rules/.

Endpoints

Rule typePathValue field
BIN country.../rules/bin-countries/country_code
BIN.../rules/bins/bin
GeoIP country.../rules/countries/country_code
IP range.../rules/ips/cidr
Card.../rules/pans/vault_token, of a card used in an earlier order

On each of these paths:

  • GET lists the rules of that type.
  • POST creates a rule and returns it with its rule_id, with 201 Created.
  • DELETE on .../{rule_id}/ deletes a rule, with 204 No Content.

GET .../rules/ returns all rules of the project at once, grouped by type.

List all rules

curl https://api.example.com/v1/merchants/self/projects/$PROJECT_ID/fraud-prevention/rules/ \
  --user "$API_KEY:"

The response holds the rules of the project per type: bin_countries, bins, countries, ips and pans, each rule with its rule_id. See List all rules in the API reference.

Create a rule

Send the value field of the rule type. For example, block an IP range:

curl https://api.example.com/v1/merchants/self/projects/$PROJECT_ID/fraud-prevention/rules/ips/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{ "cidr": "192.0.2.0/24" }'

The API responds with 201 Created and the rule, with its rule_id. See Create an IP range rule in the API reference.

A card rule takes the vault_token of a card from an earlier order, and returns the card's brand and masked_pan, so you can see which card you blocked.

Delete a rule

Append the rule_id to the path of its type:

curl https://api.example.com/v1/merchants/self/projects/$PROJECT_ID/fraud-prevention/rules/bin-countries/$RULE_ID/ \
  --user "$API_KEY:" \
  --request DELETE

The API responds with 204 No Content. See Delete a BIN country rule in the API reference.

A deleted rule no longer blocks payments. You can't undo a delete: create the rule again instead.

API reference

See List all rules and the other operations under Rules in the API reference for every field.