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 Adapter in the com.gpayments.oob.api.v1 package.

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 (Native OOB Adapter).

  2. The Native API Adapter should be implemented as a Service based on the OOB interface Adapter. 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.oob.api.v1.Adapter. 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.

Adapter Interface Methods

The Adapter interface has four methods as follows:

  • Method Name: getAdapterInfo

    • Description: Returns information about oob.adapter
    • Input: This method takes no arguments
    • Output: An instance of AdapterInfo class that contains information about oob.adapter should be returned. The AdapterInfo is explained in detail in the AdapterInfo Data Elements section.

  • Method Name: ping

    • Description: Checks whether OOB-Authenticator Server is accessible or not
    • Input: This method takes no arguments
    • Output: The result of OOB Server pinging should be returned in a boolean value. If the server responds to ping successfully, true should be returned, otherwise false should be returned.

  • Method Name: requestChallenge

    • Description: To call when OOB authentication is necessary and returns whether authentication method for the card is available or not.

    • Input: This method takes the following parameters:

      • Field Name: acsTransactionId

        • Description: Universally Unique identifier assigned by the ACS to identify a single transaction
        • Length: 36 characters
        • Format: String
        • Accepted Value: Canonical format as defined in IETF RFC 4122
        • Message Inclusion: Required

      • Field Name: transactionInfo

        • Description: Information about the transaction, which is required for the OOB authentication
        • Length:
        • Format: An instance of type TransactionInfo. TransactionInfo is explained in detail in the TransactionInfo Data Elements section.
        • Accepted Value:
        • Message Inclusion: Required

    • Output: Adapter requestChallenge method has a OobRequestChallengeResult return type

      • Field Name: oobRequestChallengeResult
        • Description:
        • Length:
        • Format: An instance of type OobRequestChallengeResult. OobRequestChallengeResult is explained in details in the OobRequestChallengeResult Data Elements section.
        • Accepted Value:
        • Message Inclusion: Required

  • Method Name: getChallengeResult

    • Description: Checks if the card is authenticated successfully or not

    • Input: This method takes the following parameters:

      • Field Name: acsTransactionId

        • Description: Universally Unique identifier assigned by the ACS to identify a single transaction.
        • Length: 36 characters
        • Format: String
        • Accepted Value: Canonical format as defined in IETF RFC 4122
        • Message Inclusion: Required

      • Field Name: oobTransId

        • Description: Unique identifier assigned by the OOB-Authenticator-System to identify a single OOB Authentication Challenge
        • Length: Variable, maximum 36 characters.
        • Format: String
        • Accepted Value:
        • Message Inclusion: Optional

      • Field Name: additionalInfo

        • Description: Some additional Information for OOB authentication
        • Length:
        • Format: JSON object of AdditionalInfo type. AdditionalInfo is explained in the AdditionalInfo Data Elements section.
        • Accepted Value:
        • Message Inclusion: Optional

    • Output: Adapter getChallengeResult method has a OobAuthenticationResult return type.

      • Field Name: oobAuthenticationResult
        • Description:
        • Length:
        • Format: An instance of type OobAuthenticationResult. OobAuthenticationResult is explained in details in the OobAuthenticationResult Data Elements section.
        • Accepted Value:
        • Message Inclusion: Required

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.

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.

Get OOB Adapter Information

The 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: For further details on AdapterInfo, refer to the AdapterInfo Data Elements section.
    • Inclusion: Required

dc_new.png

Sample request

HTTP URL: http://localhost:8447/restful-adapter/oob/adapter-info

Sample response

{
  "id": "0b99b82f-62cf-4275-88b3-de039020f14e",
  "name": "restful-adapter",
  "version": "1",
  "signature": "SIGNATURE"
}

Check OOB Authenticator Server availability status

The ACS sends an HTTP request to check whether OOB Authenticator Server is accessible or not. The 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 to perform the OOB challenge process, this API returns an HTTP entity with 200 (OK) HTTP status code.

Request 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 on TransactionInfo, refer to the TransactionInfo Data Elements section.
    • Inclusion: required
  • Response:
    • Name: oobRequestChallengeResult
    • Format: JSON object of OobRequestChallengeResult.
    • Description: OobRequestChallengeResult is explained in details in the OobRequestChallengeResult Data Elements section.
    • Inclusion: required

dc_new.png

Sample Request

HTTP URL: http://localhost:8447/restful-adapter/oob/request-challenge/da3cb8f9-90a2-489b-a7af-28ba33ce924a

