Implementing Payer Authentication with the SDK

Request the Enrollment Check Service

After the SDK completes the device collection from your mobile application, and after the customer selects the Buy button, you must make a back-end, server-to-server request to 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

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

• Same request: 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 this card-specific information in your authorization request:

• For Visa, JCB, China UnionPay, Elo, Diners Club, Discover, and American Express include the CAVV.
• For Mastercard only, include the collection indicator and the AAV (also known as UCAF).

Enrollment Check and Response Fields

Interpret the Enrollment Response

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

• Frictionless: No challenge or step-up 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 might 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 step-up URL. 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.

Authenticate 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.

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

Call Cardinal.cca_continue (Android SDK)

After you verify that a customer's card is enrolled in a card authentication program, you must include the payload and the consumerAuthenticationInformation.authenticationTransactionId response field and incorporate them into the Cardinal.cca_continue function as shown in this example before proceeding with the authentication session.

/** * 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 }

Call Cardinal Session Continue (iOS SDK)

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

In the Cardinal session continue function, pass a class conforming to the CardinalValidationDelegate protocol (and implement the stepUpDidValidate method) as a parameter.

@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

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 the Cardinal.continue process is requested in the same class, request the method shown in these examples to start the step-up flow.

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

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

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

Receive Authentication Results

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

{  "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"  }}

Request the Validation Service

For enrolled cards, the next step is to make a back-end, server-to-server request for 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 so 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

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, JCB, China UnionPay, Elo, Diners Club, Discover, and American Express include the CAVV.
• For Mastercard only, include the collection indicator and the AAV (also known as UCAF).

Validation Check and Response Fields

Interpret the Validation Response

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.

Redirect 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 FailedYour card issuer cannot authenticate this card. Please select another card or form of payment to complete your purchase.