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 /: give them to the merchant, and to each project that manages its own rules. See Permissions.
As an admin, use the same paths under /, such as /.
Endpoints
| Rule type | Path | Value field |
|---|---|---|
| BIN country | .../ | country_ |
| BIN | .../ | bin |
| GeoIP country | .../ | country_ |
| IP range | .../ | cidr |
| Card | .../ | vault_, of a card used in an earlier order |
On each of these paths:
GETlists the rules of that type.POSTcreates a rule and returns it with itsrule_, withid 201 Created.DELETEon.../deletes a rule, with{rule_ id}/ 204 No Content.
GET .../ 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_, bins, countries, ips and pans, each rule with its rule_. 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_. See Create an IP range rule in the API reference.
A card rule takes the vault_ of a card from an earlier order, and returns the card's brand and masked_, so you can see which card you blocked.
Delete a rule
Append the rule_ 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 DELETEThe 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.