On This Page
The device collection process must finish before the customer selects the option to buy. You must receive a response before requesting the Check Enrollment service.

Request Fields

The
consumerAuthenticationInformation.referenceId
 field is mapped from the
consumerAuthenticationInformation.referenceId
 field as discussed in Step 1: Payer Authentication Setup Service.
consumerAuthenticationInformation.returnUrl
 is set to the URL where the issuing bank will redirect the customer as discussed in Step 4: Step-Up IFrame.
To request the Payer Authentication Check Enrollment service, you must send either the customer’s card number, encrypted payment data, transient token, or a TMS token or transient token or some other equivalent of card data used by your integration. The request fields may include any of the following:
  • paymentInformation.card.number
  • paymentInformation.fluidData.value
  • paymentInformation.fluidData.descriptor
  • paymentInformation.customer.customerID
  • tokenInformation.transientToken
The following fields are required (merchant ID is in the header):
  • orderInformation.amountDetails.totalAmount
  • orderInformation.billTo.address1
  • orderInformation.billTo.locality
  • orderInformation.billTo.country
  • orderInformation.billTo.administrativeArea
  • orderInformation.billTo.postalCode
  • paymentInformation.card.type
  • orderInformation.amountDetails.currency
  • paymentInformation.card.expirationMonth
  • paymentInformation.card.expirationYear
  • orderInformation.billTo.email
  • orderInformation.billTo.firstName
  • orderInformation.billTo.lastName
  • consumerAuthenticationInformation.referenceId
  • consumerAuthenticationInformation.returnUrl
  • clientReferenceInformation.code
You can send additional request data to reduce your issuer step-up authentication rates. It is recommended to send all available fields. You should include the 11 device information fields listed among the optional fields for the Check Enrollment service in your request as a backup, in case, Device Data Collection fails. If a failure does occur, adding these fields ensures a transaction is not downgraded to 3-D Secure 1.0. If you do not have data for a field, do not send dummy data.
The size of the step-up iframe discussed in Step 4: Step-Up IFrame can vary depending on the 3-D Secure version of the transaction (1.0 or 2.x ). You can send the size of the challenge window in the
consumerAuthenticationInformation.acsWindowSize
 request field.
Requesting a specific Window size does not guarantee this size. Parsing the PAReq as described in Step 4: Step-Up IFramedetermines the actual size.
For further details on individual API fields, refer to the The field values should use the ISO 3166-2 format.

Combining Services

You can use the enrollment check and card authorization services in the same request or in separate requests. Using the same request is recommended.
  • Same request: Attempts to authorize the card after authentication are made if step-up payer authentication is not required. In this case, the field values that are required to prove that you attempted to check enrollment are passed automatically to the authorization service. With same request transactions, a different endpoint must be referenced and an additional element must be added to the JSON. If step-up authentication is required, processing stops to allow completion, and authorization is not called. This integration method is recommended.
  • Separate requests: You must manually include the enrollment check result values (Enrollment Check Response Fields) in the authorization service request (Card Authorization Request Fields).
Depending on your card type and whether it is a 3-D Secure 1.0 or 2.x transaction, you might not receive the XID. If you receive this field back under a frictionless scenario, it is required for authorization.
The following table lists these fields.
Enrollment Check and Response Fields
Identifier
Enrollment Check Response Field
Card Authorization Request Field
consumerAuthenticationInformation.indicator
processingInformation.commerceIndicator
Collection indicator (Mastercard only)
consumerAuthenticationInformation.ucafCollectionIndicator
consumerAuthenticationInformation.ucafCollectionIndicator
CAVV
consumerAuthenticationInformation.cavv
consumerAuthenticationInformation.cavv
AAV
consumerAuthenticationInformation.ucafAuthenticationData
consumerAuthenticationInformation.ucafAuthenticationData
XID
consumerAuthenticationInformation.xid
 and
consumerAuthenticationInformation.xid
Result of the enrollment check for Asia, Middle East, and Africa Gateway
consumerAuthenticationInformation.veresEnrolled
consumerAuthenticationInformation.veresEnrolled
3-D Secure version
consumerAuthenticationInformation.specificationVersion
consumerAuthenticationInformation.paSpecificationVersion
Directory server transaction ID
(Not required for 3-D Secure 1.0.)
consumerAuthenticationInformation.directoryServerTransactionId
consumerAuthenticationInformation.directoryServerTransactionId

Interpreting the Response

The responses are similar for all card types.
  • Enrolled cards: You receive
    PENDING_AUTHENTICATION
     if the customer’s card is enrolled in a payer authentication program. When you receive this response, proceed to Step 4: Step-Up IFrame.
  • Cards not enrolled, or step-up authentication not required: You receive
    AUTHENTICATION_SUCCESSFUL
     in the following cases:
    • When the account number is not eligible for a payer authentication program or when step-up authentication is not required. The other services in your request are processed normally. If you are making separate enrollment and authorization calls, you must include pertinent payer authentication data in the authorization request to receive liability shift protection.
    • When payer authentication is not supported by the card type. When you receive this response, you can proceed to card authorization. If you receive the authentication results along with
      AUTHENTICATION_SUCCESSFUL
      , you might receive liability shift protection.
    An
    AUTHENTICATION_FAILED
     status may occur that requires the merchant to display a card issuer message to the cardholder using the
    consumerAuthenticationInformation.cardholderMessage
     field.
    The message text is provided by the ACS/issuer to the cardholder during a frictionless or decoupled transaction to convey information to cardholder. For example, “Additional authentication is needed for this transaction, contact (issuer name) at xxx-xxx-xxxx.”
    The entry that appears in the log will be similar to this example:
    "cardholderInfo":"You're unable to complete this purchase right now. For help call CommBank on 13 2221"

Important Response Fields

When you receive
PENDING_AUTHENTICATION
, you also receive the following fields: