Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and USDC payments, automate payouts, embed multi-asset accounts into your product or service, or power your internet marketplace.

Cards, Banks and Payments Risk Evaluation

What is “Risk Evaluation”?

When you create a card, a bank account or process a payment with Circle Payments APIs, the response will include a riskEvaluation section.

Risk Evaluation is the response for the check that is executed by Circle's Risk Service. The Risk Service automatically runs checks for every card, bank account and payment.

In the current version of this risk evaluation, this data element will only be present in the response in situations where the decision made by Circle's Risk Service is denied. We plan to subsequently launch additional Risk Management features which will see the expansion of the risk evaluation to decisions other than denied and also to an asynchronous mode.

When Circle's Risk Service sets the status of a card, bank account or payment to denied you should receive a response similar to below:

"riskEvaluation": {
    "decision": "denied",
    "reason": "3000"
},

As you can see, the data element contains two fields:

Field

Data Type

Description

decision

String (enumerated)

The decision made by Circle's Risk Service for this risk evaluation. denied is the only possible value in the current version of the service.

reason

Integer

The reason for the decision. The reason codes are explained in detail below.

Risk Evaluation: Denied Reason Codes

Below are the current reason code categories (or buckets) you will find in the risk evaluation responses.

Reason Code Category (Bucket)

Explanation

Category Code Range

Circle Blocked

Fiat Account / Payment contains criteria that Circle is unable to support at this time.
E.g. Prohibited Country.

3000-3099

Processor / Issuing Bank

Fiat Account / Payment creation contains criteria that Circle's partner processor or the Issuing Bank are unable to accept.
E.g. unsupported issuer country, authorization failure.

3100-3199

Regulatory Compliance Intervention

Interventions by Circle Risk Service due to legal & regulatory compliance requirements.
E.g. KYC verification limits.

3200-3299

Fraud Risk Intervention

Fiat Account / Payment creation was actioned by Circle's Risk Service due to identified fraud management issues.
E.g. Excessive Chargeback Rates, Immediate Fraud Pressure.

3300-3499

Customer Configuration

Unsupported

Fiat Account / Payment creation was actioned by Circle's Risk Service due to customer configuration or request.
E.g. Block Issuer Country, Block Card Type, etc.

3500-3599

Customer Configuration

Fraud

Fiat Account / Payment creation was actioned by Circle's Risk Service due to customer configuration or request.
E.g. User was added to watchlist

3600-3699

The specific reason codes that apply currently are documented below.

Reason Code

Explanation

Circle Blocked

3000

Default

3001

Prohibited Issuer (Bank) Country

3002

Prohibited Billing Address Country

3020

Fiat Account Denied (See Fiat Account for Reason)

3022

Fiat Account (Card) Evaluation Timeout. We recommend retrying.

3023

Fiat Account (Bank Account) Evaluation Timeout. We recommend retrying.

3030

Unsupported Bank Account Routing Number (rtn)

3050

Customer suspended from Payment Processing

Regulatory Compliance Intervention

3200 - 3202

Unsupported Criteria

3210

Withdrawal Limit Exceeded (7 Day Default Payout Limit)

3211

Withdrawal Limit Exceeded (7 Day Custom Payout Limit)

Fraud Risk Intervention

3300

Transaction Pending Circle Risk Review

3310

Fiat Account directly associated with fraudulent activity

3311

Email Address directly associated with fraudulent activity

3330

Fiat Account flagged by Risk Team

3331

Email Account flagged by Risk team

3340

Fiat Account linked to previous fraudulent activity

3341

Email Address linked to previous fraudulent activity

Processor / Issuing Bank

3100

Unsupported Return Code Response from Processor / Issuing Bank - Default

3101

Invalid Return Code Response from Issuing Bank E.g Invalid Card

3102

Fraudulent Return Code Response from Issuing Bank E.g Pickup Card

3103

Blacklisted Entity Return Code Response from Processor E.g Card Blacklisted

3104

Account associated with an invalid ACH RTN

3150

Administrative return from ODFI / RDFI

3151

Return indicating ineligible account from customer / RDFI

3152

Unsupported transaction type return from customer / RDFI

Customer Configuration - Unsupported

3500

Default

3501

Blocked Issuer (Bank) Country

3502

Blocked Billing Address Country

3520

Blocked Card Type E.g. Credit

3530 - 3539

Chargeback/Unauthorized Return History on Circle Platform

3540 - 3549

Chargeback/Unauthorized Return History on Customer Platform

3550

Blocked Fiat (Card)

3551

Blocked Email Address

3552

Blocked Phone Number

Customer Configuration - Fraud

3600 - 3699

Blocked by fraud watchlist

If you are interested in some custom configurations, please contact the Circle Risk team.

Updated 2 months ago



Cards, Banks and Payments Risk Evaluation


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.