flintDocs

Risk controls

Risk controls govern how Flint handles each payment attempt. Merchant-managed rules decide whether an attempt is allowed, blocked, challenged with 3DS, or sent to review; lists hold the values rules match against; reviews queue payments for a manual decision; and fraud warnings record issuer-reported fraud after a payment.

Rules use a strict JSON predicate grammar. Retrieve GET /v1/risk-rules/attributes before authoring rules: risk scoring is not enabled in every environment, and the registry reports which attributes your sandbox or live environment can use. Use POST /v1/risk-previews to validate a candidate rule or an existing rule by ID without changing it.

A review opens only on a payment the bank approved. For a manual-capture payment, approving the review allows a later capture but never captures; for an automatic-capture payment, the money has already been collected and approving only closes the review. Declining cancels an uncaptured payment or refunds a captured one, and may return 202 Accepted while that finishes: poll the review according to Retry-After or subscribe to the review.closed webhook event. Fraud warnings are distinct from the original risk assessment and can later link to a dispute. A payment without risk.score had no score available, not a score of zero.

Reads require the risk.read scope. Review actions require risk.reviews.write. Rule and list changes, and POST /v1/risk-previews, require risk.controls.write.

Note:

For predicate examples, lifecycle guidance, error handling, and webhook behavior, see the Risk Controls guide.

The Risk control object#

Every field on a risk control, as returned by retrieve and carried by the endpoints below.

Attributes

actionablebooleanRequired
created_atstringRequired

RFC3339 timestamp.

disputeobject or null
dispute_idstring or nullRequired
fraud_typeenumRequired
  • card_never_received
  • fraudulent_card_application
  • made_with_counterfeit_card
  • made_with_lost_card
  • made_with_stolen_card
  • unauthorized_use_of_card
  • other
fraud_warning_idstringRequired
payment_intentobject or null
payment_intent_idstringRequired
payment_summaryobjectRequired
reported_atstringRequired

RFC3339 timestamp.

JSON
{
  "actionable": true,
  "created_at": "2026-07-09T18:02:12Z",
  "dispute_id": null,
  "fraud_type": "unauthorized_use_of_card",
  "fraud_warning_id": "fw_123",
  "payment_intent_id": "pi_123",
  "payment_summary": {
    "amount_money": {
      "amount": 12900,
      "currency": "USD"
    },
    "email": "buyer@example.com",
    "last4": "4242",
    "payment_method_brand": "visa"
  },
  "reported_at": "2026-07-09T18:02:11Z"
}

List early fraud warnings#

GET/v1/fraud-warnings

Requires scope risk.controls.write or risk.read or risk.reviews.write

List early fraud warnings for the authenticated merchant environment.

Query parameters

actionableboolean

Filter by whether a proactive fraudulent refund can still prevent a dispute.

payment_intent_idstring

Filter by Flint payment intent ID.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/fraud-warnings \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get an early fraud warning#

GET/v1/fraud-warnings/{fraud_warning_id}

Requires scope risk.controls.write or risk.read or risk.reviews.write

Get an early fraud warning for the authenticated merchant environment.

Path parameters

fraud_warning_idstringRequired

Flint fraud warning ID.

Query parameters

expandarray of enum

Supported expansions: dispute, payment_intent. Expansion requires risk.read plus the read scope for each expanded resource. Limits: at most 10 unique expand paths per request; path depth at most 2. Repeat expand, for example expand=dispute&expand=payment_intent, or pass one comma-separated value.

  • dispute
  • payment_intent

Response · 200

dataobjectRequired
metaobject
request_idstring
curl https://api.withflintpay.com/v1/fraud-warnings/{fraud_warning_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "actionable": true,
    "created_at": "2026-07-09T18:02:12Z",
    "dispute_id": null,
    "fraud_type": "unauthorized_use_of_card",
    "fraud_warning_id": "fw_123",
    "payment_intent_id": "pi_123",
    "payment_summary": {
      "amount_money": {
        "amount": 12900,
        "currency": "USD"
      },
      "email": "buyer@example.com",
      "last4": "4242",
      "payment_method_brand": "visa"
    },
    "reported_at": "2026-07-09T18:02:11Z"
  },
  "request_id": "req_123"
}

List payment reviews#

GET/v1/reviews

Requires scope risk.controls.write or risk.read or risk.reviews.write

List payment reviews for the authenticated merchant environment.

Query parameters

statusarray of enum

Filter by review status. Repeat or comma-separate values.

  • open
  • resolving
  • closed
risk_levelarray of enum

Filter by immutable review risk level. Repeat or comma-separate values.

  • normal
  • elevated
  • highest
  • not_assessed
payment_flowarray of enum

