Remote Messaging

This section details the messaging requirements for connecting between ActiveAccess and an issuer's remote systems.

The ActiveAccess authentication system is responsible for managing the authentication of cardholders during American Express SafeKey, Diners Club International ProtectBuy, JCB J/Secure, Mastercard SecureCode / Identity Check and Verified by Visa / Visa Secure transactions. In order to support this requirement, the system must have access to appropriate information in order to uniquely determine the identity of the cardholder, whether a cardholder transaction requires authentication and what type of authentication is required. The determination of whether a cardholder is registered, whether a transaction requires authentication and what type of authentication is required for any particular transaction is currently performed by the ActiveAccess system. However, in order to delegate any of these duties to external issuer systems, some level of integration will be required.

In order to determine the correct 3-D Secure registration status, an issuer may be required to maintain the status of each of its cardholder's within the ActiveAccess system. Where this requires a significant investment in the development of maintenance procedures, an alternative may be to connect to determine the registration status of a cardholder by connecting with an issuer's systems. This procedure will remove the need to synchronise systems and ensure the maintenance of only one source of truth.

In a similar way, where an issuer is currently providing authentication services for its cardholders and wishes to re-use some of these services, it is possible to connect to the issuer's existing authentication system and leverage off their existing process for cardholder authentication. While the capability to perform second factor authentication is provided by ActiveAccess, this integration may be the issuer's preferred implementation model. This approach ensures a seamless user experience for the bank's customers across its banking channels.

The following sections explain the messaging requirements for connecting between ActiveAccess and an issuer's remote systems.

Message Format¶

SOAP, originally defined as Simple Object Access Protocol, is a protocol specification for exchanging structured information in the implementation of Web Services for messaging between ActiveAccess and an external system. It relies on Extensible Markup Language (XML) for its message format, and usually relies on other Application Layer protocols, most notably Hypertext Transfer Protocol (HTTP) and Simple Mail Transfer Protocol (SMTP), for message negotiation and transmission.

The Web Services Description Language is an XML-based language that is used for describing the functionality offered by a Web service. A WSDL description of a web service (also referred to as a WSDL file) provides a machine-readable description of how the service can be called, what parameters it expects, and what data structures it returns. It thus serves a roughly similar purpose as a method signature in a programming language.

Support for generating client-side and server-side API code based on WSDL is provided in most languages.

For WSDL of the services discussed in this document, refer to Remote System Integration WSDL.

Request¶

During a 3-D Secure transaction, the first stage of the messaging is to determine the registration status of a cardholder. By integrating with the issuer's system, ActiveAccess can determine the cardholder's registration status and therefore determine whether a transaction requires authentication.

Having determined a transaction requires authentication, the second stage in the process is to perform an authentication and by integrating with the issuer's system, ActiveAccess is capable of reusing the issuer's infrastructure to determine the authentication result. At the end of the process, the ActiveAccess system responds to the MPI with the authentication result in accordance with the 3-D Secure protocol.

The purpose of remote system integration is to:

• Determine the registration status of a cardholder

  and/or

• Initiate and verify the cardholder authentication.

The types of messages sent by ActiveAccess are:

• VerifyRegistration: determine the registration status of a cardholder

• InitAuthentication: initiate the cardholder authentication process

• VerifyAuthentication: verify the authentication result

• PreAuthentication: determine the action for exemption

• VerifyIdentity: verify the identification results

• Register: register the card

• ResetPassword: initiate the reset password process

• Ping: determine the status of the service.

CAAS Services¶

Table 1 - CAAS Services¶

Verify Registration¶

The Verify Registration request is used to determine the registration status of a cardholder, within the remote system. Where a cardholder cannot be uniquely identified, such as the case where primary and secondary exist, it may be necessary for the remote system to provide the registration status of all related cardholders. ActiveAccess will then determine the appropriate course of action based on the response and in line with the issuer's business requirements.

Once the cardholder has been uniquely identified and where authentication is required, ActiveAccess should commence the appropriate authentication process.

Verify Registration Request¶

Table 2 - VerifyRegReq¶

Table 3 - Card¶

Table 4 - Transaction¶

Verify Registration Response¶

A response message should be sent back for each request. The response message should provide the result of the request message with details of appropriate response information or errors as appropriate. Where one card is found in the remote system, registration details for that card should be included in the response. Where multiple cards are found, the registration details for each of the cards should be included in the response.

Table 5 - VerifyRegResp¶

Table 6 - CardInfo¶

CardInfo	Table 6
Attribute	Description	Usage	Sample Value
CardID	A unique cardholder identifier to be used as the value of the Card.ID attribute in subsequent request messages	Conditional. At least one of the Context_Blob or CardID is required. ActiveAccess echoes the Context_Blob into both Card.ID and Card. Context_Blob of the subsequent InitAuthReq and VerifyAuthReq if no CardID is returned by CAAS	2345678901
Card Name	Cardholder name to be used for specifying the exact cardholder when there are multiple cardholders for an identical card number (If an encryption KeyStore has been defined for the issuer or group of issuers, cardholder name must be encrypted using DESede/CBC/PKCS5Padding mode and message request IV by CAAS server, then HEX encoded and included in the message. ActiveAccess will decrypt this field using DESede/CBC/PKCS5Padding mode and the message request IV before using it in the process.)	Optional	John Smith
PAM	Personal Assurance Message (If an encryption KeyStore has been defined for the issuer or group of issuers, PAM must be encrypted using DESede/CBC/PKCS5Padding mode and the message request IV by the CAAS server, then HEX encoded and included in the message. ActiveAccess will decrypt this field using DESede/CBC/PKCS5Padding mode and the message request IV before using it in the process.)	Optional	This is my Bank
Context_Blob	A context detail that may be used in subsequent calls	Conditional. At least one of the Context_Blob or CardID is required. ActiveAccess echoes the Context_Blob into both Card.ID and Card. Context_Blob of the subsequent InitAuthReq and VerifyAuthReq if no CardID is returned by CAAS	12345678901234567890
Prisec	Primary or Secondary Cardholder 1 - Primary 2 - Secondary	Conditional	1
RegStatus	Registration Status: 1 - Enrolled (ActiveAccess enrolment status of pre-registered) 2 - Registered (ActiveAccess enrolment status of registered) 3 - Locked 4 - Unknown 5 - Error 6 - Temporarily Exempt 7 - Permanently Exempt 8 - Lost 9 - Stolen 10 -Restricted 11 - Card Number Error 12 - No Account 13 - Fraud 14 - Expired	Conditional. If SIS has data, RegStatus will not be considered.	2
AuthRequired	Authentication Required: 1 - Yes 2 - No	Conditional. If SIS has data, AuthRequired will not be considered.	1
AuthType	Authentication Type: 1 - Password 2 - SMS 3 - OTP device 4 - Virtual OTP device 5 - CAP/DPA 6 - Verify by Voice 7 - USS 8 - Q&A 9 - OLB 10 - CR 11 - BIO 12 - PKI 13 - TTP 14 - Email 15 - OOB	Conditional. If SIS has data, AuthType will not be considered. Note that this field cannot be used for two-factor authentication or being selected by user/cardholder during the authentication, as it only allows one supplementary authentication type to be set for the authentication page.	1
RegToken	The variable part of a message to be displayed to user/cardholder in the registration page. It reflects the number of times the cardholder opts-out during the registration process.	Optional. e.g. CAAS server wants to limit the number of times that a user/cardholder can opt-out from the registration process.	3 (e.g. of the message in the registration page: You have opted-out of the registration process 3 times)
AuthTypeSup	Supplementary authentication types that user/cardholder's account supports: 1 - Password 2 - SMS 3 - OTP device 4 - Virtual OTP device 5 - CAP/DPA 6 - Verify by Voice (OOB Biometrics) 7 - USS 8 - Q&A 9 - OLB (OOB Login) 10 - CR 11 - BIO (OOB Biometrics) 12 - PKI 13 - TTP (OOB Other) 14 - Email 15 - OOB (OOB Other) 16 - DA (Decoupled Authenticator)	Optional. Note that only this field can be used for two-factor authentication or being selected by user/cardholder during the authentication, as it allows more than one supplementary authentication type to be set for the authentication page.	2, 3
SIS	Refer to Table 7 - SIS	Conditional. If exists, it takes precedence over RegStatus, AuthRequired and AuthType
ProofAttempt	The availability of the Opt-Out option, as opposed to Cancel, for the cardholder. True - request identification parameters False - Proof of Attempt disabled,Opt - Out option not available Note - it is recommended to set this through ACS via MIA > Issuers > Settings instead of this parameter	Optional	false
ActivationDuringShopping	The ability to authenticate an enrolled cardholder by ID details for verification. True - request identification parameters False - registration pages are processed as without activation Note - it is recommended to set this through ACS via MIA > Issuers > Settings instead of this parameter	Optional	true
LanCode	The code of the preferred language saved for the cardholder. The value can be a digit between 0 to 4.	Optional	0 - default language 1 - 2nd language 2 - 3rd language 3 - 4th language 4 - 5th language
IdentityData	Attributes of Data: Name (required) - the name of the AuthData parameter to be used for data collection on the page AuthType (conditional) - empty value Format (optional) - the regular expression for verifying the value collected from the page Mask (optional) - True - input on the page will be masked False - input on the page will be in plaintext Confirm (optional) - True - an additional input field will be added to the page for confirmation False - no confirmation input field will be displayed on the page Refer to Table 8 - Data	Conditional. Required if ActivationDuringShopping is TRUE and RegStatus is 1. If RegStatus is not 1 and IdentityData has been returned, it will be used in the ResetPassword process.	identityData=[data={[value=<(null)>, error=<(null)>, name=pin, authType=<(null)>, format=\w+, mask=true, confirm=<(null)>]
twoFA	The availability of 2FA authentication option. 2FA authentication is a combination of: Knowledge: something only the user knows (e.g. password, pin, ID number) + Ownership: something only the user possesses (e.g. mobile device, token, smart card) or Inherence: something only the user is (e.g. fingerprint, face or voice recognition) The first factor must be knowledge; the second factor can be ownership or inherence.	Optional	true - enable two-factor authentication false - disable two factor authentication

Table 7 - SIS¶

Table 8 - Data¶

Table 9 - Error¶

Pre Authentication¶

The ability to integrate ActiveAccess with an external risk engine has been established in the Pre Authentication process in which header data including cookie and HTTP header data in addition to potential extension information will be sent to CAAS for it to determine if authentication is required or exempt.

Pre Authentication¶

Table 10 - PreAuthReq¶

Table 11 - HeaderParams¶

ExtensionParams

The elements differ by different message extensions which are defined in messages. For instance, American Express extension params differ from Mastercard extension params.

Table 12 - AdditionalParams¶

Pre Authentication Response¶

A response message should be sent back by the remote authentication system to decide on the continuation of the authentication process.

Table 13 - PreAuthResp¶

Initiate Authentication¶

The Initiate Authentication step is optional and depends upon the type of authentication device being used. Once the registration status of the cardholder has been determined, ActiveAccess may initiate the authentication process by sending a request to the issuer's remote system. This step may be used for the first, and subsequent, generate challenge requests.

This step will commonly be used to initiate out of band authentication such as SMS, Question and Answer, Challenge and Response and Email.

Initiate Authentication Request¶

Table 14 - InitAuthReq¶

InitAuthReq	Table 14
Attribute	Description	Usage	Sample Value
Card	Where a value for Card.ID or Context_Blob was returned in the VerifyReg response, this value should be assigned to the Card.ID attribute. Otherwise, attributes of the Card may include Number, Name and Type as described in the VerifyReg request. Refer to Table 3 - Card.	Required. Either ID or Number and Type should be presented	card=[id=4564260131003313, number=4564-26XX-XXXX-3313, type=VbV, cardName=< null >, Context_Blob=595],
Transaction	Where messaging commences after the ActiveAccess system receives the PAReq, additional transaction, cardholder and merchant information is available. This information may be additionally sent to the issuer system for analysis and fraud detection purposes. Where required, the following data fields may be sent to the issuer's system in any of the request messages. Refer to Table 4 - Transaction.	Optional	transaction=[xid=MDAwMDAwMDAwM, purchaseAmount=12365, purchaseCurrency=840, purchaseDate=[orig_eon=< null >, orig_year=2016, orig_month=11, orig_day=3, orig_hour=10, orig_minute=23, orig_second=19, orig_fracSeconds=0.000, orig_timezone=210, eon=< null >, year=2016, month=11, day=3, timezone=210, hour=10, minute=23, second=19, fractionalSecond=0.000],
SMS	Template - The SMS message to be sent to the cardholder populated with Transaction.MerchantName, Transaction.PurchaseAmount and Transaction.PurchaseCurrency in the format that is required by SMS Gateway to send to customer mobile. template = "Sample message here. Your OTP is {0}". Notes: 1. The {0} is the placeholder where CAAS injects the actual 6-digit OTP. 2. {0} can be anywhere in the template – the above is just an example. 3. The length of the text can be up to 160 chars (note, the {0} placeholder will expand from 4 characters to 6 characters, so free text is effectively 154 characters.)	Conditional, where the authentication channel is SMS. Up to 154 characters.	Your OTP is :{0} \r\n merName: Test Merchant, purchaseAmount: 123.65
Email	Contains Content, Subject and the Content-Type of the email. Content (Required) - The content of the email to be sent to the cardholder, which can be populated with Transaction.MerchantName, Transaction.PurchaseAmount, Transaction.PurchaseCurrency, and any other information in the format that is configured by the bank to send to the customer's email address. Notes: 1. The {0} is the placeholder where CAAS injects the actual 6-digit OTP. 2. {0} can be anywhere in the template – the above is just an example. 3. The length of the text can be up to 160 chars (note, the {0} placeholder will expand from 4 characters to 6 characters, so free text is effectively 154 characters.) Subject (Required) - The subject of the email to be sent to the cardholder, which can be populated with Issuer Name, to send to the customer's email address. Content-Type (Required) - The content type of the email to be sent to the cardholder. This can be TEXT/PLAIN or TEXT/HTML.	Conditional. Content up to 1024 characters. Subject up to 998 characters. Content-Type up to 25 characters.
OobInfo	Template - The message to be sent to the OOB application populated with Transaction. MerchantName, Transaction.PurchaseAmount and Transaction.PurchaseCurrency in the format that is required by OOB adapter to send to OOB. template = ": "$ThreeDSServerTransID", "purchaseAmount": "$PurchaseAmount", "purchaseCurrency": "$PurchaseCurrency", "purchaseExponent": "$PurchaseExponent", "purchaseDate":"$PurchaseDate", "messageCategory": "$MessageCategory", "deviceChannel": "$DeviceChannel", "acctNumber": "$AcctNumber", "merchantName": "$MerchantName", "cardHolderInfo": { "cardholderName": "$CardholderName", "email": "$Email", "homePhone": { "cc": "$HomePhone_cc", "subscriber": "$HomePhone_subscriber" }, "mobilePhone": { "cc": "$MobilePhone_cc", "subscriber": "$MobilePhone_subscriber" }, "shipAddrCity": "$ShipAddrCity", "shipAddrCountry": "$ShipAddrCountry", "shipAddrLine1": "$ShipAddrLine1", "shipAddrLine2": "$ShipAddrLine2", "shipAddrLine3": "$ShipAddrLine3", "shipAddrPostCode": "$ShipAddrPostCode", "shipAddrState": "$ShipAddrState", "workPhone": { "cc": "$WorkPhone_cc", "subscriber": "$WorkPhone_subscriber", } } }	Conditional. Where the authentication channel is any of OOB 6 - Verify by Voice 7 - USS 9 - OLB 11 - BIO 13 - TTP 15 - OOB. Up to 4000 characters.	{ "threeDSServerTransID": "$ThreeDSServerTransID", "purchaseAmount": "123", "purchaseCurrency": "840", "purchaseExponent": "2", "purchaseDate":"20201216041928", "messageCategory": "01", "deviceChannel": "01", "acctNumber": "4123XXXXXXXX45", "merchantName": "Tet Merchant", "cardHolderInfo": { "cardholderName": "John", "email": "email@example.com", "homePhone": { "cc": "1", "subscriber": "530123112345" }, "mobilePhone": { "cc": "55", "subscriber": "23451443212" }, "shipAddrCity": "$ShipAddrCity", "shipAddrCountry": "$ShipAddrCountry", "shipAddrLine1": "$ShipAddrLine1", "shipAddrLine2": "$ShipAddrLine2", "shipAddrLine3": "$ShipAddrLine3", "shipAddrPostCode": "$ShipAddrPostCode", "shipAddrState": "$ShipAddrState", "workPhone": { "cc": "$WorkPhone_cc", "subscriber": "$WorkPhone_subscriber" } } }
callBack	URL - The URL that will receive the notification for the completion of OOB and Decoupled authentication.	Conditional. Where the authentication channel is any of OOB 6 - Verify by Voice 7 - USS 9 - OLB 11 - BIO 13 - TTP 15 - OOB 16 - DA	http://acs.local:8080/acs/notifier/c26fe6e0-e8c6-45da-a488-09b9b50b82a6
AuthType	Authentication Type that cardholder requests to (re)initiate the one-time passcode for authentication: 2 - SMS 6 - Verify by Voice 7 - USS 10 - CR 11 - BIO 14 - Email 15 - OOB	Conditional. Up to 2 characters.	2
IV	If an encryption KeyStore has been defined for the issuer or group of issuers, critical card data must be encrypted by ActiveAccess using DESede/CBC/PKCS5Padding mode. The CBC encryption mode requires an Initialisation Vector (IV), which includes 8 random bytes, as an input parameter for encryption and decryption. The IV should be sent to the CAAS server to be used at decryption time. To do this, the IV which was used for encryption, must be encrypted in DESede/ECB/PKCS5Padding mode, using the same key, then HEX encoded and set as IV in the request.	Optional. If present, it means that ActiveAccess has generated an IV parameter and critical card information has been encrypted using the CBC mode and the generated IV, otherwise ECB or plain mode has been used instead. 8 or 16 characters in length.	8F51F71064DB2B65

Initiate Authentication Response¶

A response message should be sent back by the remote authentication system to indicate the status of sending an SMS or Email, or otherwise return AuthData for the authentication initiation.

Table 15 - InitAuthResp¶

Verify Authentication¶

Where the remote system determines that authentication is required and after an authentication has been initiated, the cardholder should be presented with an appropriate page. In many circumstances, this page will request the cardholder to enter their authentication credentials, such as a password or a one-time password. However, in some circumstances, the screen presented may ask the cardholder to press a button after having completed their out of band authentication.

When a cardholder enters their password, ActiveAccess will format the details of the authentication request and send it to the remote system for verification. The response provided will determine the authentication status of the transaction, with ActiveAccess formatting the 3-D Secure payer authentication response message to be returned to the merchant's MPI.

Verify Authentication Request¶

Table 16 - VerifyAuthReq¶

Verify Authentication Response¶

Table 17 - VerifyAuth¶

A response message should be sent back by the remote authentication system to indicate the success, or otherwise of the authentication verification.

Verify Identity¶

Verify Identity data is used in ADS or the Forgot password process to primarily verify the identity of the cardholder before changing/setting authentication data.

A request message should be sent to CAAS with the user identity data and to have CAAS verify the data.

Verify Identity Request¶

Table 18 – VerifyIdentityReq¶

Verify Identity Response¶

A response message should be sent back to ActiveAccess to inform whether user identity has been verified or not and to return the reason in case of identity failure. In addition, it returns failed identity items to be highlighted in the page. In the case of a successful response, it returns AuthData to be asked for a subsequent authentication process.

Table 19 - VerifyIdentityResp¶

Register¶

A request message should be sent to CAAS to set Authentication data for subsequent authentication.

Register Request¶

Table 20 – RegisterReq¶

Register Response¶

Table 21 – RegisterResp¶

Reset Password¶

Reset Password Request¶

A request message should be sent to CAAS for ResetPasswordData and have data set for further use.

Table 22 - ResetPasswordReq¶

Reset Password Response¶

A response message should be sent back to ActiveAccess to indicate the result of the reset password process in CAAS.

Table 23 – ResetPasswordResp¶

Ping¶

The ping request is used to determine the responsiveness and availability of the server. Simply send a ping request to the server to check if the service is up and operational or not.

Ping Request¶

Ping has no request parameter.

Ping Response¶

Ping has no response. Successful return of the operation invocation without any exception means the service is up and running.

Messaging Requirements¶

Securing Message Channel¶

Communication security must be ensured by using SSL with server and client authentication.

Critical Card Data Encryption and Decryption¶

The key, which is used for encrypting/decrypting the critical card data, must be a 112 or 168 bit DESede key. A KeyStore with the following details should be prepared for the encryption key that is to be uploaded, through MIA, for the specified issuer or group of issuers:

KeyStore type/format: JCEKS

KeyStore provider: SunJCE

Key algorithm: DESede

Key size: 112 or 168 bit

Key name: can be any

No of keys in the KeyStore: Only one key must be populated in the KeyStore

Such KeyStores can be easily created through the Java keytool utility using the following command:

keytool -genseckey -alias enckey168 -keypass 123456 -keyalg DESede -keysize 168 -keystore enc-key.JKS -storepass 123456 -storetype JCEKS

Calling Convention¶

Requests will be sent using SOAP on HTTPS.

Remote System Integration WSDL¶