Block an email, card, IP range or country

Adds a value to the brand's blocklist in the mode of the request. From the next attempt on, checkout and auto-reload refuse payments that match it (risk_payment_declined for the buyer, without saying why):

email: the customer's address (any case);
card_fingerprint: the processor's fingerprint of a card number (Stripe card.fingerprint; a risk evaluation shows it), so the same card is refused whatever its expiry or the customer;
ip_range: CIDR such as 203.0.113.0/24 or 2001:db8::/32, at most /24 (IPv4) or /48 (IPv6) narrow, since Ownrecord keeps only the truncated network of an address; a bare address blocks its /24;
country: an ISO country code, matched against the IP country, the billing country and the card's country.

Values are stored normalised (the answer shows how). A value already listed is risk_blocklist_entry_exists.

At a glance

REST: POST /api/v1/risk/blocklist
MCP tool: risk_blocklist_create
Operation ID: risk.blocklist.create
Scope: Brand
Permission: customers:write
Risk tier: write
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the customers:write scope
Since: M9

Request

Body

A JSON object (Content-Type: application/json):

Field	Type	Required
`kind`	one of `email`, `card_fingerprint`, `ip_range`, `country`	Yes
`value`	string	Yes
`reason`	string	No

Response

201 Created with a JSON object:

Field	Type	Description
`id`	`rbl_…` ID
`object`	`"risk_blocklist_entry"`
`livemode`	boolean
`brandId`	`brd_…` ID
`kind`	one of `email`, `card_fingerprint`, `ip_range`, `country`
`value`	string
`reason`	string or null
`source`	one of `operator`, `review`
`evaluationId`	`rsk_…` ID or null
`createdBy`	string
`createdAt`	date-time

Examples

Block a card tester's email

HTTP

POST /api/v1/risk/blocklist
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "kind": "email",
  "value": "Card.Tester@Example.com",
  "reason": "Tried six cards in ten minutes"
}

Response (201):

JSON

{
  "id": "rbl_01m4ttwd3veh9apbewxheq5xr2",
  "object": "risk_blocklist_entry",
  "livemode": true,
  "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
  "kind": "email",
  "value": "card.tester@example.com",
  "reason": "Tried six cards in ten minutes",
  "source": "operator",
  "evaluationId": null,
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-20T09:00:00.000Z"
}

Block an IP network

HTTP

POST /api/v1/risk/blocklist
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "kind": "ip_range",
  "value": "203.0.113.77"
}

Response (201):

JSON

{
  "id": "rbl_01m4ttwd3veh9apbewxheq5xr9",
  "object": "risk_blocklist_entry",
  "livemode": true,
  "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
  "kind": "ip_range",
  "value": "203.0.113.0/24",
  "reason": null,
  "source": "operator",
  "evaluationId": null,
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-20T09:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The value isn't one of its kind, or the IP range is narrower than /24 (/48).	Fix the fields listed in `details.issues` and send the request again.
`risk_blocklist_entry_exists`	409	The value is already on the blocklist (`details.entryId`).	Nothing to do: `details.entryId` is the existing entry. Delete it first to change its reason.
`permission_denied`	403	You can't change this brand's customers.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, scope_required, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Block a card tester's email#

Block an IP network#

Errors#