Authorization controls

What authorization controls do

Overview

Authorization controls let you establish rules for card transaction validation. You check merchant category, currency, merchant ID, and country in real-time during:

3DS Authentication: Controls are evaluated during 3D Secure authentication flows

Authorization Requests (0100): Controls are evaluated for authorization messages

Financial Authorization Requests (0200): Controls are evaluated for financial transaction requests

Important: Authorization controls apply only to 3DS authentication and authorization messages (0100, 0200). Clearing messages (0220) are not restricted by these controls.

The system automatically declines transactions that violate any configured authorization control rule.

Control hierarchy

The system evaluates two control levels before approving any transaction. Both levels must approve for a transaction to succeed:

1. Account level

Individual account restrictions. Apply these controls to all cards associated with a specific account.

2. Card level

Most granular level of control. Per-card controls provide the highest level of customization for individual cards.

Evaluation Order: Account → Card

Approval Requirement: Both levels must approve for transaction to succeed.

API endpoints

For a full description of the APIs used to configure authorizationControls refer to the following API endpoints:

PUT /v1/cards/{cardId}/controls

GET /v1/cards/{cardId}/controls

Action types

Two action types define control behavior, ALLOW and DENY.

Action Type	Description
ALLOW (whitelist)	Evaluation: Value must be in the list Result if match: Continue to next control Result if no match: Decline transaction Empty list: Declines all transactions
DENY (blacklist)	Evaluation: Value must not be in the list Result if match: Decline transaction Result if no match: Continue to next control Empty list: Allows all transactions
No controls configured	Behavior: No restrictions applied at this level Result: Continue to next hierarchy level

ALLOW (whitelist)

Permits only the values listed in the control. The system declines any transaction with a value outside the list.

Use Case: Restrict card to specific merchants or categories only.

Example: Allow only fuel purchases

{ "type": "mcc", "action": "ALLOW", "list": ["5172", "5541", "5542", "5552"] }

DENY (blacklist)

Blocks only the values listed in the control. All other values are permitted.

Use Case: Block specific merchants, countries, or categories while allowing everything else.

Example: Block gambling merchants

{ "type": "mcc", "action": "DENY", "list": ["7995", "7800", "7801"] }

Control types

1. MCC (Merchant Category Code)

Restricts transactions based on merchant category codes.

Field name: mcc

Value format: 4-digit merchant category code (string)

Common use cases:

Restrict to fuel purchases only

Block gambling transactions

Limit to specific business categories

Example: Fuel purchase restriction:

