Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and stablecoin payments, embed digital wallets into your product or service, or power your internet marketplace.

Cards and Payments Risk Evaluation

What is “Risk Evaluation”?

When you create a card or process a payment. with Circle Payments / Marketplaces 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 and payment creation.

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 or payment creation 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

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

3000-3099

Processor / Issuing Bank

Card / 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

Card / 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

Card / 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-3899

The specific reason codes that apply currently are documented below.

Reason Code

Explanation

Circle Blocked

3000

Prohibited Issuer (Bank) Country

3001

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)

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

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 about a month ago



Cards 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.