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.

Risk Evaluation

What is “Risk Evaluation”?

When you create a fiat ( create a card, create a bank account (wires), create a bank account (ACH). ) 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 Unsupported

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 processor partner or 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 Unsupported Configurations

Fiat Account / Payment creation was actioned by Circle's Risk Service due to customer configuration on block list where associated entity was labelled "unsupported".
E.g. Block Issuer Country, Block Card Type, etc.

3500-3599

Customer Fraud Configurations

Fiat Account / Payment creation was actioned by Circle's Risk Service due to customer configuration on block list where associated entity was labelled "fraud".
E.g. Block Issuer Country, Block Card Type, etc.

3600-3699

The specific reason codes that apply currently are documented below.

Reason Code

Explanation

Circle Unsupported

3000

Default

3001

Prohibited Issuer (Bank) Country

3002

Prohibited Billing Address Country

3020

Fiat Account Denied (See Fiat Account for Reason)

3021

Fiat Account Failed (See Fiat Account for Reason)

3022

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

3023

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

3024

Fiat Account Evaluation Suspended. Information has been requested or fiat is awaiting review.

3030

Unsupported Bank Account Routing Number (rtn)

3050

Customer suspended from Payment Processing

3070

Limit for Transaction exceeded

3071

Limit for Daily Aggregate exceeded (email)

3072

Limit for Daily Aggregate exceeded (fiat)

3075

Limit for Weekly Aggregate exceeded (email)

3076

Limit for Weekly Aggregate exceeded (fiat)

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)

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

3500

Blocked Issuer (Bank) Country

3501

Blocked Billing Address Country

3520

Blocked Card Type E.g. Credit

3530 - 3539

Chargeback History on Circle Platform

3540 - 3549

Chargeback History on Customer Platform

3550

Blocked Fiat (Card)

3551

Blocked Email Address

3552

Blocked Phone Number

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

Updated 2 months ago


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.