Implementing SDK Payer Authentication

Requesting the Check Enrollment Service (SDK)

After the SDK completes the device collection from your mobile application and once the customer clicks the ‘buy now’ 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 following fields are required:

namount or grand_total_amount

nbill_address1

nbill_city

nbill_country

nbill_state

nbill_zip

ncard_type

ncurrency

ncustomer_cc_expmo

ncustomer_cc_expyr

ncustomer_cc_number

ncustomer_email

ncustomer_firstname

ncustomer_lastname

nics_applications

nmerchant_id

nmerchant_ref_number

npa_reference_id

For further details on required and optional fields, see Request-Level Fields.

You can use the enrollment check and card authorization services in the same request or in separate requests:

nSame 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 in order to prove that you attempted to check enrollment are passed automatically to the authorization service. If authentication is required, processing automatically stops.

nSeparate requests: you must manually include the enrollment check result values (Enrollment Check Response Fields) in the authorization service request (Card Authorization Request Fields).

Table 8 lists these fields.

Interpreting the Response

The responses are similar for all card types. See Request and Response Examples for examples of enrollment responses.

nEnrolled Cards

You receive response flag DAUTHENTICATE if the customer’s card is enrolled in a payer authentication program. When you receive this response, you can proceed to validate authentication.

nCards Not Enrolled 

You receive response flag SOK in the following cases:

lWhen the account number is not enrolled in a payer authentication program. The other services in your request are processed normally.

lWhen payer authentication is not supported by the card type.

When you receive this response, you can proceed to card authorization.

Authenticating Enrolled Cards

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

n3D Secure version = 2.x 

nVERes enrolled = Y

nPARes status = C

These values identify whether it is a 2.x transaction and that a challenge is required. If the 3D Secure version is 1.0, then the SDK is no longer applicable and you must open up a WebView.

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

Call 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 pa_enroll_authentication_transaction_id response field and include them in the Cardinal.cca_continue function in order to proceed with the authentication session as shown in Example 21   .

Example 21Cardinal.cca_continue (Android SDK)

Call Cardinal session continue (iOS SDK)

When you have verified that a customer’s card is enrolled in a card authentication program, you must take the payload, and the pa_enroll_authentication_transaction_id response field and include them in the Cardinal session continue function in order to proceed 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. Example 22    or Example 24    show an example of class conforming to CardinalValidationDelegate protocol.

Objective-C Examples

Example 22Cardinal session continue (iOS SDK - Objective-C)

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

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

Swift Examples

Example 24Cardinal session continue (iOS SDK - Swift)

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

Example 25Cardinal.continue Call in the Same Class (Swift)

The SDK displays the authentication window if necessary 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 Example 26   .

Example 26Decoded Response JWT

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:

nSend the pa_authentication_transaction_id request field

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

The response that you receive contains the validation result.

Cybersource recommends that you request both payer authentication and card authorization services at the same time. When you do so, Cybersource automatically sends the correct information to your payment processor; Cybersource converts the values of these fields to the proper format required by your payment processor:

nE-commerce indicator: pa_enroll_e_commerce_indicator

nCAVV: pa_validate_cavv

nAAV: pa_validate_ucaf_authentication_data

nXID: pa_enroll_xid and pa_validate_xid

If you request the services separately, you must 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 may invalidate your liability shift for that transaction. Include the electronic commerce indicator (ECI), the transaction ID (XID), the 3D Secure version, the directory server transaction ID, and the following card-specific information in your authorization request:

nFor Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo include the CAVV (cardholder authentication verification value).

nFor Mastercard, include the UCAF (universal cardholder authentication field) and the collection indicator.

Table 9 lists these fields.

Interpreting the Response

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

nSuccess:

You receive the response flag SOK, and other service requests, including authorization, are processed normally.

nFailure:

You receive the response flag DAUTHENTICATIONFAILED, so the other services in your request are not processed.

nError:

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 Cybersource 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 Pass or Fail Message Page

After authentication is complete, redirect the customer to a page containing a success or failure message. You must ensure that all messages that display to customers are accurate, complete, and that they address all possible scenarios for enrolled and nonenrolled cards. For example, if the authentication fails, a message such as the following should be displayed to the customer:

Authentication Failed

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