Body: {
  "acctNumber": 4548812049400004,
  "additionalInfo": {
    "clientId": "123456789012345",
    "deviceId": "123e4567-e89b-12d3-a456-426655440000"
  },
  "cardHolderInfo": {
    "cardholderName": "cardholderName",
    "email": "abc@example.com",
    "homePhone": {
      "cc": 61,
      "subscriber": 234567890
    },
    "mobilePhone": {
      "cc": 61,
      "subscriber": 234567890
    },
    "shipAddrCity": "shipAddrCity",
    "shipAddrCountry": "040",
    "shipAddrLine1": "shipAddrLine1",
    "shipAddrLine2": "shipAddrLine2",
    "shipAddrLine3": "shipAddrLine3",
    "shipAddrPostCode": "shipAddrPostCode",
    "shipAddrState": "VIC",
    "workPhone": {
      "cc": 61,
      "subscriber": 234567890
    }
  },
  "deviceChannel": "01",
  "issuerName": "AnyBank",
  "merchantName": "merchantName",
  "messageCategory": "01",
  "purchaseAmount": 12345,
  "purchaseCurrency": "036",
  "purchaseExponent": 2,
  "threeDSServerTransID": "a4edc97f-4b89-4e52-8590-6c328f0b9648"
}

Sample response

{
  "requestChallengeEnum": "OK",
  "oobTransId": "0679cb73-ea9a-41fb-8fda-dec78a46cd0b",
  "message": null
}

Get OOB authentication result

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

  • URL: Adapter-URL/challenge-result/{acsTransactionId}/{oobTransId} (or Adapter-URL/challenge-result/{acsTransactionId} if oobTransId is null.)
  • Request Method: POST

  • Path variables:

    • Name: acsTransactionId
    • Format: String

    • Inclusion: Required

    • Name: oobTransId

    • Format: String
    • Inclusion: Optional

  • Request Body:

    • Name: additionalInfo
    • Format: JSON object of AdditionalInfo type. You can find details of AdditionalInfo in the AdditionalInfo Data Elements section.
  • Response:
    • Name: oobAuthenticationResult
    • Format: JSON object of type OobAuthenticationResult
    • Description: OobAuthenticationResult is explained in details in the OobAuthenticationResult Data Elements section.
    • 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.

Adapter Data Elements

AdapterInfo Data Elements

  • Field Name: id

    • Description: The ACS assigned UUID to the OOB Adapter
    • Length: 36 characters
    • Format: String
    • Accepted Value: Canonical format as defined in IETF RFC 4122
    • Message Inclusion: Required

  • Field Name: name

    • Description: The ACS assigned name to the OOB Adapter
    • Length: Variable, maximum 100 Characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: version

    • Description: The number that indicates the OOB Adapter version
    • Length: Variable
    • Format: String
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: signature

    Note

    This field is not currently used and is reserved for for future versions.

    • Description: Signature to validate OOB Adapter integrity
    • Length: Variable
    • Format: String
    • Accepted Value:
    • Message Inclusion: Optional

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: additionalInfo

    • Description: Some additional Info for OOB authentication
    • Length:
    • Format: JSON object of AdditionalInfo type. AdditionalInfo is explained in the AdditionalInfo Data Elements section.
    • Accepted Value:
    • Device Channel: 01-APP, 02-BRW, 03-3RI
    • Message Category: 01-PA, 02-NPA
    • Message Inclusion: Optional

  • 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; 955-964 and 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, token.
    • Length: 13-19 Characters, dc_new.png or up to 72 characters when encryption for sensitive data is enabled
    • 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

AdditionalInfo Data Elements

  • Field Name: clientId

    • Description: Client ID
    • Length: 15 characters
    • Format: String
    • Accepted Value: Decimal numbers
    • dc_new.png Message Inclusion: Optional (this field will be excluded from RESTful JSON message when it has no value)

  • Field Name: deviceId

    • Description: Device ID
    • Length: Variable, maximum 36 characters
    • Format: String
    • Accepted Value: Any
    • dc_new.png Message Inclusion: Optional (this field will be excluded from RESTful JSON message when it has no value)

CardHolderInfo Data Elements

  • Field Name: cardholderName

    • Description: Cardholder name
    • Length: 2-45 characters dc_new.png or up to 104 characters when encryption for sensitive data is enabled
    • 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: 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

OobRequestChallengeResult Data Elements

  • Field Name: requestChallengeEnum

    • Description: Result of requesting OOB authentication challenge to OOB-Authenticator-System, that determines whether OOB authentication method is available for this card or not.
    • Length:
    • Format:
    • Accepted Value: OK, ERROR
    • Accepted Value:
    • Message Inclusion: Required

  • Field Name: oobTransId

    • Description: Unique identifier assigned by the OOB-Authenticator-System to identify a single OOB Authentication Challenge.
    • Length: Variable, maximum 36 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Optional

  • Field Name: message

    • Description: Any required message that should be returned to the ACS
    • Length: Variable, maximum 500 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Optional

OobAuthenticationResult Data Elements

  • Field Name: authenticationResultEnum

    • Description: Result of OOB authentication challenge
    • Length:
    • Format:
    • Accepted Value: AUTHENTICATED, NOT_AUTHENTICATED, ERROR, PENDING
    • Message Inclusion: Required

  • Field Name: message

    • Description: Any required message that should be returned to the ACS
    • Length: Variable, maximum 500 characters
    • Format: String
    • Accepted Value:
    • Message Inclusion: Optional