Skip to content

Out of Band Authentication Adapter

Adapter Loading Process

The ActiveAccess ACS performs Out Of Band (OOB) challenges through OOB Adapters, which connect the existing OOB authentication system with ActiveAccess. During 3DSecure 2.0 challenge flows where OOB Authentication is required, the ACS will trigger the external OOB process and perform interactions with the Cardholder via the OOB Adapters.

For this purpose, the ACS communicates with the existing OOB-System via a middleware, known as the OOB Adapter. The OOB Adapter can be either loaded locally by the ACS or communicated via HTTP calls, known as the Native API and REST API versions respectively.

Native API version of OOB Adapter

The Native API version of OOB Adapter is known as oob.adapter in this specification. The Native Adapters are provided in the form of JAR files, by GPayments or ActiveAccess clients. Only Java is supported for the Native API version of OOB Adapter.

Native OOB Adapter developers provide the adapters in one or more JAR files. The oob.adapter implementation in the adapter must implement the Java interface OobAdapterService.

Implementation Steps

The steps for implementing OOB Adapter are:

  1. OOB Adapter developers create a Java project and obtain the corresponding Adapter API library from the ActiveAccess package. This library contains the interface definition for oob.adapter.
  2. The Native API Adapter should be implemented as a Service based on the OOB interface OobAdapterService. This specific implementation of the service known as service provider. ACS loads this class in startup and uses it in OOB Authentication. The requirement enforced by ACS is that provider class must have a public zero-argument constructor so that it can be instantiated during loading.
  3. A service provider is identified by placing a provider-configuration file in the resource directory META-INF/services. The file's name is the fully-qualified binary name of the service's type, e.g. com.gpayments.acs.oob.OobAdapterService. The file contains a list of fully-qualified binary names of concrete provider classes, one per line. Space and tab characters surrounding each name, as well as blank lines, are ignored. The comment character is '#' ('\u0023', NUMBER SIGN); on each line all characters following the first comment character are ignored. The file must be encoded in UTF-8.

OobAdapterService methods

OobAdapterService interface has four methods:

  • ping: Checks if the OOB Server responses to ping or not.
  • getAdapterInfo: Returns information about oob.adapter
  • requestChallenge: To call when OOB authentication is necessary and returns whether the authentication method for the card is available or not.
  • getChallengeResult: Checks if the card is authenticated successfully or not.

The Input and Output of each OobAdapterService method are:

ping
  • Input: This method takes no arguments.
  • Output: The result of OOb Server pinging should be returned in a boolean value; if the server responses to ping successfully, true should be returned, otherwise false should be returned.
getAdapterInfo
  • Input: This method takes no arguments.
  • Output: An object of AdapterInfo class that contains some information about oob.adapter should be returned. Instance variables of AdapterInfo class are:
    • id: The ACS assigned UUID to the oob.adapter. This field is required and of type String.
    • name: The ACS assigned name to the oob.adapter. This field is required and of type of String.
    • version: The int value that indicates version of oob.adapter.
    • signature: Signature to validate oob.adapter integrity, not used currently, will be included in a future version. It is of type String.
requestChallenge
  • Input: This method requires two parameters to accomplish its task, of types String and TransactionInfo. The method expects to receive acsTransactionId as the first argument and an object of TransactionInfo class (for a detailed explanation, refer to the TransactionInfo Data Elements section) as the second.
  • Output: When requestChallenge method is called and has completed its task, it must return an object of OobRequestChallengeResult type. OobRequestChallengeResult class has three instance variables, named requestChallengeEnum, oobTransId and message, that are of type RequestChallengeEnum, String and String respectively. requestChallengeEnum maintains the result of requesting OOB challenge to OOB-System; valid values for this attribute are OK and ERROR. oobTransId is a unique ID that can be generated by OOB-System to be used in getting the challenge result. oobTransId is an optional attribute and can have no value. If any message is required to be returned it should be maintained in the message attribute.
getChallengeResult
  • Input: This method requires two parameters; the first is acsTransactionId of type String and the second is oobTransId retrieved from requestChallenge output. oobTransId is of type String.
  • Output: After completing getChallengeResult method's task, it must return an object of OobAuthenticationResult class to the method's caller. OobAuthenticationResult class has two instance variables, named authenticationResultEnum and message, that are of types AuthenticationResultEnum (enum) and String respectively. authenticationResultEnum maintains the result of the OOB challenge; valid values for this attribute are AUTHENTICATED, NOT_AUTHENTICATED, ERROR or PENDING. If any message is required to be returned it should be maintained in the message attribute. A default message will be displayed on the page in case of the missing message in PENDING.

Restful API version of OOB Adapter

For the Restful API version of the oob.adapter, a Restful API needs to be defined similar to the adapter interface. ACS implements the Restful client and the OOB Adapter API Server will be implemented by the client. In this case, no JARs or plugins need to be loaded by ACS. Clients must provide a specific URL for ACS. Known as Adapter-URL in this document and the required REST API endpoints are defined based on this URL.

dc_new.png

Note

We also provide a Swagger API for the sample REST OOB Adapter server that is included in release package. To use it, run OOB Server in the installation package and then open https://localhost:8447/swagger-ui.html#/ in your browser.

