Requesting the Check Enrollment Service (SDK)

After the SDK completes the device collection from your mobile application, and after the customer clicks the Buy button, you must make a back-end, server-to-server call to request the Enrollment Check service.

The Check Enrollment service verifies that the card is enrolled in a card authentication program. The merchant ID is included as part of the header, but these fields are required in the request:

consumerAuthenticationInformation.referenceId

orderInformation.amountDetails.currency

orderInformation.amountDetails.totalAmount

orderInformation.billTo.address1

orderInformation.billTo.administrativeArea

orderInformation.billTo.country

orderInformation.billTo.email

orderInformation.billTo.firstName

orderInformation.billTo.lastName

orderInformation.billTo.locality

orderInformation.billTo.postalCode

paymentInformation.card.expirationMonth

paymentInformation.card.expirationYear

paymentInformation.card.number

paymentInformation.card.type

IMPORTANT

To reduce your issuer step-up authentication rates, you can send additional request data in order. It is best to send all available fields.

Use the enrollment check and card authorization services in the same request or in separate requests:

Same request:

Cybersource

attempts to authorize the card if your customer is not enrolled in a payer authentication program. In this case, the field values that are required to prove that you attempted to check enrollment are passed automatically to the authorization service. If authentication is required, processing automatically stops.

Separate requests: Manually include the enrollment check result values (Enrollment Check response fields) in the authorization service request (Card Authorization request fields).

Be sure to include the following card-specific information in your authorization request:

For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo, include the CAVV.

For Mastercard only, include the collection indicator and the AAV (also known as UCAF).

These fields are listed in this table.

Enrollment Check and Response Fields
Identifier	Enrollment Check Response Field	Card Authorization Request Field
E-commerce indicator	consumerAuthenticationInfo rmation.ecommerceIndicator	processingInformation.commerceIndicator
Collection indicator	consumerAuthenticationInfo rmation.ucafCollectionIndicator	consumerAuthenticationInfo rmation.ucafCollectionIndicator
CAVV	consumerAuthenticationInfo rmation.cavv	consumerAuthenticationInfo rmation.cavv
AAV	consumerAuthenticationInfo rmation.ucafAuthentication Data	consumerAuthenticationInfo rmation.ucafAuthentication Data
XID	consumerAuthenticationInfo rmation.xid and	consumerAuthenticationInfo rmation.xid
Result of the enrollment check for Asia, Middle East, and Africa Gateway	consumerAuthenticationInfo rmation.veresEnrolled	consumerAuthenticationInfo rmation.veresEnrolled
3-D Secure version	consumerAuthenticationInfo rmation.specificationVersion	consumerAuthenticationInfo rmation.paSpecificationVersion
Directory server transaction ID	consumerAuthenticationInfo rmation.directoryServerTran sactionId	consumerAuthenticationInfo rmation.directoryServerTransactionId

Interpreting the Response

In EMV 3-D Secure, there are two possible responses:

Frictionless: No challenge or stepup to the cardholder. While frictionless authentication can indicate a successfully authenticated outcome because the customer's card is enrolled in a payer authentication program, it can also result from the bank failing or rejecting authentication without challenging the cardholder. In the frictionless authentication flow, you receive a PAResStatus of either

Y

,

A

,

N

,

I

,

R

, or

U

with an associated ECI value. With successful frictionless authentication, the PAResStatus =

Y

or

A

and you receive a CAVV. You may also receive a PAResStatus =

I

indicating successful authentication but it might not include a CAVV.

Challenge: The response contains PAResStatus =

C

. A challenge response has a payload and contains an ACS URL and a StepUpUrl. Challenge the cardholder to provide additional authentication information and display an authentication challenge window to the cardholder so the cardholder can respond to a validation request and receive a validation response.

Authenticating Enrolled Cards

In the response from the enrollment check service, confirm that you receive these fields and values:

3-D Secure version = 2.x

VERes enrolled = Y

PARes status = C

These values identify whether it is an EMV 3-D Secure 2.x transaction and that a challenge is required.

Once you validate these fields, you call Cardinal.cca_continue
(Android SDK) or Cardinal session continue
(iOS SDK) for the SDK to perform the challenge between the customer and the issuing bank.

Calling Cardinal.cca_continue (Android SDK)

