3DS in P1

3ds overview the 3d secure (3ds) authentication system provides an additional security layer for card not present transactions through strong customer authentication ( ) the system supports both rules based decisioning and multiple authentication methods to verify cardholder identity during online purchases supported networks visa (visa secure) mastercard (mastercard securecode®) authentication standard strong customer authentication (sca) compliant note both mastercard and visa support emv® 3d secure quick reference authentication types otp (one time password) is a temporary, single use, secure code the system sends it via sms to the customer's mobile phone or email for otp based authentication, otpsms or otpemail, you must provide customer contact information as follows mobile number retrieve this during card creation it must be the customer’s verified mobile phone number see the phonenumber attribute in the create new card docid\ ejccinvxb0omkja567gum api endpoint for the required format email address retrieve this during card creation it must be the customer’s verified email address see the emailaddress attribute in the create new card docid\ ejccinvxb0omkja567gum api endpoint for the required format type description validation required use case otpsms sms otp ❌ no (automatic) standard e commerce otpemail email otp ❌ no (automatic) standard e commerce outofbandother biometric (oob) ✅ yes (manual) mobile app with biometrics api endpoints summary endpoint method purpose /v1/3ds/{id} docid\ su5nvsufruwn28v1o7gm8 get get authentication details /v1/3ds/{id}/validate docid 0 mnw4crkx4t gprujlew post validate oob authentication (outofbandother only) /v1/simulate/3ds/authenticate docid\ vdmgalvyg 2gld buajxf post simulate 3ds authentication (testing) important notes authentication flow sequencediagram participant merchant participant p1 as cross river p1 participant partner participant cardholder note over merchant,cardholder 3ds authentication flow merchant >>p1 1 initiate 3ds authentication request p1 >>p1 2 evaluate authentication rules alt approve p1 >>merchant transaction approved else decline p1 xmerchant transaction declined else challenge required p1 >>partner 3 send authentication webhook\<br/>(based on authentication type) note over partner,cardholder partner configuration applied partner >>cardholder 4 partner uses webhook from cross river\<br/>to present authentication options cardholder >>cardholder 5 complete authentication cardholder >>partner 6 authentication result partner >>p1 7 return authentication response p1 >>merchant 8 final transaction result end merchant initiates 3ds authentication request cross river p1 evaluates rules (approve/decline/challenge) if challenge triggered, cross river p1 sends webhook to partner (based on authentication type) cardholder presented with configured authentication options authentication method executes based on partner configuration validation requirements outofbandother requires validation after biometric authentication completes, merchant must call post /v1/3ds/{id}/validate docid 0 mnw4crkx4t gprujlew to send result back to p1 otpsms and otpemail are automatic no validation endpoint call required vcas handles otp validation internally three domain model 3ds authentication involves three separate domains domain type description acquirer (merchant) merchant's e commerce platform initiates authentication request receives authentication results issuer (cross river p1) access control server (acs) processes authentication requests sends authentication challenges interoperability (vcas) vcas (visa card authentication service) routes messages between domains validates authentication results handles both visa and mastercard authentication flows generates tokens authentication methods method 1 out of band (oob) authentication type outofbandother flow sequencediagram participant merchant participant p1 as cross river p1 participant partner participant cardholder note over merchant,cardholder 3ds authentication flow challenge required merchant >>p1 1 initiate 3ds authentication request p1 >>p1 2 evaluate authentication rules note over p1 challenge triggered p1 >>partner 3 send authentication webhook\<br/>with authentication details note over partner partner uses webhook from cross river partner >>cardholder 4 push notification to\<br/>cardholder's mobile app cardholder >>cardholder 5 authenticate using biometrics\<br/>(fingerprint, face id, etc ) cardholder >>partner 6 authentication completed partner >>p1 7 post /v1/3ds/{id}/validate\<br/>send authentication result p1 >>p1 8 process and confirm authentication\<br/>(vcas validation) p1 >>merchant 9 return final authentication result\<br/>with cavv and eci note over merchant,p1 result authentication successful\<br/>transaction approved merchant initiates 3ds authentication request cross river p1 evaluates authentication rules if p1 triggers a challenge, p1 presents the cardholder with configured authentication options (based on partner configuration) p1 initiates authentication webhook to partner with authentication details partner receives webhook and pushes notification to cardholder's mobile app cardholder authenticates using biometrics (fingerprint, face id, etc ) in the app partner sends authentication result to cross river p1 via the validate outofbandother docid 0 mnw4crkx4t gprujlew api endpoint p1 confirms authentication with vcas (visa card authentication service) p1 returns final authentication result with cavv and to merchant timeout 10 minutes for cardholder response advantages frictionless user experience biometric authentication no manual code entry important this method requires calling the /validate endpoint to send the authentication result back to p1 method 2 one time passcode (otp) authentication sms otp type otpsms flow sequencediagram participant merchant participant p1 as cross river p1 participant partner participant cardholder note over merchant,cardholder 3ds authentication flow otp challenge merchant >>p1 1 initiate 3ds authentication request p1 >>p1 2 evaluate authentication rules note over p1 challenge triggered p1 >>partner 3 send authentication webhook\<br/>with otp details note over partner partner uses webhook from cross river partner >>cardholder 4 trigger otp delivery via sms\<br/>to cardholder's phone merchant >>cardholder 5 display otp entry screen cardholder >>merchant 6 enter otp on\<br/>merchant's validation screen merchant >>p1 7 submit otp for validation p1 >>p1 8 validate otp automatically\<br/>(vcas validation) p1 >>merchant 9 return authentication result\<br/>with cavv and eci note over merchant,p1 result authentication successful\<br/>transaction approved merchant initiates 3ds authentication request cross river p1 evaluates authentication rules if p1 triggers a challenge, cardholder is presented with configured authentication options (based on partner configuration) cross river p1 initiates authentication webhook to partner with otp details partner triggers otp delivery via sms to cardholder's phone merchant displays otp entry screen to cardholder cardholder enters otp on merchant's validation screen vcas validates otp automatically (no /validate endpoint call needed) cross river p1 returns authentication result with cavv and eci no validation endpoint required otp validation happens automatically within vcas important partner is responsible for sending the otp via sms based on details received in webhook email otp type otpemail flow sequencediagram participant merchant participant p1 as cross river p1 participant partner participant cardholder note over merchant,cardholder 3ds authentication flow email otp challenge merchant >>p1 1 initiate 3ds authentication request p1 >>p1 2 evaluate authentication rules note over p1 challenge triggered p1 >>partner 3 send authentication webhook\<br/>with otp details note over partner partner uses webhook from cross river partner >>cardholder 4 trigger otp delivery via email\<br/>to cardholder's email address merchant >>cardholder 5 display otp entry screen cardholder >>merchant 6 enter otp on\<br/>merchant's validation screen merchant >>p1 7 submit otp for validation p1 >>p1 8 validate otp automatically\<br/>(vcas validation) p1 >>merchant 9 return authentication result\<br/>with cavv and eci note over merchant,p1 result authentication successful\<br/>transaction approved merchant initiates 3ds authentication request cross river p1 evaluates authentication rules if challenge is triggered, cardholder is presented with configured authentication options (based on partner configuration) cross river p1 initiates authentication webhook to partner with otp details partner triggers otp delivery via email to cardholder's email address merchant displays otp entry screen to cardholder cardholder enters otp on merchant's validation screen vcas validates otp automatically (no /validate endpoint call needed) cross river p1 returns authentication result with cavv and eci no validation endpoint required otp validation happens automatically within vcas important partner is responsible for sending the otp via email based on details received in webhook otp validity 10 minutes per code retry logic resend logic maximum 3 attempts to enter correct otp reference code displayed to confirm expected otp authentication fails after 3 incorrect attempts important pan (primary account number) remains active after failed attempts initial otp sent automatically up to 2 additional resends permitted (3 total otps maximum) each resend generates a new otp code resend button becomes inactive after limit reached authentication rules system authentication rules provide a control layer for 3ds decisioning by allowing custom logic based on transaction attributes purpose add custom decisioning logic to 3ds authentication flow works with both cross river p1 decisioning and partner custom decisioning enforce stricter controls beyond base decisioning key limitation rules only enforce stricter controls or maintain existing declines they cannot override declines authentication decision flow step by step process sequencediagram participant merchant participant p1 as cross river p1 participant partner participant cardholder note over merchant,cardholder 3ds authentication flow merchant >>p1 1 initiate 3ds authentication request p1 >>p1 2 evaluate authentication rules alt approve p1 >>merchant transaction approved else decline p1 xmerchant transaction declined else challenge required p1 >>partner 3 send authentication webhook\<br/>(based on authentication type) note over partner partner uses webhook from cross river partner >>cardholder 4 present authentication options cardholder >>cardholder 5 complete authentication\<br/>(method based on partner config) cardholder >>partner 6 authentication result partner >>p1 7 return authentication response p1 >>merchant 8 final transaction result end 1 merchant initiates 3ds authentication request ↓ 2\ p1 receives authentication request ↓ 3\ all active rules evaluate simultaneously ↓ 4\ each rule checks transaction attributes ↓ 5\ matching rules execute actions (approve/decline/challenge) ↓ 6\ apply "most restrictive" decision logic ↓ 7\ if challenge triggered ├─ p1 initiates authentication webhook to partner ├─ cardholder presented with configured authentication options └─ authentication method (otpsms/otpemail/outofbandother) executes ↓ 8\ authentication result ├─ for otp methods vcas validates otp automatically └─ for oob methods partner calls /validate endpoint ↓ 9\ p1 confirms with vcas (visa card authentication service) ↓ 10\ final authentication response (with cavv and eci) ↓ 11\ response transmitted to merchant decision logic "most restrictive" principle the system applies the strictest outcome among all matching rules decision priority (most to least restrictive) decline transaction rejected immediately challenge additional verification required approve transaction proceeds (if no rules triggered) rules interaction flowchart td a\[transaction received] > b{evaluate all rules} b > c{any rule declines?} c >|yes| d\[❌ transaction declined] d > e\[cannot be overridden] c >|no| f{any rule triggers challenge?} f >|yes| g{another rule declines?} g >|yes| d g >|no| h\[⚠️ challenge flow continues] f >|no| i{any rules match?} i >|no| j\[🔄 default decisioning applies] i >|yes| k\[✅ process matched rules] style d fill #f44336,color #fff,stroke #b71c1c style e fill #f44336,color #fff,stroke #b71c1c style h fill #ff9800,color #fff,stroke #e65100 style j fill #2196f3,color #fff,stroke #0d47a1 style k fill #4caf50,color #fff,stroke #1b5e20 if any rule declines → transaction is declined (cannot be overridden) if any rule triggers challenge → challenge flow continues (unless another rule declines) if no rules match → default decisioning applies example scenario rules configured rule a challenge when risk score > 600 rule b decline when risk score > 800 transaction with risk score 850 rule a matches → action challenge rule b matches → action decline result transaction declined (decline is more restrictive than challenge) transaction with risk score 700 rule a matches → action challenge rule b does not match result transaction challenged (cardholder must authenticate) available actions authentication rules can execute two actions 1\ decline effect reject the transaction immediately use case high risk transactions, blocked merchants, suspicious patterns result transaction fails 3ds authentication 2\ challenge effect trigger additional verification flow (otp or oob) use case medium risk transactions requiring cardholder verification result cardholder must authenticate to proceed authentication result codes success states success cardholder authenticated successfully approved authentication approved by issuer failure states failure authentication failed (incorrect otp, biometric rejection) timeout cardholder did not respond within 10 minutes challenge required additional verification needed declined authentication declined by rules engine use cases use case 1 e commerce purchase low risk (frictionless) scenario customer purchases $50 item from known merchant flow sequencediagram participant merchant participant p1 as cross river merchant >>p1 1 initiate 3ds authentication request p1 >>p1 2 evaluate rules\<br/>risk score 450 (low) note over p1 3 no rules match\<br/>no challenge triggered p1 >>p1 4 approve authentication\<br/>without cardholder interaction p1 >>merchant 5 return authentication result\<br/>with cavv and eci note over merchant,p1 result frictionless approval\<br/>(no authentication challenge required) merchant initiates 3ds authentication request p1 evaluates rules risk score 450 (low) no rules match no challenge triggered p1 approves authentication without cardholder interaction p1 returns authentication result with cavv and eci result frictionless approval (no authentication challenge required) use case 2 e commerce purchase medium risk scenario customer purchases $500 item from new merchant flow sequencediagram participant merchant participant p1 as cross river participant partner participant cardholder participant vcas merchant >>p1 1 initiate 3ds authentication request p1 >>p1 2 evaluate rules\<br/>risk score 650 (medium) note over p1 3 rule matches \<br/>"challenge when risk score > 600" p1 >>partner 4 send authentication webhook\<br/>with otp details partner >>cardholder 5 present authentication options\<br/>(sms otp, email otp) cardholder >>partner 6 select sms otp partner >>cardholder 7 send otp via sms\<br/>to cardholder's phone cardholder >>merchant 8 enter correct otp\<br/>on merchant's screen merchant >>vcas 9 vcas validates otp automatically vcas >>p1 10 confirm authentication p1 >>merchant 11 return cavv and eci note over merchant,vcas result authentication successful\<br/>transaction approved merchant initiates 3ds authentication request cross river p1 evaluates rules risk score 650 (medium) rule matches "challenge when risk score > 600" cross river p1 initiates authentication webhook to partner with otp details cardholder presented with authentication options (sms otp, email otp) cardholder selects sms otp partner sends otp via sms to cardholder's phone (based on webhook data) cardholder enters correct otp on merchant's screen vcas validates otp automatically cross river p1 confirms with vcas and returns cavv result authentication successful, transaction approved use case 3 e commerce purchase high risk scenario customer purchases $1,000 item, cross border transaction flow sequencediagram participant merchant participant p1 as cross river merchant >>p1 1 initiate 3ds authentication request p1 >>p1 2 evaluate rules\<br/>risk score 850 (high) note over p1 3 rule matches \<br/>"decline when risk score > 800" p1 >>p1 4 apply "most restrictive"\<br/>decision logic p1 xmerchant 5 transaction declined note over merchant,p1 result transaction declined immediately\<br/>(no challenge triggered,\<br/>no authentication required) merchant initiates 3ds authentication request p1 evaluates rules risk score 850 (high) rule matches "decline when risk score > 800" apply "most restrictive" decision logic result transaction declined immediately (no challenge triggered, no authentication required) use case 4 oob authentication (outofbandother) scenario customer uses partner's mobile app with biometric support flow sequencediagram participant customer as customer\<br/>(cardholder) participant merchant participant p1 as cross river p1 participant partner note over customer,partner 3ds authentication flow oob biometric customer >>merchant 1 initiate $300 purchase\<br/>in mobile app merchant >>p1 2 initiate 3ds authentication request p1 >>p1 3 evaluate authentication rules\<br/>medium risk, challenge triggered p1 >>partner 4 send authentication webhook\<br/>with oob biometric details p1 >>merchant 5 return authenticationid\<br/>and transactionid note over partner partner uses webhook from cross river partner >>customer 6 send push notification\<br/>to mobile device customer >>customer 7 authenticate with face id\<br/>in partner's app customer >>partner 8 authentication completed partner >>p1 9 post /v1/3ds/{id}/validate\<br/>status "success" p1 >>p1 10 confirm authentication\<br/>(vcas validation) p1 >>merchant 11 return cavv and eci note over customer,p1 result frictionless authentication\<br/>transaction approved customer initiates $300 purchase in mobile app merchant initiates 3ds authentication request p1 evaluates rules medium risk, challenge triggered cardholder presented with authentication options (partner configured for oob biometric) p1 initiates authentication webhook to partner p1 returns authenticationid and transactionid to merchant partner receives webhook and sends push notification to customer's mobile device customer authenticates with face id in partner's app partner calls post /v1/3ds/{id}/validate docid 0 mnw4crkx4t gprujlew with status "success" to send result to p1 p1 confirms with vcas and returns cavv and eci result frictionless authentication, transaction approved