Check Adapter Server availability status

ACS sends an HTTP request to check whether Adapter Server is up or down. Details of this request are:

  • URL: Adapter-URL/ping
  • Request Method: GET
  • Request Parameters: there are not any request parameters for this REST API
  • Response: If Adapter Server is accessible for the OOB challenge processes, this API returns an HTTP entity with a 200 (OK) HTTP status code.

Get OOB Adapter Information

ACS sends an HTTP request to get oob.adapter information. The details of this request are:

  • URL: Adapter-URL/adapter-info
  • Request Method: GET
  • Request Parameters: there are not any request parameters for this REST API
  • Response:
    • Name: adapterInfo
    • Format JSON object of AdapterInfo.
    • Description AdapterInfo has four properties:
      • id: The ACS assigned UUID to the oob.adapter. This field is required and of type String.
      • name: The ACS name assigned to the oob.adapter. This field is required and of type of String.
      • version: The int value that indicates the version of oob.adapter.
      • signature: Signature to validate oob.adapter integrity, not currently used, will be included in a future version. It is of type String.
      • Inclusion: Required

Requeste OOB Challenge

ACS calls an HTTP API when OOB authentication is necessary and returns whether authentication method for the card is available or not.

  • URL: Adapter-URL/request-challenge/{acsTransactionId}
  • Request Method: POST

  • Path variables:

    • Name: acsTransactionId
    • Format: String
    • Inclusion: required

  • Request Body:

    • Name: transactionInfo
    • Format: JSON object of TransactionInfo type. For further details of TransactionInfo, refer to the TransactionInfo Data Elements section.
    • Response:
      • Name: oobRequestChallengeResult
      • Format: JSON object of OobRequestChallengeResult.
      • Description: OobRequestChallengeResult object has three instance variables, named requestChallengeEnum, oobTransId and message. requestChallengeEnum maintains the result of requesting OOB challenge to OOB-System; valid values for this attribute are OK and Error. oobTransId is the ID assigned by oob.adapter for the next requests. If any message is required to be returned it should be maintained in message attribute.
      • Inclusion: required

Check card OOB authentication result

ACS calls an HTTP API to check if the card is authenticated successfully or not. The details of this REST API are:

  • URL: Adapter-URL/challenge-result/{acsTransactionId}/{oobTransId}
  • Request Method: GET
  • Path variables:
    • Name: acsTransactionId
    • Format: String
    • Inclusion: required
    • Name: oobTransId
    • Format: String
    • Inclusion: Optional
  • Response:
    • Name: oobAuthenticationResult
    • Format: JSON object of OobAuthenticationResult class.
    • Description: OobAuthenticationResult class has two instance variables, named authenticationResultEnum and message. authenticationResultEnum maintains the result of OOB challenge; valid values for this attribute are AUTHENTICATED, NOT_AUTHENTICATED, ERROR, and PENDING. If any message is required to be returned it should be maintained in message attribute. A default message will be displayed on the page in case of the missing message in PENDING.
    • Inclusion: Required

Authentication mechanism for the Restful API version

Certificate based mutual authentication is used as the authentication mechanism for the Restful API version. The steps are:

  • ACS publishes a CA for adapter communication, known as Adapter CA
  • ACS also issues a server certificate for the adapter.
  • ACS uses a generated client certificate that is issued by the same Adapter CA.
  • The Adapter server implementation must be set up with the CA and mutual authentication provided.
  • ACS will try to connect to the Adapter Server and if the connection can be established then ACS will continue with the adapter, otherwise it throws an error.

OobAdapterService Data Elements