When you have verified that a customer’s card is enrolled in a card authentication program, you must take the payload, and the

consumerAuthenticationInformation.authenticationTransactionId

response field and include them in the
Cardinal.cca_continue
function before proceeding with the authentication session as shown in this example.

/**
 * Cca continue.
 *
 * @param transactionId     the transaction id
 * @param payload           the payload
 * @param currentActivity   the current activity
 * @throws InvalidInputException        the invalid input exception
 * @throws JSONException                the json exception
 * @throws UnsupportedEncodingException the unsupported encoding exception
 */
try {
    cardinal.cca_continue("[TRANSACTION ID ]", "[PAYLOAD]", this, new CardinalValidateReceiver() {
           /**
            * This method is triggered when the transaction 
            * has been terminated. This is how SDK hands back
            * control to the merchant's application. This method will
            * include data on how the transaction attempt ended and
            * you should have your logic for reviewing the results of
            * the transaction and making decisions regarding next steps.
            * JWT will be empty if validate was not successful.
            *
            * @param validateResponse
            * @param serverJWT
            */
           @Override
           public void onValidated(Context currentContext, ValidateResponse validateResponse, String serverJWT) {
           }
       });
 }
catch (Exception e) {
   // Handle exception
 }

Calling Cardinal session continue (iOS SDK)

When you have verified that a customer’s card is enrolled in a card authentication program, take the payload, and the response field and include them in the Cardinal session continue
function before proceeding with the authentication session

as shown in Example 22

.

In Continue, you should pass a class conforming to a protocol CardinalValidationDelegate
(and implement a method stepUpDidValidate
) as a parameter. These examples show a class conforming to CardinalValidationDelegate
protocol.

Objective-C Examples

Cardinal session continue (iOS SDK - Objective-C)

@interface YourViewController()<CardinalValidationDelegate>{ //Conform your ViewController or any other class to CardinalValidationDelegate protocol
   
}
@end
  
@implementation YourViewController
  
    /**
     * This method is triggered when the transaction has 
     * been terminated.This is how SDK hands back
     * control to the merchant's application. This method will
     * include data on how the transaction attempt ended and
     * you should have your logic for reviewing the results of
     * the transaction and making decisions regarding next steps.
     * JWT will be empty if validate was not successful
     *
     * @param session
     * @param validateResponse
     * @param serverJWT
     */
    -(void)cardinalSession:(CardinalSession *)session stepUpDidValidateWithResponse:(CardinalResponse *)validateResponse serverJWT:(NSString *)serverJWT{
       
    }
  
@end

If Continue
is called in the same class, call the method shown in the following example to start StepUpFlow
.

Cardinal.continue Call in the Same Class (Objective-C)

[session continueWithTransactionId: @"[TRANSACTION_ID]"
                           payload: @"[PAYLOAD]"
               didValidateDelegate: self];

Swift Examples

Cardinal session continue (iOS SDK - Swift)

class YourViewController:CardinalValidationDelegate {
  
    /**
     * This method is triggered when the transaction has been 
     * terminated.This is how SDK hands back
     * control to the merchant's application. This method will
     * include data on how the transaction attempt ended and
     * you should have your logic for reviewing the results of
     * the transaction and making decisions regarding next steps.
     * JWT will be empty if validate was not successful
     *
     * @param session
     * @param validateResponse
     * @param serverJWT
     */
    func cardinalSession(cardinalSession session: CardinalSession!, stepUpValidated validateResponse: CardinalResponse!, serverJWT: String!) {
        
    }
 
}

If Continue
is called in the same class, call the method shown in the example below to start StepUpFlow
.

Cardinal.continue Call in the Same Class (Swift)

session.continueWith(transactionId: "[TRANSACTION_ID]", payload: "[PAYLOAD]", validationDelegate: self)

When necessary, the SDK displays the authentication window and the customer enters their authentication information.

Receiving the Authentication Results

Next onValidated()
(Android SDK) or stepUpDidValidate
(iOS SDK) launches and returns the authentication results and response JWT along with the processor transaction ID as shown in this example.

Decoded Response JWT