Filter by immutable payment flow. Repeat or comma-separate values.

  • checkout
  • payment_link
  • invoice
  • subscription_initial
  • subscription_renewal
  • virtual_terminal
  • api
payment_intent_idstring

Filter by Flint payment intent ID.

order_idstring

Filter by Flint order ID.

customer_idstring

Filter by Flint customer ID.

created_afterstring

Filter reviews opened after this RFC3339 timestamp.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/reviews \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a payment review#

GET/v1/reviews/{review_id}

Requires scope risk.controls.write or risk.read or risk.reviews.write

Get a payment review for the authenticated merchant environment.

Path parameters

review_idstringRequired

Flint review ID.

Query parameters

expandarray of enum

Supported expansions: customer, order, payment_intent. Expansion requires risk.read plus the read scope for each expanded resource. Limits: at most 10 unique expand paths per request; path depth at most 2. Repeat expand, for example expand=customer&expand=order, or pass one comma-separated value.

  • customer
  • order
  • payment_intent

Response · 200

dataobjectRequired
metaobject
request_idstring
curl https://api.withflintpay.com/v1/reviews/{review_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "closed_at": null,
    "closed_by": null,
    "closed_reason": null,
    "customer_id": "cus_123",
    "ip_address": null,
    "ip_address_location": null,
    "matched_risk_rule_id": null,
    "opened_at": "2026-07-09T18:02:11Z",
    "opened_reason": "rule",
    "order_id": "ord_123",
    "payment_flow": "checkout",
    "payment_intent_id": "pi_123",
    "payment_summary": {
      "amount_money": {
        "amount": 12900,
        "currency": "USD"
      },
      "authorization_expires_at": null,
      "capture_method": "automatic",
      "email": "buyer@example.com",
      "last4": "4242",
      "payment_method_brand": "visa"
    },
    "pending_action": null,
    "refund_id": null,
    "refunded_amount_money": null,
    "resolution_started_at": null,
    "resolution_started_by": null,
    "review_id": "rev_123",
    "risk": {
      "level": "elevated",
      "score": null
    },
    "status": "open"
  },
  "request_id": "req_123"
}

Approve a payment review#

POST/v1/reviews/{review_id}/approveIdempotent

Requires scope risk.reviews.write

Approve a payment review for the authenticated merchant environment.

Path parameters

review_idstringRequired

Flint review ID.

Response · 200

Same response as Get a payment review.

curl -X POST https://api.withflintpay.com/v1/reviews/{review_id}/approve \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Decline a payment review#

POST/v1/reviews/{review_id}/declineIdempotent

Requires scope risk.reviews.write

Decline a payment review for the authenticated merchant environment.

Path parameters

review_idstringRequired

Flint review ID.

Request body

add_to_block_listboolean

Response · 200

Same response as Get a payment review.

curl -X POST https://api.withflintpay.com/v1/reviews/{review_id}/decline \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "add_to_block_list": false
  }'

List risk lists#

GET/v1/risk-lists

Requires scope risk.controls.write or risk.read or risk.reviews.write

List risk lists for the authenticated merchant environment.

Query parameters

include_archivedboolean

Include archived resources.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/risk-lists \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a risk list#

POST/v1/risk-listsIdempotent

Requires scope risk.controls.write

Create a risk list for the authenticated merchant environment.

Request body

aliasstringRequired
item_typeenumRequired
  • card_fingerprint
  • card_bin
  • email
  • email_domain
  • ip_address
  • country
  • customer_id
  • string
  • case_sensitive_string
namestringRequired

Response · 201

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/risk-lists \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "alias": "",
    "item_type": "card_fingerprint",
    "name": ""
  }'

Get a risk list#

GET/v1/risk-lists/{risk_list_id}

Requires scope risk.controls.write or risk.read or risk.reviews.write

Get a risk list for the authenticated merchant environment.

Path parameters

risk_list_idstringRequired

Flint risk list ID.

Response · 200

Same response as Create a risk list.

curl https://api.withflintpay.com/v1/risk-lists/{risk_list_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a risk list#

PATCH/v1/risk-lists/{risk_list_id}Idempotent

Requires scope risk.controls.write

Update a risk list for the authenticated merchant environment.

Path parameters

risk_list_idstringRequired

Flint risk list ID.

Request body

namestringRequired

Response · 200

Same response as Create a risk list.

curl -X PATCH https://api.withflintpay.com/v1/risk-lists/{risk_list_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": ""
  }'

Retire a risk list#

DELETE/v1/risk-lists/{risk_list_id}Idempotent

Requires scope risk.controls.write

Retire a risk list for the authenticated merchant environment.

Path parameters

risk_list_idstringRequired

Flint risk list ID.

Response · 200

Same response as Create a risk list.

curl -X DELETE https://api.withflintpay.com/v1/risk-lists/{risk_list_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

List risk list items#

GET/v1/risk-lists/{risk_list_id}/items

Requires scope risk.controls.write or risk.read or risk.reviews.write

List risk list items for the authenticated merchant environment.

Path parameters

risk_list_idstringRequired

Flint risk list ID.

Query parameters

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/risk-lists/{risk_list_id}/items \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Add risk list items#

POST/v1/risk-lists/{risk_list_id}/itemsIdempotent

Requires scope risk.controls.write

Add risk list items for the authenticated merchant environment.

Path parameters

risk_list_idstringRequired

Flint risk list ID.

Request body

Send exactly one of these

valuestringRequired

Response · 200

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/risk-lists/{risk_list_id}/items \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "values": [
      ""
    ]
  }'

Get a risk list item#

GET/v1/risk-lists/{risk_list_id}/items/{risk_list_item_id}

Requires scope risk.controls.write or risk.read or risk.reviews.write

Get a risk list item for the authenticated merchant environment.

Path parameters

risk_list_idstringRequired

Flint risk list ID.

risk_list_item_idstringRequired

Flint risk list item ID.

Response · 200

dataobjectRequired
metaobject
request_idstring
curl https://api.withflintpay.com/v1/risk-lists/{risk_list_id}/items/{risk_list_item_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete a risk list item#

DELETE/v1/risk-lists/{risk_list_id}/items/{risk_list_item_id}Idempotent

Requires scope risk.controls.write

Delete a risk list item for the authenticated merchant environment.

Path parameters

risk_list_idstringRequired

Flint risk list ID.

risk_list_item_idstringRequired

Flint risk list item ID.

Response · 200

Same response as Get a risk list item.

curl -X DELETE https://api.withflintpay.com/v1/risk-lists/{risk_list_id}/items/{risk_list_item_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a risk preview#

POST/v1/risk-previews

Requires scope risk.controls.write

Create a risk preview for the authenticated merchant environment.

Request body

Send exactly one of these

actionenumRequired
  • allow
  • block
  • review
  • require_3ds
predicateone ofRequired

Response · 200

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/risk-previews \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "allow",
    "predicate": {},
    "risk_rule_id": ""
  }'

List risk rules#

GET/v1/risk-rules

Requires scope risk.controls.write or risk.read or risk.reviews.write

List risk rules for the authenticated merchant environment.

Query parameters

include_archivedboolean

Include archived resources.

page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/risk-rules \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a risk rule#

POST/v1/risk-rulesIdempotent

Requires scope risk.controls.write

Create a risk rule for the authenticated merchant environment.

Request body

actionenumRequired
  • allow
  • block
  • review
  • require_3ds
descriptionstringRequired
enabledboolean
predicateone ofRequired

Response · 201

dataobjectRequired
metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/risk-rules \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "action": "allow",
    "description": "",
    "predicate": {}
  }'

Get a risk rule#

GET/v1/risk-rules/{risk_rule_id}

Requires scope risk.controls.write or risk.read or risk.reviews.write

Get a risk rule for the authenticated merchant environment.

Path parameters

risk_rule_idstringRequired

Flint risk rule ID.

Response · 200

Same response as Create a risk rule.

curl https://api.withflintpay.com/v1/risk-rules/{risk_rule_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a risk rule#

PATCH/v1/risk-rules/{risk_rule_id}Idempotent

Requires scope risk.controls.write

Update a risk rule for the authenticated merchant environment.

Path parameters

risk_rule_idstringRequired

Flint risk rule ID.

Request body

Send at least one of these

actionenumRequired
  • allow
  • block
  • review
  • require_3ds
descriptionstring
enabledboolean
expected_versioninteger

Optional risk rule version last read by the caller.

predicateone of

Response · 200

Same response as Create a risk rule.

curl -X PATCH https://api.withflintpay.com/v1/risk-rules/{risk_rule_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "action": "allow",
    "description": "",
    "enabled": false,
    "expected_version": 0,
    "predicate": {}
  }'

Retire a risk rule#

DELETE/v1/risk-rules/{risk_rule_id}Idempotent

Requires scope risk.controls.write

Retire a risk rule for the authenticated merchant environment.

Path parameters

risk_rule_idstringRequired

Flint risk rule ID.

Query parameters

expected_versioninteger

Optional risk rule version last read by the caller.

Response · 200

Same response as Create a risk rule.

curl -X DELETE https://api.withflintpay.com/v1/risk-rules/{risk_rule_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get the risk rule attribute registry#

GET/v1/risk-rules/attributes

Requires scope risk.controls.write or risk.read or risk.reviews.write

Get the risk rule attribute registry for the authenticated merchant environment.

Response · 200

dataobjectRequired
metaobject
request_idstring
curl https://api.withflintpay.com/v1/risk-rules/attributes \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Was this helpful?