TransactionInfo Data Elements

  • Field Name: threeDSServerTransID

    • Description: Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.
    • Length: 36 characters
    • Format: String
    • Accepted Value: Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions if the output meets specified requirements.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Required

  • Field Name: purchaseAmount

    • Description: Purchase amount in minor units of currency with all punctuation removed. When used in conjunction with the Purchase Currency Exponent field, proper punctuation can be calculated.
    • Length: 48 characters
    • Format: String
    • Accepted Value: Example: If the purchase amount is USD 123.45, element will contain the value 12345.
    • Device Channel: 01-APP, 02-BRW
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: 01-PA: Required, 02-NPA: Conditional
    • Conditional Inclusion: Required for 02NPA if 3DS Requestor Authentication Indicator = 02 or 03.

  • Field Name: purchaseCurrency

    • Description: Currency in which purchase amount is expressed.
    • Length: 3 characters
    • Format: String
    • Accepted Value: ISO 4217 three-digit currency code; 901-999 values are excluded and not permitted.
    • Device Channel: 01-APP, 02-BRW
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: 01-PA: Required, 02-NPA: Conditional
    • Conditional Inclusion: Required for 02NPA if 3DS Requestor Authentication Indicator = 02 or 03.

  • Field Name: purchaseExponent

    • Description: Minor units of currency as specified in the ISO 4217 currency exponent.
    • Length: 1 character
    • Format: String
    • Accepted Value: Number
    • Device Channel: 01-APP, 02-BRW
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: 01-PA: Required, 02-NPA: Conditional
    • Conditional Inclusion: Required for 02NPA if 3DS Requestor Authentication Indicator = 02 or 03.

  • Field Name: messageCategory

    • Description: Identifies the category of the message for a specific use case
    • Length: 2 characters
    • Format: String
    • Accepted Value: 01-PA, 02-NPA
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Required

  • Field Name: deviceChannel

    • Description: Indicates the type of channel interface being used to initiate the transaction.
    • Length: 2 Characters
    • Format: String
    • Accepted Value: 01 (APP); 02 (BRW); 03 (3RI)
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Required

  • Field Name: acctNumber

    • Description: Account number that will be used in the authorisation request for payment transactions. It will be represented by PAN.
    • Length: 13-19 Characters
    • Format: String
    • Accepted Value: Format represented ISO 7812.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Required

  • Field Name: merchantName

    • Description: Merchant name assigned by the Acquirer or Payment System.
    • Length: Variable, maximum 40 characters
    • Format: String
    • Accepted Value: Same name used in the authorisation message as defined in ISO 8583.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: 01-PA: Required, 02-NPA: Optional
    • Conditional Inclusion: Optional but strongly recommended to include for 02NPA if the merchant is also the 3DS Requestor.

  • Field Name: cardHolderInfo

    • Description: Information about the Cardholder, which is provided by the 3DS Requestor. For further details, refer to the CardHolderInfo Data Elements section
    • Type: CardHolderInfo

  • Field Name: issuerName

    • Description: Name of the Issuer
    • Length: Variable, maximum 64 characters.
    • Format: String
    • Accepted Value: Any.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Required

CardHolderInfo Data Elements

  • Field Name: cardholderName

    • Description: Cardholder name
    • Length: 2-45
    • Format: String
    • Accepted Value: Alphanumeric special characters, listed in EMVBook 4, “Appendix B”.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information.

  • Field Name: email

    • Description: The email address associated with the account that is either entered by the Cardholder, or is on file with the 3DS Requestor.
    • Length: 254 Characters
    • Format: String
    • Accepted Value: Shall meet requirements of Section 3.4 of IETF RFC 5322.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information.

  • Field Name: homePhone

    • Description: The home phone number provided by the Cardholder. For further details, refer to the HomePhone Data Elements section
    • Type: HomePhone
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information.

  • Field Name: mobilePhone

    • Description: The mobile phone number provided by the Cardholder. For further details, refer to the MobilePhone Data Elements section
    • Type: MobilePhone
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required unless market or regional mandate restricts sending this information.

  • Field Name: shipAddrCity

    • Description: City portion of the shipping address requested by the Cardholder
    • Length: Variable, maximum 50 Characters
    • Format: String
    • Accepted Value:
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Optional

  • Field Name: shipAddrCountry

    • Description: Country of the shipping address requested by the Cardholder.
    • Length: 3 Characters
    • Format: String
    • Accepted Value: ISO 3166-1 three-digit country code; 901-999 values are excluded and not permitted.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Optional

  • Field Name: shipAddrLine1

    • Description: First line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
    • Length: Variable, maximum 50 Characters
    • Format: String
    • Accepted Value:
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Optional

  • Field Name: shipAddrLine2

    • Description: Second line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
    • Length: Variable, maximum 50 Characters
    • Format: String
    • Accepted Value:
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Optional

  • Field Name: shipAddrLine3

    • Description: Third line of the street address or equivalent local portion of the shipping address requested by the Cardholder.
    • Length: Variable, maximum 50 Characters
    • Format: String
    • Accepted Value:
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Optional

  • Field Name: shipAddrPostCode

    • Description: The ZIP or other postal code of the shipping address requested by the Cardholder
    • Length: Variable, maximum 16 Characters
    • Format: String
    • Accepted Value:
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Optional

  • Field Name: shipAddrState

    • Description: The state or province of the shipping address associated with the card being used for this purchase.
    • Length: Variable, maximum 3 Characters
    • Format: String
    • Accepted Value: Should be the country subdivision code defined in ISO 3166-2.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Optional

  • Field Name: workPhone

    • Description: The work phone number provided by the Cardholder. For further details, refer to the WorkPhone Data Elements section
    • Type: WorkPhone
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Conditional
    • Conditional Inclusion: Required (if available) unless market or regional mandate restricts sending this information.

HomePhone Data Elements

  • Field Name: cc

    • Description: Country Code of the number
    • Length: 1-3 Characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA

  • Field Name: subscriber

    • Description: Subscriber sections of the number
    • Length: Variable, maximum 15 Characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA

MobilePhone Data Elements

  • Field Name: cc

    • Description: Country Code of the number
    • Length: 1-3 Characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA

  • Field Name: subscriber

    • Description: Subscriber sections of the number
    • Length: Variable, maximum 15 Characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA

WorkPhone Data Elements

  • Field Name: cc

    • Description: Country Code of the number
    • Length: 1-3 Characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA

  • Field Name: subscriber

    • Description:
    • Length: Variable, maximum 15 Characters
    • Format: String
    • Accepted Value: Refer to ITU-E.164 for additional information on format and length.
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA