Hybrid Payer Authentication

Implementation Overview

Notify your Cybersource account representative that you want to implement payer authentication (3D Secure). Give them the Cybersource merchant ID that you will use for testing. For more information, see Required Merchant Information.

Implementation tasks include:

nAdd the JavaScript code to your checkout page

nFor each purchase request

lBuild the authentication request

lCall the ics_pa_enroll: Payer Authentication Enrollment Check service

lInvoke the authentication

lHandle declines

lCall the following services:

-ics_pa_validate: Payer Authentication Validation (only for Hybrid integration)

-ics_auth: Card Authorization service (optional)

nUse the test cases to test your preliminary code and make appropriate changes. You can change to the test environment by changing the URL in your JavaScript code. See Testing Payer Authentication Services.

nEnsure that your account is configured for production.

Process Flow for Hybrid Integration

1You generate a JSON Web Token (JWT).

2You add the JavaScript tag to your checkout page.

3Call Cardinal.setup().

4Run BIN detection. If the BIN is eligible for 3D Secure 2.x, it gathers the proper Method URL JavaScript required by the issuer to collect additional device data.

5You request the Enrollment Check service, passing in transaction details and the pa_reference_id request field.

6If the issuing bank does not require authentication, you receive the following information in the Enrollment Check response:

nE-commerce indicator

nCAVV (all card types except Mastercard)

nAAV (Mastercard only)

nTransaction ID

n3D Secure version

nDirectory server transaction ID

7If the issuing bank requires authentication, you receive a response with the ACS URL of the issuing bank, the payload, and the transaction ID that you include in the Cardinal.continue JavaScript call.

8The JavaScript displays the authentication window, and the customer enters the authentication information.

9The bank validates the customer credentials, and a JWT is returned that the merchant is required to validate server-side for security reasons.

10You request the Validate Authentication service, extracting the processor transaction ID value from the JWT and sending it in the pa_authentication_transaction_id request field. You receive the e-commerce indicator, CAVV or AAV, transaction ID, 3D Secure version, and directory server transaction ID.

Verify that the authentication was successful and continue processing your order.

You must pass all pertinent data for the card type and processor in your authorization request. For more information, see Requesting the Validation Service .

Before You Begin

Before you can implement payer authentication services, your business team must contact your acquirer and Cybersource to establish the service. Your software development team should become familiar with the API fields and technical details of this service.

Credentials/API Keys

API keys are required in order to create the JSON Web Token (JWT). For further information, contact Cybersource Customer Support.

Create the JSON Web Token (JWT)

The Hybrid integration uses JWTs as the method of authentication.

When creating the JWT, use your company API Key as the JWT secret. You can use any JTW library that supports JSON Web Signature (JWS). For further information about JWTs, see https://jwt.io/.

JWT Claims

Table 36    lists the standard claims that can be used in a JWT claim set.

JWT Examples

Example 44    shows the JSON content of a basic JWT payload that passes an object within the payload claim.

Example 44Raw JWT

Example 45    shows the JSON content of a basic JWT payload that passes a string within the payload claim.

Example 45Stringified JWT

Add the JavaScript

Add Songbird.js to your checkout page and complete the additional steps:

1Configure it: create the configuration object and pass it to Cardinal.configure().

2Listen for Events: subscribe to events with Cardinal.on() and set up callback functions for:

npayments.setupComplete: this optional event triggers when the JavaScript successfully initializes, after calling Cardinal.setup(). 

npayments.validated: this event triggers when the transaction completes.

3Initialize it: call Cardinal.setup() to trigger and pass your JWT to the JavaScript for each transaction.

To complete these steps, see the JavaScript Documentation.

BIN Detection

BIN detection is required and allows the card-issuing bank’s ACS provider to collect additional device data; it can help speed up the authentication process by collecting this data before the checkout page launches. This step occurs prior to authentication and must occur before the Cardinal.start event (Standard integration) or Check Enrollment service request (Hybrid integration). For further information, see the JavaScript Documentation.

Implementing Hybrid Payer Authentication

Requesting the Check Enrollment Service (Hybrid)

Request the Check Enrollment service to verify 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 37 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

When you have verified that a customer’s card is enrolled in a card authentication program, you must include the URL of the card-issuing bank’s Access Control Server (ACS), the payload, and the pa_enroll_authentication_transaction_id response field in the Cardinal.continue function in order to proceed with the authentication session as shown in Example 46   .

Example 46Cardinal.continue

Cardinal.continue displays the authentication window if necessary and automatically redirects the customer’s session over to the ACS URL for authentication. The customer’s browser displays the authentication window with the option to enter their password.

Receiving the Authentication Results

Next, payments.validated launches, and returns the authentication results and response JWT along with the processor transaction ID as shown in Example 47   .

Example 47Decoded Response JWT

Requesting the Validation Service

For enrolled cards, the next step is 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 38 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.