Process Flow for Cardinal Cruise Direct Connection API

Step 1: Payer Authentication Setup Service

The Payer Authentication Setup service is called on the server side after the customer enters their payment information. Request the Payer Authentication Setup service separately without including other Cybersource services.

Request Fields

To request the Payer Authentication Setup service, you must send the customer’s card number, encrypted payment data, transient token, or TMS token for digital wallet transactions, in addition to other fields. The request fields may include:

ncustomer_cc_number

nencrypted_payment_data

nencrypted_payment_descriptor

nsubscription_id

ntransient_token

The card_type field is required when card type is Cartes Bancaires.

Important Response Fields

npa_access_token is used in Step 2: Device Data Collection Iframe .

npa_setup_pa_device_data_collection_url is used in Step 2: Device Data Collection Iframe .

npa_setup_pa_reference_id is used in Step 3: Payer Authentication Check Enrollment Service .

Field Definitions and Details

For further details on required and optional fields, see API Fields.

Request and Response API Examples

For further details on examples, see Request and Response Examples.

Step 2: Device Data Collection Iframe

Device Data Collection is initiated on the front end after you receive the server-side Payer Authentication Setup service response as described in Step 1: Payer Authentication Setup Service and pass pa_access_token to the front end.

The hidden 10x10 pixel iframe is rendered to the browser in order to profile the customer device. The response depends on the card-issuing bank and can take 3 to 5 seconds. If you proceed with the check enrollment service as described in Step 3: Payer Authentication Check Enrollment Service before a response is received, Cybersource will fall back to 3D Secure 1.0.

Building the Iframe

Iframe Parameters

nForm POST Action: The URL posted to the iframe is from the pa_setup_pa_device_data_collection_url response field discussed in Step 1: Payer Authentication Setup Service.

nJWT POST Parameter: Use the value from the pa_access_token response field discussed in Step 1: Payer Authentication Setup Service.

Initiate the Device Data Collection Iframe

Initiate a form POST in a hidden iframe and send to the device data collection URL. See Example 1 .

Place the following HTML anywhere inside the <body> element of the checkout page. Note that you must dynamically replace the value of the form action attribute and JWT POST parameter with the response values discussed in Step 1: Payer Authentication Setup Service.

Example 1Initiate the Device Data Collection Iframe

</iframe>

<form id="ddc-form" target=”ddc-iframe” method="POST"

action="https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect">

</form>

Add JavaScript to Submit the Device Data Collection Iframe

Add JavaScript to invoke the iframe form POST. Place the JavaScript after the closing
</body> element as shown in Example 2 . The JavaScript invokes the iframe form POST automatically when the window loads. You may also choose to submit the form at a different time, but you must do it before requesting the check enrollment service.

Example 2JavaScript to Invoke the Iframe Form POST