{
  "iss": "5a4504be6fe3d1127cdfd94e",
  "iat": 1555075930,
  "exp": 1555083130,
  "jti": "cc532159-636d-4fa8-931d-d4b0f4c83b99",
  "ConsumerSessionId": "0_9a16b7f5-8b94-480d-bf92-09cd302c9230",
  "aud": "d0cf3392-62c5-4107-bf6a-8fc3bb49922b",
  "Payload": {
    "Payment": {
      "Type": "CCA",
      "ProcessorTransactionId": "YGSaOBivyG0dzCFs2Zv0"
    },
    "ErrorNumber": 0,
    "ErrorDescription": "Success"
  }
}

Requesting the Validation Service

For enrolled cards, the next step is to make a back-end, server-to-server call to request the validation service.

When you make the validation request, you must:

Send the

consumerAuthenticationInformation.authenticationTransactionId

request field.

Send the credit card information including the PAN, currency, and expiration date (month and year).

The response that you receive contains the validation result.

It is recommended that you request the payer authentication and card authorization services at the same time. Doing this automatically sends the correct information to your payment processor and converts the values of these fields to the proper format required by your payment processor:

consumerAuthenticationInformation.ecommerceIndicator

consumerAuthenticationInformation.cavv

consumerAuthenticationInformation.ucafAuthenticationData

consumerAuthenticationInformation.xid

and

consumerAuthenticationInformation.xid

If you request the services separately, manually include the validation result values (Validation Check response fields) in the authorization service request (Card Authorization request fields). To receive liability shift protection, you must ensure that you pass all pertinent data for the card type and processor in your request. Failure to do so might invalidate your liability shift for that transaction. Include the electronic commerce indicator (ECI), the transaction ID (XID), the 3-D Secure version, the directory server transaction ID, and this card-specific information in your authorization request.

For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo, include the CAVV.

For Mastercard only, include the collection indicator and the AAV (also known as UCAF).

Validation Check and Response Fields
Identifier	Validation Check Response Field	Card Authorization Request Field
E-commerce indicator	consumerAuthenticationInformation.indicator	processingInformation.commerceIndicator
Collection indicator	consumerAuthenticationInforma tion.ucafCollectionIndicator	consumerAuthenticationInfo rmation.ucafCollectionIndicator
CAVV	consumerAuthenticationInformation.cavv	consumerAuthenticationInformation.cavv
AAV	consumerAuthenticationInforma tion.ucafAuthenticationData	consumerAuthenticationInfo rmation.ucafAuthenticationData
XID	consumerAuthenticationInformation.xid	consumerAuthenticationInformation.xid
3-D Secure version	consumerAuthenticationInforma tion.specificationVersion	consumerAuthenticationInfo rmation.paSpecificationVersion
Directory server transaction ID	consumerAuthenticationInforma tion.directoryServerTransactionId	consumerAuthenticationInfo rmation.directoryServerTransactionId

Interpreting the Response

IMPORTANT

If the authentication fails, Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo require that you not accept the card. Instead, you must ask the customer to use another payment method.

Proceed with the order according to the validation response received. The responses are similar for all card types:

Success: You receive

AUTHENTICATION_SUCCESSFUL

, and other service requests, including authorization, are processed normally.

Failure: You receive

AUTHENTICATION_FAILED

, so the other services in your request are not processed.

Error: If you receive an error from the payment card company, process the order according to your business rules. If the error occurs frequently, report it to customer support. If you receive a system error, determine the cause, and proceed with card authorization only if appropriate.

To verify that the enrollment and validation checks are for the same transaction, ensure that the XID in the enrollment check and validation responses are identical.

Redirecting Customers to the Message Page

After authentication is complete, redirect the customer to a page containing a success or failure message. Ensure that all messages that display to customers are accurate, complete, and address all possible scenarios for enrolled and non-enrolled cards. For example, if the authentication fails, display a message such as this to the customer:

Authentication Failed
Your card issuer cannot authenticate this card. Please select another card or form of payment to complete your purchase.

Running Payer Authentication with SDK

Requesting the Check Enrollment Service (SDK)

Interpreting the Response

Authenticating Enrolled Cards

Calling Cardinal.cca_continue (Android SDK)

Calling Cardinal session continue (iOS SDK)

Objective-C Examples

Swift Examples

Receiving the Authentication Results

Requesting the Validation Service

Interpreting the Response

Redirecting Customers to the Message Page