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, UnionPay International 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 and optionally determine the action of exemption
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.
Note
Messages sent between ActiveAccess and the remote system for this purpose do not carry any session information and therefore are considered to be stateless
CAAS Services¶
Table 1 - CAAS Services¶
| CAAS Service | Table 1 | |
|---|---|---|
| Operation | Description | Usage |
| VerifyRegistration | Used to verify the registration status of a cardholder and optionally determine the action of exemption. | Required for a verify registration request |
| InitAuthentication | Used to initiate the authentication process for out-of-band authentication. | Required for an initiate authentication request |
| VerifyAuthentication | Used to determine the authentication result. | Required for a verify authentication request |
| PreAuthentication | Used to determine the action for exemption | Optional |
| VerifyIdentity | Used to verify the identification results | Required for a reset password request and register request |
| Register | Used to register the card | Required for a register request |
| ResetPassword | Used to initiate the reset password process | Required for a reset password request |
| Ping | Used to determine if service is up and running | Optional |
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.
Optionally, the ability to integrate ActiveAccess with an external risk engine has been established in which header data including browser info and device data in addition to potential extension information will be sent to CAAS to determine if authentication is exempt or not.
Verify Registration Request¶
Table 2 - VerifyRegReq¶
| VerifyRegReq | Table 2 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Card | Refer to Table 3 - Card | Required | |
| Transaction | Additional transaction information may include transaction; cardholder and merchant information such as MerchantID and AcqBIN. Refer to Table 4 - Transaction. | Optional | |
| IV | If an encryption KeyStore has been defined for the issuer or group of issuers, critical card data must be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode. The CBC encryption mode requires an Initialisation Vector (IV), which includes 16 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 AES/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. 16 bytes when AES, 8 bytes when DESede. | 8F51F71064DB2B65 |
| HeaderParams | Attributes of Param: Value (required) Key (required) Cookie (optional) | Optional | headerParams=[param={[value=value1, key=key1, cookie=true],...}], |
| ExtensionParams | Attributes of Param: Value (required) Key (required). | Optional | extensionParams=[param={[value=value1, key=key1, cookie=true],...}], |
| AdditionalParams | Attributes of Param: Value (required) Key (required). | Optional | additionalParams=[param={[value=value1, key=key1, cookie=true],...}], |
Table 3 - Card¶
| Card | Table 3 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| ID | A unique cardholder identifier | Optional. Up to 2000 characters. | 2345678901 |
| Number | Card number (If an encryption KeyStore has been defined for the issuer or group of issuers, card number will be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode and IV, then HEX encoded and included in the message. Therefore, the CAAS server will need to decrypt this field using AES/CBC/PKCS5Padding mode and the request's IV before using it in the process) | Optional. Up to 64 characters. | 5012345678901234 |
| CardName | Name on card (If an encryption KeyStore has been defined for the issuer or group of issuers, name on card will be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode and IV, then HEX encoded and included in the message. Therefore, the CAAS server will need to decrypt this field using AES/CBC/PKCS5Padding mode and the request's IV before using it in the process) | Optional. Up to 512 characters. | JOE CITIZEN |
| Type | Card type | Optional. Up to 3 characters. Valid types: VbV – Visa, UPI - UnionPay International, SPA – Mastercard, JCB – JCB, SK – American Express, DC - Diners Club International. | SPA |
| Context_Blob | A context detail that may be used in subsequent calls | Optional. This field can be ignored by CAAS in VerifyRegReq as ActiveAccess does not use it and only echoes it in InitAuthReq and VerifyAuthReq if it has been set in VerifyRegResp.CardInfo. Context_Blob by CAAS. Length not defined. | 12345678901235467890 |
| LanCode | A code between 0 to 4 that presents the cardholder's preferred language | Optional. 1 character in length. | 0 |
Table 4 - Transaction¶
| Transaction | Table 4 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| XID | The transaction ID as defined in the PAReq message | Optional. Up to 28 characters. | MDAwMDAwMDAwMDAwMDAwMDAxMDA= |
| PurchaseDate | The transaction purchase date and time as defined in the PAReq message | Optional. Up to 17 characters in XMLGregorianCalendar format. | 20091023 06:11:00 |
| PurchaseAmount | The transaction purchase amount as defined in the PAReq message | Optional. Up to 12 characters in decimal format. | 12345 |
| PurchaseCurrency | The 3-digit transaction currency value as defined in the PAReq message. Refer to Country and Currency Codes | Optional. Up to 3 digits. | 840 |
| PurchaseExponent | The minor units of currency specified in ISO 4217 | Optional. 1 character in length. | 2 |
| PurchaseDesc | A description of the purchase as defined in the PAReq message | Optional. Up to 125 characters. | Blue Shirt |
| MerchantID | The merchant ID as defined in the PAReq message | Optional. Up to 24 characters. | 123456789012345 |
| AcqBIN | The acquirer BIN as defined in the PAReq message | Optional. Up to 11 characters. | 412345 |
| MerchantName | The merchant name as defined in the PAReq message | Optional. Up to 25 characters. | Test Merchant |
| MerchantURL | The fully qualified merchant URL as defined in the PAReq message | Optional. Up to 2048 characters. | http://www.testmerchant.com.au/ |
| MerchantCountry | The 3-digit merchant country code as defined in the PAReq message. Refer to Country and Currency Codes | Optional. 3 digits in length. | 036 |
| CardExpiry | The 4-digit expiry date of the card as defined in the PAReq message, e.g. YYMM | Optional. 4 or 6 digits in length. | 1012 |
| CardholderIP | The IP address of the cardholder browser where available | Optional. 15 or 45 characters in IPv4 or IPv6 format. | 192.168.0.157 |
| CVD | Card Verification Data code is the 3 or 4-digit code found on the back of a payment card | Optional. 3 or 4 digits in length. | 0320 |
| issuerName | Name of Issuer/Bank to be displayed on OOB page | Optional. Up to 64 characters. | Any Bank |
| theeDSProtocolVersion | Version of 3DS protocol in x.x.x format | Optional. 5 characters in length. | 2.1.0 |
| acsTransId | Universally Unique transaction identifier assigned by the ACS to identify a single transaction. | Optional. 36 alphanumeric characters in length. | ee5de3bc-a1a3-4648-9c5f-350422146fe1 |
| threeDSTransId | Universally Unique transaction identifier assigned by the 3DS Server to identify a single transaction. | Optional. 36 alphanumeric characters in length. | we5de3bc-a213-46lk-9cas-35456ed46fe1 |
| dsTransId | Universally Unique transaction identifier assigned by the Directory Server to identify a single transaction. | Optional. 36 alphanumeric characters in length. | tg6de3bc-a213-4r3k-9c12-35456ed4edr43 |
| threeDSRequestorID | DS assigned 3DS Requestor identifier | Optional. Variable length with maximum 35 characters in length. | tg6de3bc-a213-4r3k-9c12-35456ed4edr43 |
| threeDSRequestorName | DS assigned 3DS Requestor name | Optional. Variable length with maximum 40 characters in length. | Test Requestor |
| threeDSRequestorURL | URL of 3DS Requestor website or customer care site | Optional. Variable length with maximum 2048 characters in length. | http://server.domainname.com |
| threeDSServerRefNumber | Unique identifier assigned by the EMVCo | Optional. Variable length with maximum 32 characters in length. | TestTDSRef123 |
| threeDSServerOperatorID | DS assigned 3DS Server identifier | Optional. Variable length with maximum 32 characters in length. | TestDsOperatorId12 |
| threeDSServerURL | URL of the 3DS Server to which the DS will send the RReq | Optional. Variable length with maximum 2048 characters in length. | https://server.adomainname.net |
| deviceChannel | Indicates the type of channel interface being used to initiate the transaction | Optional. 2 characters in length. Acceptable values are 01,02,03 | 01 |
| dsReferenceNumber | Unique identifier assigned by the EMVCo | Optional. Variable length with maximum 32 characters in length. | TestDsRef123 |
| payTokenInd | A value of True indicates that the transaction was de-tokenised prior to being received by the ACS. | Optional. 4 characters in length. Acceptable value: true | true |
| purchaseInstalData | Indicates the maximum number of authorisations permitted for instalment payments | Optional. Variable length with maximum 3 characters in length. Acceptable values: number greater than 1 | 3 |
| mcc | DS-specific code describing the Merchant’s type of business, product or service | Optional. 4 characters in length. | 3210 |
| messageCategory | Identifies the category of the message for a specific use case. | Optional. 2 characters in length. Acceptable values: 01, 02 | 01 |
| recurringExpiry | Date after which no further authorisations shall be performed. | Optional. 8 characters in length. Format YYYYMMDD | 20201010 |
| recurringFrequency | Indicates the minimum number of days between authorisations | Optional. Variable length with maximum 4 characters in length. | 3 |
| sdkReferenceNumber | Unique identifier assigned by the EMVCo | Optional. Variable length with maximum 32 characters in length. | TestSDKRef123 |
| transType | Identifies the type of transaction being authenticated. | Optional. 2 characters in length. Acceptable values: 01, 03, 10, 11, 28 | 01 |
| acctType | Indicates the type of account. For example, for a multi-account card product. | Optional. 2 characters in length. Acceptable values: 01, 02, 03 | 01 |
| threeDSRequestorAppURL | 3DS Requestor App declaring their URL within the CReq message so that the Authentication app can call the 3DS Requestor App after OOB authentication has occurred. Each transaction would require a unique Transaction ID by using the SDK Transaction ID. | Optional. Variable length with maximum 256 characters in length. Fully qualified URL. | http://threeds.app.url/ |
| threeDSRequestorAuthenticationInd | Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handling an authentication request. | Optional. 2 characters in length. 01-Payment transaction 02-Recurring transaction 03-Instalment transaction 04-Add card 05-Maintain card 06-Cardholder verification as part of EMV token ID & V | 01 |
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¶
| VerifyRegResp | Table 5 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| CardInfo | If the request was successful and at least one card record was found, card related data may include primary/secondary cardholder indicator, registration status, authentication required indicator, authentication type, a card identifier and a SIS data. Refer to Table 6 - CardInfo. | Conditional. If response code is not presented, at least one CardInfo should exist. | |
| Code | Response code: 0 - request was successful but no card records were found 1 - request has been successfully processed but there are warnings (NOTE- Please see below ) 2 - error in processing the request. | Required. Included where no card records are found or an error occurred. | 0 |
| ErrorMessage | A descriptive message that identifies the category of the error | Conditional. Included where a Code is returned in the response. | No card(s) found |
| ErrorDetail | A more detailed description of the error | Conditional. Included where a Code is returned in the response. | No card(s) matching the request were found |
| RiskAction | 0 - The authentication will be exempted. The authentication will not be displayed and the appropriate response will be returned. 1 - The transaction is not exempt. The authentication page will be displayed. 2 - There was an error but ActiveAccess will display the authentication page and let the authentication continue. ActiveAccess will not cancel the authentication. 3 - The transaction is deemed to be high risk, ActiveAccess will decline the transaction.  4 - The transaction will be exempted with review. The authentication page will not be displayed and the appropriate response will be returned. | Optional | 0 |
| RiskAuthType | The comma separated list of decided authTypes by risk engine integration: 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 16- DECOUPLED AUTH | Optional | 2, 14 |
| RiskMessage | A descriptive message that indicates the category of the error | Optional | Error while evaluating risk of transaction |
Note
ActiveAccess treats warnings (code=1) as errors unless the exact ErrorMessage is introduced in AA_HOME/caaswarning.properties with a code less than 2000. Changing this file requires a restart to take effect.
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 AES/CBC/PKCS5Padding mode and message request IV by CAAS server, then HEX encoded and included in the message. ActiveAccess will decrypt this field using AES/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 AES/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 AES/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 16 - Decoupled Authenticator(DA) | 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¶
| SIS | Table 7 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| AccountState | Account State: 1 - Operational 2 - Unknown | Required | 1 |
| OperationalState | Operational State: 1 - Operational 2 - Locked Blank -Not Specified | Required | 1 |
| SecurityDeviceType | Security Device Type: 1 - Hard Token 2 - Soft Token 3 - SMS 4 - PIQ 5 - Email Blank - Not specified | Required | 3 |
| IsExempt | Authentication Exemption: True False Blank - Not specified | Required | 2 |
| IsPermanent | Permanent Authentication Exemption: True False Blank - Not specified | Required | 2 |
Table 8 - Data¶
| Data | Table 8 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Value | The value of Data | Optional | 123456 |
| Error | Refer to Table 9 - Error | Optional |
Table 9 - Error¶
| Error | Table 9 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Code | Response code: 0 - the request was successful 1 - there was an error and ActiveAccess should send the request again 2 - there was an error and ActiveAccess should cancel the authentication | Required | 2 |
| Message | A descriptive message that identifies the category of the error | Optional | No card(s) found |
| Detail | A more detailed description of the error | Optional | No card(s) matching the request were found |
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¶
| PreAuthReq | Table 10 | ||
|---|---|---|---|
| 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=MDAwMDAwMDAwMDAwMDAwMDAxMDA=, purchaseAmount=12365, purchaseCurrency=840, purchaseDate=[eon=<(null)>, year=2016, month=11, day=3, timezone=210, hour=10, minute=16, second=46, fractionalSecond=0.000], |
| IV | If an encryption KeyStore has been defined for the issuer or group of issuers, critical card data must be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode. The CBC encryption mode requires an Initialisation Vector (IV), which includes 16 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 AES/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. | 8F51F71064DB2B65 |
| HeaderParams | Attributes of Param: Value (required) Key (required) Cookie (optional) | Optional | headerParams=[param={[value=value1, key=key1, cookie=true],...}], |
| ExtensionParams | Attributes of Param: Value (required) Key (required) | Optional | extensionParams =[param={[value=value1, key=key1],...}], |
| AdditionalParams | Attributes of Param: Value (required) Key (required) | Optional | additionalParams =[param={[value=50, key=giftCardAmount],...}], |
Table 11 - HeaderParams¶
| HeaderParams | Table 11 | ||
|---|---|---|---|
| Attribute | Description | Sample Value | |
| User-Agent | Either value of HTTP request header parameter or browserUserAgent element of AReq; Exact content of the HTTP user-agent header | Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0 | |
| Accept | Either value of HTTP request header parameter or browserAcceptHeader element of AReq; Exact content of the HTTP accept headers | text/html | |
| Accept-Language | Either the value of HTTP request header parameter or browserLanguage element of AReq | en-US | |
| proxy-ip | Either the value of HTTP request header parameter or browserIp element of AReq; IP address of the browser as returned by the HTTP headers | 192.168.1.138 | |
| browserJavaEnabled | browserJavaEnabled element of AReq; Boolean that represents the ability of the cardholder browser to execute Java. Acceptable values: true, false | true | |
| browserTZ | browserTZ element of AReq; Time difference between UTC time and the Cardholder browser local time, in minutes | -- | |
| browserLanguage | browserLanguage element of AReq; Value representing the browser language | en-US | |
| deviceInfo | deviceInfo element of AReq; Device information gathered by the 3DS SDK from a Consumer Device | -- | |
| sdkAppID | sdkAppID element of AReq; Universally unique ID created upon all installations and updates of the 3DS Requestor App on a Consumer Device. | -- | |
| browserColorDepth | browserColorDepthelement of AReq; Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Acceptable values: 1, 4, 8, 15, 16, 24, 32, 48 | 15 | |
| browserScreenHeight | browserScreenHeight of AReq; Total height of the Cardholder’s screen in pixels, 1 - 6 characters in length | 390 | |
| browserScreenWidth | browserScreenWidth of AReq; Total width of the cardholder’s screen in pixels, 1 - 6 characters in length | 400 |
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¶
| AdditionalParams | Table 12 | ||
|---|---|---|---|
| Attribute | Description | Sample Value | |
| shipAddrState | shipAddrState element of AReq; The state or province of the shipping address associated with the card being used for this purchase, maximum 3 characters in length. Value accepted: Should be the country subdivision code defined in ISO 3166-2 | -- | |
| shipAddrCity | shipAddrCity element of AReq; City portion of the shipping address requested by the Cardholder. Maximum 50 characters in length | -- | |
| shipAddrCountry | shipAddrCountry element of AReq; Country of the shipping address requested by the Cardholder. 3 characters on length. Value accepted: ISO 3166-1 three-digit country code | -- | |
| shipAddrLine1 | shipAddrLine1 element of AReq; First line of the street address or equivalent local portion of the shipping address requested by the Cardholder. Maximum 50 characters in length | -- | |
| shipAddrLine2 | shipAddrLine2 element of AReq; The second line of the street address or equivalent local portion of the shipping address requested by the Cardholder. Maximum 50 characters in length | -- | |
| shipAddrLine3 | shipAddrLine3 element of AReq; The third line of the street address or equivalent local portion of the shipping address requested by the Cardholder. Maximum 50 characters on length | -- | |
| shipAddrPostCode | shipAddrPostCode element of AReq; The ZIP or other postal code of the shipping address requested by the Cardholder. Maximum 16 characters in length | -- | |
| billAddrState | billAddrState element of AReq; The state or province of the Cardholder billing address associated with the card used for this purchase. Maximum 3 characters in length. Value accepted: Should be the country subdivision code defined in ISO 3166-2 | -- | |
| billAddrCity | billAddrCity element of AReq; The city of the Cardholder billing address associated with the card used for this purchase. Maximum 50 characters. | -- | |
| billAddrCountry | billAddrCountry element of AReq; The country of the Cardholder billing address associated with the card used for this purchase. 3 characters in length. Value accepted: Shall be the ISO 3166-1 numeric three-digit country code | -- | |
| billAddrLine1 | billAddrLine1 element of AReq; First line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. Maximum 50 characters in length | -- | |
| billAddrLine2 | billAddrLine2 element of AReq; Second line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. Maximum 50 characters | -- | |
| billAddrLine3 | billAddrLine3 element of AReq; Third line of the street address or equivalent local portion of the Cardholder billing address associated with the card used for this purchase. Maximum 50 characters | -- | |
| billAddrPostCode | billAddrPostCode element of AReq; ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase. Maximum 16 characters | -- | |
| deliveryEmailAddress | deliveryEmailAddress element of AReq; For Electronic delivery, the email address to which the merchandise was delivered. Maximum 254 characters | -- | |
| deliveryTimeframe | deliveryTimeframe element of AReq; Indicates the merchandise delivery timeframe. 2 characters in length. Values accepted: 01, 02, 03, 04 | -- | |
| giftCardAmount | giftCardAmount element of AReq; For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123) Maximum 15 characters | 123 | |
| giftCardCount | giftCardCount element of AReq; For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased. 2 charatsers | -- | |
| giftCardCurr | giftCardCurr element of AReq; For prepaid or gift card purchase, the currency code of the card as defined in ISO 4217. 3 characters | -- | |
| preOrderDate | preOrderDate element of AReq; For a pre-ordered purchase, the expected date that the merchandise will be available. Accepted format: YYYYMMDD | -- | |
| preOrderPurchaseInd | preOrderPurchaseInd element of AReq; Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. 2 characters. Value accepted: 01, 02 | -- | |
| reorderItemsInd | reorderItemsInd element of AReq; Indicates whether the cardholder is reordering previously purchased merchandise. 2 characters. Value Accepted: 01, 02 | -- | |
| shipIndicator | shipIndicator element of AReq; Indicates shipping method chosen for the transaction. 2 characters. Value accepted: 01, 02, 03, 04, 05, 06, 07 | -- | |
| threeDSReqAuthData | threeDSReqAuthData element of AReq; Data that documents and supports a specific authentication process. Maximum 2048 characters | -- | |
| threeDSReqAuthMethod | threeDSReqAuthMethod element of AReq; Mechanism used by the Cardholder to authenticate to the 3DS Requestor. 2 characters. Value accepted: 01, 02, 03, 04, 05, 06 | -- | |
| threeDSReqAuthTimestamp | threeDSReqAuthTimestamp element of AReq; Date and time in UTC of the cardholder authentication. 12 characters. Format accepted: YYYYMMDDHHMM | -- | |
| threeDSReqPriorAuthData | threeDSReqPriorAuthData element of AReq; Data that documents and supports a specific authentication process. Maximum 2048 characters | -- | |
| threeDSReqPriorAuthMethod | threeDSReqPriorAuthMethod element of AReq; Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor. 2 characters. Value accepted: 01, 02, 03, 04 | -- | |
| threeDSReqPriorAuthTimestamp | threeDSReqPriorAuthTimestamp element of AReq; Date and time in UTC of the prior cardholder authentication. 12 characters. Format accepted: YYYYMMDDHHMM | -- | |
| threeDSReqPriorRef | threeDSReqPriorRef element of AReq; This data element provides additional information to the ACS to determine the best approach for handling a request. 36 characters | -- | |
| chAccAgeInd | chAccAgeInd element of AReq; Length of time that the cardholder has had the account with the 3DS Requestor. 2 characters. Value accepted: 01, 02, 03, 04, 05 | -- | |
| chAccChange | chAccChange element of AReq; Date that the cardholder’s account with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. 8 characters. Format accepted: YYYYMMDD | -- | |
| chAccChangeInd | chAccChangeInd element of AReq; Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added. 2 characters. Value accepted: 01, 02, 03, 04 | -- | |
| chAccDate | chAccDate element of AReq; Date that the cardholder opened the account with the 3DS Requestor. 8 characters. Format accepted: YYYYMMDD | -- | |
| chAccPwChange | chAccPwChange element of AReq; Date that cardholder’s account with the 3DS Requestor had a password change or account reset. 8 characters. Format accepted: YYYYMMDD | -- | |
| chAccPwChangeInd | chAccPwChangeInd element of AReq; Indicates the length of time since the cardholder’s account with the 3DS Requestor had a change or account reset. 2 characters. Values accepted: 01, 02, 03, 04, 05 | -- | |
| nbPurchaseAccount | nbPurchaseAccount element of AReq; Number of purchases with this cardholder account during the previous six months. maximum 4 characters | -- | |
| provisionAttemptsDay | provisionAttemptsDay element of AReq; Number of Add Card attempts in the last 24 hours. Maximum 3 characters | -- | |
| txnActivityDay | txnActivityDay element of AReq; Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours. Maximum 3 characters | -- | |
| txnActivityYear | txnActivityYear element of AReq; Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. Maximum 3 characters | -- | |
| paymentAccAge | paymentAccAge element of AReq; Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. 8 characters. Format accepted: YYYYMMDD | -- | |
| paymentAccInd | paymentAccInd element of AReq; Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor. 2 characters. Value accepted: 01, 02, 03, 04, 05 | -- | |
| shipAddressUsage | shipAddressUsage element of AReq; Date when the shipping address used for this transaction was first used with the 3DS Requestor. 8 characters. Format accepted: YYYYMMDD | -- | |
| shipAddressUsageInd | shipAddressUsageInd element of AReq; Indicates when the shipping address used for this transaction was first used with the 3DS Requestor. 2 characters. Value accepted: 01, 02, 03, 04 | -- | |
| shipNameIndicator | shipNameIndicator element of AReq; Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. 2 characters. Value accepted: 01, 02 | -- | |
| suspiciousAccActivity | suspiciousAccActivity element of AReq; Indicates whether the 3DS Requestor has experienced suspicious activity previous fraud) on the cardholder account. 2 characters. Value accepted: 01, 02 | -- | |
| threeDSCompInd | threeDSCompInd element of AReq; Indicates whether the 3DS Method successfully completed. 1 character. Value accepted: U, Y, N | -- | |
| threeDSRequestorAuthenticationInd | threeDSRequestorAuthenticationInd element of AReq; Indicates the type of Authentication request. 2 characters. Value accepted: 01, 02, 03, 04, 05, 06, 07 | -- | |
| threeDSRequestorChallengeInd | threeDSRequestorChallengeInd element of AReq; Indicates whether a challenge is requested for this transaction. 2 characters. Value accepted: 01, 02, 03, 04, 05, 06, 07, 08, 09, 82 | -- | |
| threeRIInd | threeRIInd element of AReq; Indicates the type of 3RI request. 2 characters. Value accepted: 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 11, 12, 80 | -- | |
| addrMatch | addrMatch element of AReq; Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same. 1 character. Value accepted: Y, N | -- | |
| acctID | acctID element of AReq; Additional information about the account optionally provided by the 3DS Requestor. Maximum 64 characters | -- | |
| email element of AReq; The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor. Maximum 254 characters | -- | ||
| homePhone.cc | homePhone element of AReq; The country code of home phone number provided by the Cardholder. 1-3 characters | -- | |
| homePhone.subscriber | homePhone element of AReq; The subscriber of the home phone number provided by the Cardholder. maximum 15 characters | -- | |
| mobilePhone.cc | mobilePhone element of AReq; The country code of mobile phone number provided by the Cardholder. 1-3 characters | -- | |
| mobilePhone.subscriber | mobilePhone element of AReq; The subscriber of the mobile phone number provided by the Cardholder. maximum 15 characters | -- | |
| workPhone.cc | workPhone element of AReq; The country code of work phone number provided by the Cardholder. 1-3 characters | -- | |
| workPhone.subscriber | workPhone element of AReq; The subscriber of the work phone number provided by the Cardholder. maximum 15 characters | -- |
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¶
| PreAuthResp | Table 13 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Code | Response code: 0 - The authentication will be exempted. The authentication will not be displayed and the appropriate response will be returned. 1 - The transaction is not exempt. The authentication page will be displayed. 2 - There was an error but ActiveAccess will display the authentication page and let the authentication continue. ActiveAccess will not cancel the authentication. 3 - The transaction is deemed to be high risk, ActiveAccess will decline the transaction. 4 - The transaction will be exempted with review. The authentication page will not be displayed and the appropriate response will be returned. | Required | 2 |
| AuthType | The comma separated list of decided authTypes by risk engine integration: 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 | Optional | 2, 14 |
| ErrorMessage | A descriptive message that identifies the category of the error | Optional | No card(s) found |
| ErrorDetail | A more detailed description of the error | Optional | No card(s) matching the request were found |
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.
Warning
This messaging is generally used only for out of band authentication and may be initiated either automatically by the system or manually, such as when a cardholder clicks on a "Send SMS" button on the page.
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 |
| 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 16 - Decoupled Authenticator(DA). 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 - Decoupled Authenticator(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 16 - Decoupled Authenticator(DA) | 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 AES/CBC/PKCS5Padding mode. The CBC encryption mode requires an Initialisation Vector (IV), which includes 16 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 AES/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¶
| InitAuthResp | Table 15 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Code | Response code: 0 - the request was successful 1 - there was an error and ActiveAccess should send the request again 2 - there was an error and ActiveAccess should cancel the authentication. | Required | 2 |
| ErrorMessage | A descriptive message that identifies the category of the error | Required | No card(s) found |
| ErrorDetail | A more detailed description of the error | Required | No card(s) matching the request were found |
| AuthData | Attributes of Data: Name (required) - the name of the AuthData parameter to be used for the data collection/disaply on the page, AuthType (conditional) - the AuthType of AuthData which will be used, 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, Refer to Table 8 - Data. | Conditional. Required if AuthTypeSup / AuthType is 2, 10, or 14. Recommended to mask the critical data such as mobile number. | authData=[data={[value=abababa, error=<null>, name=challenge, authType=10, format=\w+, mask=<null>, confirm=<null>],[value=<null>, error=<null>, name=response, authType=10, format=<null>, mask=<null>, confirm=<null>],[value=+421XXXXX1234, error=<null>, name=mobileNo, authType=2, format=<null>, mask=<null>, confirm=<null>]}], |
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¶
| VerifyAuthReq | Table 16 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Card | Where a value for Card.ID or Card.Context_Blob has 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 | |
| Token | The authentication number or password entered by the cardholder If an encryption KeyStore has been defined for the issuer or group of issuers, the token will be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode and IV, then HEX encoded and included in the message. CAAS server will need to decrypt this field using AES/CBC/PKCS5Padding mode and the request's IV before using it in the process. | Conditional. Required. if AuthType is NOT 2, 8 or 10. If any additional authentication types have been defined in VerifyRegResp.CardInfo.AuthTypeSup, the type of the authentication MUST be set along with entered Password/OTP when user/cardholder submits the Password/OTP page. | <token authType="2">987654</token> |
| AuthData | Attributes of Data: Name (required) - the name of the AuthData parameter to be used for data collection on the page, AuthType (conditional) - the AuthType of AuthData which has an error, 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 f the AuthData, and ACS will check that the two inputs match false - no confirmation input field will be displayed on the page Refer to Table 8 - Data. | Conditional. Required if AuthTypeSup / AuthType is 10. | authData=[data={[value=abababa, error=<null>, name=challenge, authType=10, format=<null>, mask=<null>, confirm=<null>],[value=resp, error=<null>, name=response, authType=10, format=<null>, mask=<null>, confirm=<null>]}] |
| Transaction | Additional transaction information may include transaction, cardholder and merchant information such as XID, PurchaseDate, PurchaseAmount, PurchaseCurrency, PurchaseDesc, MerchantID, AcqBIN, MerchantName, MerchantURL, MerchantCountry, CardExpiry and CardholderIP as described in the Initiate Authentication request section. Refer to Table 4 - Transaction. | Optional | transaction=[xid=MDAwMDAwMwMDAxMDA=, purchaseAmount=12365, purchaseCurrency=840, purchaseDate=[orig_eon=<(null)>, orig_year=2016, orig_month=11, orig_day=3, orig_hour=10, orig_minute=27, orig_second=31, orig_fracSeconds=0.000, orig_timezone=210, eon=<(null)>, year=2016, month=11, day=3, timezone=210, hour=10, minute=27, second=31, fractionalSecond=0.000], |
| IV | If an encryption KeyStore has been defined for the issuer or group of issuers, critical card data must be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode. The CBC encryption mode requires an Initialisation Vector (IV), which includes 16 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 AES/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. | 8F51F71064DB2B65 |
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.
| VerifyAuthResp | Table 17 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Code | Response code: 0 - the authentication was successful 1 - the authentication token was incorrect 2 - an error occurred and another attempt should be made 3 - the status of the card is locked 4 - an error occurred and no further attempts should be made. 5 - the authentication failed, transaction should end. | Required | 3 |
| AuthData | Attributes of Data: Name (required) - the name of the AuthData parameter to be used for data collection on the page AuthType (conditional) - the AuthType of AuthData which will be displayed on the authentication page 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 of the AuthData, and ACS will check that the two inputs match false - no confirmation input field will be displayed on the page Refer to Table 8 - Data. | Optional. When an error occurs, appropriate content can be returned. Otherwise, null will be returned. | authData=[data={[value=abababa, error=<null>, name=challenge, authType=10, format=<null>, mask=<null>, confirm=<null>],[value=1111, error=<null>, name=response, authType=10, format=<null>, mask=<null>, confirm=<null>]}] |
| ErrorMessage | A descriptive message that identifies the category of the error | Required | Card is locked |
| ErrorDetail | A more detailed description of the error | Required | The status of card is locked due to multiple unsuccessful login tries. |
| HeaderParams | Attributes of Param: Value (required) Key (required) Cookie (optional) | Optional | headerParams=[param={[value=value1, key=key1, cookie=true],...}], |
| ExtensionParams | Attributes of Param: Value (required) Key (required). | Optional | extensionParams=[param={[value=value1, key=key1],...}], |
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¶
| VerifyIdentityReq | Table 18 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Purpose | An attribute which indicates if Identity data are for the ADS or Forgot password process. 1 = reset password 2 = ADS | Required | 1 |
| IdentityData | Attributes of Data: Name (required) - the name of the IdentityData parameter to be used for data collection on the page AuthType (conditional) - empty value Format (optional) - empty value Mask (optional) - empty value Confirm (optional) - empty value Refer to Table 8 - Data. | Required | identityData=[data={[value=User1, error=<(null)>, name=cname, authType= <(null)>, format=<(null)>,, mask=<<(null)>,, confirm=<(null)>,], [value=123456, error=<(null)>,, name=pin, authType=<(null)>,, format=<(null)>,, mask=<(null)>, confirm=<(null)>,]}] |
| Transaction | Additional transaction information may include transaction, cardholder and merchant information such as XID, PurchaseDate, PurchaseAmount, PurchaseCurrency, PurchaseDesc, MerchantID, AcqBIN, MerchantName, MerchantURL, MerchantCountry, CardExpiry and CardholderIP Refer to Table 4 - Transaction for details. | Optional | |
| IV | If an encryption KeyStore has been defined for the issuer or group of issuers, critical card data must be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode. The CBC encryption mode requires an Initialisation Vector (IV), which includes 16 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 AES/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. | 8F51F71064DB2B65 |
| Card | Where a value for Card.ID or Card. Context_Blob has been 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 for details. | 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] |
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¶
| VerifyIdentityResp | Table 19 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Code | Response code: 0 - the authentication was successful, 1 - the authentication token was incorrect, 2 - an error occurred and another attempt should be made, 3 - the status of the card is locked, 4 - an error occurred and no further attempts should be made. | Required | 3 |
| IdentityData | Attributes of Data: Name (required) - The name of the IdentityData 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 of the AuthData, and ACS will check that the two inputs match false - no confirmation input field will be displayed on the page Refer to Table 8 - Data. | Optional. When an error occurs, appropriate content can be returned. Otherwise, null will be returned. | identityData=[data={[value=administrator11, error=[code=1, message=value mismatch, detail=value mismatch], name=cname, authType=<(null)>, format=<(null)>,, mask=<(null)>,, confirm=<(null)>],[value=123456, error=<(null)>, name=pin, authType=<(null)>, format=<(null)>, mask=<(null)>, confirm=<(null)>]}] |
| AuthData | Attributes of Data: Name (required) - the name of the AuthData parameter which will be registered or reset for the card, AuthType (conditional) - the AuthType of AuthData which will be registered or reset for the card, 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 of the AuthData, and ACS will check that the two inputs match false - no confirmation input field will be displayed on the page Refer to Table 8 - Data. | Required. If VerifyIdentityReq.purpose=1, reset AuthData will be returned. If VerifyIdentityReq.purpose=2, a list of all AuthData will be returned for the cardholder to choose from and register with. | authData=[data={[value=<(null)>, error=<(null)>, name=password, authType=1, format=<(null)>, mask=true, confirm=true],[value=<(null)>, error=<(null)>, name=mobileNo, authType=2, format=<(null)>, mask=<(null)>, confirm=true],[value=<(null)>, error=<(null)>, name=token, authType=2, format=<(null)>, mask=<(null)>, confirm=<(null)>] … }] |
| ErrorMessage | A descriptive message that identifies the category of the error | Optional | Card is locked |
| ErrorDetail | A more detailed description of the error | Optional | The status of card is locked due to multiple unsuccessful login attempts. |
Register¶
A request message should be sent to CAAS to set Authentication data for subsequent authentication.
Register Request¶
Table 20 – RegisterReq¶
| RegisterReq | Table 20 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| RegisterData | Attributes of Data: Name (required) - the name of the collected RegisterData from the page, AuthType (conditional) - the AuthType of the collected RegisterData from the page, Format (optional) - empty value, Mask (optional) - empty value, Confirm (optional) - empty value. Refer to Table 8 - Data. | Required | registerData=[data={[value=123456, error=<(null)>, name=password, authType=1, format=<(null)>, mask=<(null)>, confirm=<(null>)]}] |
| Card | Where a value for Card.ID or Card. Context_Blob has 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 | card=[id=4564260131003316, number=4564-26XX-XXXX-3316, type=VbV, cardName=<(null)>, Context_Blob=595], |
| Transaction | Additional transaction information may include transaction, cardholder and merchant information such as XID, PurchaseDate, PurchaseAmount, PurchaseCurrency, PurchaseDesc, MerchantID, AcqBIN, MerchantName, MerchantURL, MerchantCountry, CardExpiry and CardholderIP. Refer to Table 4 - Transaction. | Optional | transaction=[xid=MDAwMDAwMDAwMDAwMDAwMDAxMDA=, purchaseAmount=12365, purchaseCurrency=840, purchaseDate=[orig_eon=<(null)>, orig_year=2016, orig_month=11, orig_day=3, orig_hour=10, orig_minute=32, orig_second=20, orig_fracSeconds=0.000, orig_timezone=210, eon=<(null)>, year=2016, month=11, day=3, timezone=210, hour=10, minute=32, second=20, fractionalSecond=0.000] |
| IV | If an encryption KeyStore has been defined for the issuer or group of issuers, critical card data must be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode. The CBC encryption mode requires an Initialisation Vector (IV), which includes 16 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 AES/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. | 8F51F71064DB2B65 |
Register Response¶
Table 21 – RegisterResp¶
| RegisterResp | Table 21 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Code | Response code: 0 - the authentication was successful, 1 - the authentication token was incorrect, 2 - an error occurred and another attempt should be made, 3 - the status of the card is locked, 4 - an error occurred and no further attempts should be made. | Required | 3 |
| RegisterData | Attributes of Data: Name (required) - the name of the RegisterData parameter, Format (optional) - the regular expression of RegisterData for verifying the value which is 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 of the AuthData, and ACS will check that the two inputs match false - no confirmation input field will be displayed on the page. | Optional. If an error occurs, registerData would be sent back to ACS with an appropriate error message. Refer to Table 8 - Data. | registerData=[data={ [value=<(null)>, error=[code=1, message=invalid, detail=invalid], name=password, authType=1, format=<(null)>, mask=<(null)>, confirm=<(null)>]}] |
| ErrorMessage | A descriptive message that identifies the category of the error | Optional | |
| ErrorDetail | A more detailed description of the error | Optional |
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¶
| ResetPasswordReq | Table 22 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| ResetPasswordData | Attributes of Data: Name (required) - the name of the ResetPasswordData parameter, collected from the page, AuthType (conditional) - the AuthType of ResetPasswordData, collected from the page, Format (optional) - empty value, Mask (optional) - empty value, Confirm (optional) - empty value Refer to Table 21 – ResetPasswordResp. | Required | resetPasswordData= [data={[value=123123, error=<(null)>, name=password, authType=1, format=<(null)>, mask=<(null)>, confirm=<(null)>]}] |
| Card | Where a value for Card.ID or Card. Context_Blob has been 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 | card=[id=4564260131003313, number=4564-26XX-XXXX-3313, type=VbV, cardName=<(null)>, Context_Blob=595] |
| Transaction | Additional transaction information may include transaction, cardholder and merchant information such as XID, PurchaseDate, PurchaseAmount, PurchaseCurrency, PurchaseDesc, MerchantID, AcqBIN, MerchantName, MerchantURL, MerchantCountry, CardExpiry and CardholderIP. Refer to Table 4 - Transaction. | Optional | transaction=[xid=MDAwMDAwMDAwMDAxMDA=, purchaseAmount=12365, purchaseCurrency=840, purchaseDate=[orig_eon=<(null)>, orig_year=2016, orig_month=11, orig_day=3, orig_hour=10, orig_minute=33, orig_second=41, orig_fracSeconds=0.000, orig_timezone=210, eon=<(null)>, year=2016, month=11, day=3, timezone=210, hour=10, minute=33, second=41, fractionalSecond=0.000] |
| IV | If an encryption KeyStore has been defined for the issuer or group of issuers, critical card data must be encrypted by ActiveAccess using AES/CBC/PKCS5Padding mode. The CBC encryption mode requires an Initialisation Vector (IV), which includes 16 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 AES/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. |
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¶
| ResetPasswordResp | Table 23 | ||
|---|---|---|---|
| Attribute | Description | Usage | Sample Value |
| Code | Response code: 0 - the authentication was successful, 1 - the authentication token was incorrect, 2 - an error occurred and another attempt should be made, 3 - the status of the card is locked, 4 - an error occurred and no further attempts should be made. | Required | 3 |
| ResetPasswordData | Attributes of Data: Name (required) - the name of the ResetPasswordData parameter, AuthType (conditional) - the AuthType of ResetPasswordData, Format (optional) - the regular expression for verifying the value collected from the page, Mask (optional) - true - input on the page will be masked 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 of the AuthData, and ACS will check that the two inputs match false - no confirmation input field will be displayed on the page Refer to Table 8 - Data. | Optional. When an error occurs, appropriate content can be returned. | resetPasswordData= [data={[value=<(null)>, error=[code=1, message=invalid, detail=invalid], name=password, authType=1, format=<(null)>, mask=<(null)>, confirm=<(null)>]}] |
| ErrorMessage | A descriptive message that identifies the category of the error | Optional | |
| ErrorDetail | A more detailed description of the error | Optional |
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 128 or 256 bit AES 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: AES
Key size: 128 or 256 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 enckey256 -keypass 123456 -keyalg AES -keysize 256 -keystore enc-key.JKS -storepass 123456 -storetype JCEKS
Calling Convention¶
Requests will be sent using SOAP on HTTPS.
Remote System Integration WSDL¶
Important
It is important to ensure messages conform to the requirements of the remote system integration API by validating them against the WSDL and XSD schema.
The Remote System Integration WSDL and XSD schema can be found in the ActiveAccess installation package in the following path:
ActiveAccess/files/acs.war/WEB-INF/lib/caas.client-*.jar