window.onload = function() {

var ddcForm = document.querySelector(

if(ddcForm) // ddc form exists

ddcForm.submit();

}

</script>

Listen For the Device Data Collection URL Response

Receiving the response indicates that the device data collection URL has completed its processing. The response is an event callback that contains a message with the status of the device data collection process.

Note that the event.origin URL is variable depending on your environment:

nTest: https://centinelapistag.cardinalcommerce.com

nProduction: https://centinelapi.cardinalcommerce.com

See Example 3 to understand how to subscribe to the event and add JavaScript to receive the response from the device data collection iframe. Place the JavaScript after the closing </body> element.

Example 3Listen for Device Data Collection Response

window.addEventListener("message", (event) => {

//{MessageType: "profile.completed", Session Id: "0_57f063fd-659a-4779-b45b-9e456fdb7935", Status: true}

if (event.origin === "https://centinelapistag.cardinalcommerce.com") {

let data = JSON.parse(event.data);

console.log(

}

if (data !== undefined && data.Status) {

console.log(

}

}, false);

</script>

Example 4 shows a response payload from the event. None of the data returned must be stored for future use.

Example 4Event Listener Callback Payload

{

"MessageType": "profile.completed",

"Session Id": "f54ea591-51ac-48de-b908-eecf4ff6beff",

"Status": true

}

Step 3: Payer Authentication Check Enrollment Service

After device collection completes, request the Payer Authentication Check Enrollment service to determine if step-up authentication is needed.

Request Fields

npa_reference_id field is mapped from the pa_setup_pa_reference_id field as discussed in Step 1: Payer Authentication Setup Service.

npa_return_url is set to the URL to POST the results as discussed in Step 4: Step-Up IFrame.

To request the Payer Authentication Check Enrollment service, you must send the customer’s card number, encrypted payment data, transient token, or TMS token for digital wallet transactions. The request fields may include:

ncustomer_cc_number

nencrypted_payment_data

nencrypted_payment_descriptor

nsubscription_id

ntransient_token

The following fields are required:

namount or grand_total_amount

You can send additional request data in order to reduce your issuer step-up authentication rates. It is best to send all available fields. However, do not send dummy data if you do not have data for the field.

The size of the step-up iframe discussed in Step 4: Step-Up IFrame can vary depending on the 3D Secure version of the transaction (1.0 or 2.x ). For 3D Secure 2.x transactions, you can send the size of the challenge window in the pa_acs_window_size request field.

However, requesting a specific acsWindowSize does not guarantee this size. Parsing the PAReq as described in Step 4: Step-Up IFrame determines the actual size.

Field Definitions and Details

For further details on required and optional fields, see API Fields.

Combining Services

You can use the enrollment check and card authorization services in the same request or in separate requests. Using the same request is recommended.

nSame request: Cybersource attempts to authorize the card after authentication if step-up payer authentication is not required. 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 step-up authentication is required, processing stops to allow completion, and authorization is not called. This integration method is recommended.

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 2 lists these fields.

Table 2 Enrollment Check and Response Fields
Identifier	Enrollment Check Response Field	Card Authorization Request Field
E-commerce indicator	pa_enroll_e_commerce_indicator	e_commerce_indicator
Collection indicator (Mastercard only)	pa_enroll_ucaf_collection_indicator	ucaf_collection_indicator
Result of the enrollment check for Asia, Middle East, and Africa Gateway	pa_enroll_veres_enrolled	veres_enrolled
3D Secure version	pa_enroll_specification_version	pa_specification_version
Directory server transaction ID Note Not required for 3D Secure 1.0.	pa_enroll_directory_server_transaction_id	directory_server_transaction_id

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 reply flag DAUTHENTICATE if the customer’s card is enrolled in a payer authentication program. When you receive this response, further authentication steps are required. Proceed to Step 4: Step-Up IFrame.

nCards not enrolled, or step-up authentication not required

You receive reply flag SOK in the following cases:

lWhen the account number is not eligible for a payer authentication program or when step-up authentication is not required. The other services in your request are processed normally.

If you are making separate enrollment and authorization calls, you must include pertinent payer authentication data in the authorization request to receive liability shift protection.

lWhen payer authentication is not supported by the card type. When you receive this response, you can proceed to card authorization. If you receive the authentication results along with reply flag SOK, you receive liability shift protection.

Important Response Fields

If you receive reply flag DAUTHENTICATE, you also receive the following fields:

npa_step_up_url discussed in Step 4: Step-Up IFrame.

npa_access_token discussed in Step 4: Step-Up IFrame.

Field Definitions and Details

For further details on required and optional fields, see API Fields.

Step 4: Step-Up IFrame

Initiate step-up authentication on the front end after you receive the response as discussed in Step 3: Payer Authentication Check Enrollment Service . You only need to perform Step 4: Step-Up IFrame if Step 3 indicates step-up authentication is required.

The iframe manages customer interaction with the card-issuing bank’s Access Control Server (ACS) and 3D Secure version compatibility for 3D Secure 1.0 and 3D Secure 2.x.

Building the Iframe

Iframe Parameters

nForm POST Action: The URL posted by the iframe is from the pa_step_up_url response field discussed in Step 3: Payer Authentication Check Enrollment Service .

nJWT POST Parameter: Use the value from the pa_access_token response field discussed in Step 3: Payer Authentication Check Enrollment Service .

nMD POST Parameter: Merchant-defined data returned in the response. This field is optional.

nIframe height and width:

l3D Secure 1.0 uses a standard size of 400 by 400 pixels.

lFor 3D Secure 2.x:

-Use the pa_acs_window_size request field to request (but not guarantee) a specific window size.

-Use the pa_enroll_pareq response field to determine iframe dimensions by Base64 decoding the string and cross-referencing the challengeWindowSize value with the corresponding size.

Table 3 lists these values.

Table 3 Challenge Window Size Value and Corresponding Size
Challenge Window Size Value	Step-Up Iframe Dimensions (Width x Height)
01	250 x 400
02	390 x 400
03	500 x 600
04	600 x 400
05	Full screen

See Example 5 for the decoded value.

Example 5Challenge Window Size Decoded Value

{

"messageType":"CReq","messageVersion":"2.2.0",

"threeDSServerTransID":"c4b911d6-1f5c-40a4-bc2b-51986a98f991",

"acsTransID":"47956453-b477-4f02-a9ef-0ec3f9f779b3",

"challengeWindowSize":"02"

}

Create the Iframe

Create the iframe to send a POST request to the step-up URL. See Example 6 .

Example 6Send a POST Request to Step-Up URL

Add JavaScript to invoke the iframe form POST. Place the JavaScript after the closing
</body> tag (see Example 7 ). The JavaScript invokes the iframe form POST automatically when the window loads. You may also choose to submit the form at a different time, but you must do it before requesting the validation service.

Example 7JavaScript to Invoke the Iframe Form POST

window.onload = function() {

var stepUpForm = document.querySelector(

if(stepUpForm) // Step-Up form exists

stepUpForm.submit();

}

</script>

Receiving the Step-Up Results

After the customer interacts with the issuing bank, you get the session back through the pa_return_url response field specified in Step 3: Payer Authentication Check Enrollment Service . The payload sent to the return URL is URL-encoded and Base64-encoded (see Example 8 ).

The response sent back to the return URL contains the following:

nTransaction ID: (pa_enroll_authentication_transaction_id response field). This is used in Step 5: Payer Authentication Validation Service .

nMD: merchant data returned if present in the POST to step-up URL. Otherwise, null.

Example 8POST to Return URL

TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=null

Step 5: Payer Authentication Validation Service

When you receive the response as discussed in Step 4: Step-Up IFrame, make a validation call to verify that the customer successfully authenticated.

Request Fields

npa_authentication_transaction_id field is mapped from the pa_enroll_authentication_transaction_id field in Step 4: Step-Up IFrame.

Field Definitions and Details

For further details on required and optional fields, see API Fields.

Request and Response API Examples

For further details on examples, see Request and Response Examples.

Combining Services or Mapping Authorization 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 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 can 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.

Depending on your card type and whether it is a 3D Secure 1.0 or 2.x transaction, you might not receive the XID.

Table 4 lists these fields.

Table 4 Validation Check and Response Fields
Identifier	Validation Check Response Field	Card Authorization Request Field
E-commerce indicator	pa_validate_e_commerce_indicator	e_commerce_indicator
Collection indicator (Mastercard only)	pa_validate_ucaf_collection_indicator	ucaf_collection_indicator
CAVV (Visa and American Express only)	pa_validate_cavv	cavv
AAV (Mastercard only. Known as UCAF)	pa_validate_ucaf_authentication_data	ucaf_authentication_data
XID	pa_validate_xid	xid
3D Secure version	pa_validate_sepcification_version	pa_specification_version
Directory server transaction ID Note Not required for 3D Secure 1.0.	pa_validate_directory_server_transaction_id	directory_server_transaction_id

Interpreting the Response

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 that you receive. The responses are similar for all card types:

nSuccess:

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

nFailure:

You receive the reply 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.