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 docid\ r cxcl0l2uoywkuujpaj1 get /v1/cards/{cardid}/controls docid\ at16wgxzgov5cqfufnptp 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 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 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 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