Standard 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

lInvoke the authentication

lHandle declines

lCall the following services:

-ics_pa_enroll: Payer Authentication Enrollment Check

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

5When the customer places an order on your website, you call the cardinal.start function to pass in the transaction level data including the full PAN and order details.

6The JavaScript verifies with the bank that the card is enrolled in a 3D Secure card authentication program by using a server-to-server call.

7If the issuing bank requires authentication, the JavaScript displays the authentication window.

8If required, 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 ICS Enrollment Check service, extracting the processor transaction ID value from the JWT and sending it in the pa_authentication_transaction_id request field. You receive this information:

nE-commerce indicator

nCAVV (all card types except Mastercard)

nAAV (Mastercard only)

nTransaction ID

n3D Secure version

nDirectory 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 Check Enrollment Service (Standard).

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 Standard 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 48Raw JWT

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

Example 49Stringified 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 Standard Payer Authentication

Starting Authentication

The JavaScript handles the device data collection, initiates the transaction for authentication, displays the authentication window if required, and returns the authentication results.

You initiate this authentication process, usually when the customer clicks the Place Order or Submit Order button, by triggering Cardinal.start(). Cardinal.start() invokes the authentication and authenticates the customer.

Create an order object to pass to the Cardinal.start() event. The more fields you include, the less likely the cardholder will be challenged to provide credentials.

Initiate Cardinal.start() before the authorization as shown in Example 50   . The second argument of data is a Request Order Object. You can construct this object ahead of time or pass it directly as shown.

Example 50Cardinal.start with Request Order Object

Payments.validated returns the authentication results and response JWT along with the processor transaction ID as shown in Example 51   .

Example 51Decoded Response JWT

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.

Requesting the Check Enrollment Service (Standard)

Once the validation is complete, use the Check Enrollment service to obtain the values needed for authorization.

To request the Check Enrollment service, extract the processor transaction ID value from the JWT and send it in the pa_authentication_transaction_id request field. The following fields are also 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.

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 enrollment check result values (Enrollment 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 40 lists these fields.

In most cases, you request card authorization only once for each purchase. However, you must send multiple authorization requests if the original authorization expires before it is captured, which can occur when order fulfillment is split or delayed. In these cases, you must include in subsequent authorization requests the same payer authentication data contained in the original request so that your acquiring bank can track all related requests if a dispute occurs. Authentication data can only be used for one authorization and cannot be used multiple times or on subsequent authorizations.