{ "type": "mcc", "action": "ALLOW", "list": [ "5172", // Petroleum Products "5541", // Service Stations "5542", // Automated Fuel Dispensers "5552" // Electric Vehicle Charging ] }

Common MCC codes:

Code	Category
5172	Petroleum Products
5541	Service Stations (with/without ancillary services)
5542	Automated Fuel Dispensers
5552	Electric Vehicle Charging
5812	Restaurants
5411	Grocery Stores
7995	Betting/Casino Gambling

Full list:

MCCListing.xlsx

2. MID (Merchant ID)

Targets specific merchant locations using card acceptor IDs.

Field name: mid

Value format: Merchant identifier string

Common use cases:

Allow transactions at specific store locations only

Block specific problematic merchants

Restrict to corporate-approved vendor locations

Example: Specific merchant allowlist:

{ "type": "mid", "action": "ALLOW", "list": [ "MERCHANT_12345", "MERCHANT_67890" ] }

Example: Block specific merchant:

{ "type": "mid", "action": "DENY", "list": ["MERCHANT_99999"] }

3. Country

Restricts transactions based on merchant country location using ISO 3166-1 alpha-2 country codes.

Field name: country

Value format: 2-character ISO country code (string)

Common use cases:

Restrict to domestic transactions only

Block transactions from high-risk countries

Limit to specific geographic regions

Example: US only:

{ "type": "country", "action": "ALLOW", "list": ["US"] }

Example: Block specific countries:

{ "type": "country", "action": "DENY", "list": ["XX", "YY", "ZZ"] }

Common country codes:

Code	Country
US	United States
ES	Spain
GB	United Kingdom
CA	Canada
MX	Mexico
FR	France
DE	Germany

Country and currency codes:

CountryandCurrencyCodes.xlsx

4. Currency

Limits transaction currencies using ISO 4217 currency codes.

Field name: currency

Value format: 3-character ISO currency code (string)

Common use cases:

Restrict to home currency only

Block foreign currency transactions

Limit multi-currency exposure

Example: USD only:

{ "type": "currency", "action": "ALLOW", "list": ["USD"] }

Example: Block specific currencies:

{ "type": "currency", "action": "DENY", "list": ["EUR", "GBP"] }

Common currency codes:

Code	Currency
USD	US Dollar
EUR	Euro
GBP	Great Britain Pound
CAD	Canadian Dollar
MXN	Mexican Pesa
JPY	Japanese Yen

Country and currency codes:

CountryandCurrencyCodes.xlsx

Transaction evaluation flow

For authorization messages (0100, 0200) and 3DS authentication

---
config:
  layout: elk
---
flowchart TD
    A[Transaction Received<br/>0100/0200/3DS] --> B[Account Level Controls]
    B --> C{Pass}
    C -->|Yes| D[Card Level Controls]
    D --> E{Pass}
    E -->|Yes| F[Transaction Approved]
    E -->|No| G[Transaction Declined]
    C -->|No| G
    
    classDef start stroke:#38bdf8,fill:#f0f9ff
    classDef process stroke:#a78bfa,fill:#f5f3ff
    classDef decision stroke:#fb923c,fill:#fff7ed
    classDef approved stroke:#4ade80,fill:#f0fdf4
    classDef declined stroke:#f87171,fill:#fef2f2
    
    class A start
    class B,D process
    class C,E decision
    class F approved
    class G declined

Transaction Received (0100/0200/3DS) ↓ Account Level Controls ↓ (Pass) Card Level Controls ↓ (Pass) Transaction Approved

Decline at any level: If any level declines the transaction, evaluation stops immediately and the transaction is declined.

For clearing messages (0220)

---
config:
  layout: elk
---
flowchart TD
    A["Clearing Transaction Received (0220)"] --> B["Authorization Controls SKIPPED"]
    B --> C["Transaction Processed"]
    
    classDef processNode stroke:#818cf8,fill:#eef2ff
    classDef warningNode stroke:#fb923c,fill:#fff7ed
    classDef resultNode stroke:#4ade80,fill:#f0fdf4
    
    class A processNode
    class B warningNode
    class C resultNode

Clearing Transaction Received (0220) ↓ Authorization Controls SKIPPED ↓ Transaction Processed

Note: Clearing messages (0220) bypass authorization controls and are processed without restriction checks.

Use cases

Fleet card: Fuel only

Restrict card to fuel purchases at service stations:

{ "authorizationControls": [ { "type": "mcc", "action": "ALLOW", "list": ["5172", "5541", "5542", "5552"] } ] }

Corporate card: Domestic only

Restrict to US merchants using USD:

{ "authorizationControls": [ { "type": "country", "action": "ALLOW", "list": ["US"] }, { "type": "currency", "action": "ALLOW", "list": ["USD"] } ] }

Travel card: Block gambling

Allow all transactions except gambling:

{ "authorizationControls": [ { "type": "mcc", "action": "DENY", "list": ["7995", "7800", "7801", "7802"] } ] }

Vendor-specific card

Restrict to specific approved merchants:

{ "authorizationControls": [ { "type": "mid", "action": "ALLOW", "list": ["VENDOR_A_001", "VENDOR_B_002", "VENDOR_C_003"] } ] }

Best practices

1. Use appropriate action type

Use ALLOW for restrictive use cases (few permitted values)

Use DENY for permissive use cases (few blocked values)

2. Combine controls strategically

Layer multiple control types for complete restrictions

Example: Country + Currency + MCC for fleet cards

3. Hierarchy considerations

Set broad restrictions at Account level

Set specific restrictions at Card level

Avoid conflicting controls across hierarchy levels

4. Testing

Test all control combinations before production deployment

Verify both approval and decline scenarios

Test edge cases (empty lists, special characters)

5. Updates without reissuance

Update controls dynamically

Respond quickly to fraud patterns or policy changes

No need to reissue physical cards

Limitations & constraints

Control scope

Applies to:

Authorization requests (0100)

Financial authorization requests (0200)

3DS authentication

Does NOT apply to:

Clearing messages (0220)

Authorization controls restrict only the authorization phase, not the clearing/settlement phase

Control limits

Maximum controls per card: Check with Cross River P1

Maximum list items per control: Check with Cross River P1

Update frequency

Controls can be updated in real-time

Changes take effect immediately for new authorization requests

Data validation

Country codes must be valid ISO 3166-1 alpha-2 codes

Currency codes must be valid ISO 4217 codes

MCC codes must be 4-digit strings

MID format depends on merchant identifier standards