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.
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.
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 .
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.
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.
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:
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.
For further details on required and optional fields, see API Fields.
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.
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.
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.
For further details on required and optional fields, see API Fields.
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.
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.
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> |
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.
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.
npa_authentication_transaction_id field is mapped from the pa_enroll_authentication_transaction_id field in Step 4: Step-Up IFrame.
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.
Identifier |
Validation Check Response Field |
Card Authorization Request Field |
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 |
pa_validate_ucaf_authentication_data |
ucaf_authentication_data |
|
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 |
|
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.