Home > Implementing Cardinal Cruise Direct Connection API Payer Authentication > Process Flow for Cardinal Cruise Direct Connection API


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 name=”ddc-iframe” height="10" width="10" style="display: none;">

</iframe>

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

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

<input type="hidden" name="JWT" value=" eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YWZiNGRkY2ZmNjI2YjIzNzA2OWZhM2QiLCJpYXQiOjE1OTExMTgyNzIsImV4cCI6MTU5MTEyNTQ3MiwianRpIjoiNWU4MDg5MGEtN2UyNi00ZmI3LThiYTUtNjQ2ZDU0NjJiMzBkIiwiUGF5bG9hZCI6eyJBY3Rpb25Db2RlIjoiU1VDQ0VTUyIsIlNlc3Npb25JZCI6IjY0ZTY2NjQ4LTFkYzYtNDZjMS1hNGYzLTBkYzE2MzQwZmFmMTAiLCJFcnJvck51bWJlciI6MCwiRXJyb3JEZXNjcmlwdGlvbiI6IlN1Y2Nlc3MifX0.j8EPWEEDf85hYQcxFzXxmHqHFTlptSQITJgfBGtLLjA" />

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

<script>

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

<script>

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

nbill_address1

nbill_city

nbill_country

nbill_state

nbill_zip

ncard_type

ncurrency

ncustomer_cc_expmo

ncustomer_cc_expyr

ncustomer_email

ncustomer_firstname

ncustomer_lastname

nics_applications

nmerchant_id

nmerchant_ref_number

npa_reference_id

npa_return_url

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

<iframe name=”step-up-iframe" height="400" width="400"></iframe>

<form id="step-up-form" target=”step-up-iframe" method="post" action=" https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp"> <input type="hidden" name="JWT" value="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJmNmFmMTRmOS04YWRjLTRiNzktOGVkYS04YWVlMTI2NTkzZTEiLCJpYXQiOjE1OTYwNTEyNzYsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5NjA1NDg3NiwiT3JnVW5pdElkIjoiNTVlZjNmNTZmNzIzYWE0MzFjOTlkNTRiIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUpsTkdKaVpqazNNeTFqTW1FeUxUUTNOREF0T1RWak5DMWpNVGhoTVRNeE16TmlPRFFpTENKaFkzTlVjbUZ1YzBsRUlqb2lNVGMzT0RFM016SXROREk1TVMwME1HUmlMVGxoTkRndE1ESm1OREpoTlRZd1lqYzVJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiQnh5a0hYVEp4M1JuNHBGWnF1bjAifSwiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9taWNoYWVsdGF5bG9yLmlvL2N5YnMvc3RvcmVEZW1vL3B1YmxpYy9saXN0ZW5lci5weSJ9.H8j-VYCJK_7ZEHxGz82_IwZGKBODzPaceJNNC99xZRo" /> <input type="hidden" name="MD" value="optionally_include_custom_data_that_will_be_returned_as_is”/> </form>

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

<script>

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.