CyberSource Storefront Reference Architecture

LINK Cartridge 3DS2.X - Developer Guide

Upgrading from Version 19.2.X to Version 19.3.0

1
Table of Contents
1. CyberSource Cartridge Overview....................................................................................................................2
2. Installation Guide.............................................................................................................................................2
3. Payer Authentication.......................................................................................................................................2
4. Change Logs....................................................................................................................................................5
5. Support French Processor................................................................................................................................9

1. CyberSource Cartridge Overview

NOTE: If you are integrating CyberSource with a controller or pipeline version of Site Genesis, please
disregard this document, and refer to the corresponding integration guide for your version of Site
Genesis.

The CyberSource package contains four cartridges.

1) A core cartridge (int_cybersource) that contains core API integrations, this includes:
i) The building and handling of API requests,
ii) Parsing responses into objects usable by the storefront.

2) Two legacy architecture cartridges (int_cybersource_pipelines, int_cybersource_controllers) each

i) contain sets of wrappers that connect the core code to their respective SFCC platforms.

3) From Version 18.1 and higher of the CyberSource cartridge package adds a fourth cartridge
(int_cybersource_sfra/ LINK_cybersource). This combines a modified version of the core code that
exists in the int_cybersource, along with the necessary hooks, extensions, and wrappers to connect this
code to the SFRA storefront. When integrating CyberSource with SFRA, you should only upload the
LINK_cybersource cartridge to your workspace and storefront. The remaining three cartridges are not
utilized in this integration and can be ignored. The following pages describe the high-level architecture
of the SFRA CS Architecture, along with details regarding specific Integrations.

2. Installation Guide
Refer Cartridge Integration guide (Cybersource Cartridge Integration SFRA vxx_x_x.docx) included in
the cartridge for the detail steps to install the cartridge.

3. Payer Authentication

Integration Overview

2
 The CyberSource LINK Cartridge 19.3.0 provides support for the latest 3D Secure 2.x specification.
Upgrading your Payer Authentication integration from the legacy 3D Secure 1.0 specification to 2.x will
allow for better authentication rates from issuers and meet PSD2 regulatory requirements for Strong
Customer Authentication (SCA) in Europe.

The following is a high-level architectural diagram of how the Payer Authentication integration works:

3
Implementation for upgrade to 3DS2.x
To enable Payer Authentication services on SFRA, ensure you have followed all steps in the "
Cybersource Cartridge Integration SFRA vXX_X_X" guide.

Prerequisite Please contact your Cybersource Representative to sign up and receive your Payer
Authentication credentials.

Step 1. Import ‘int_cybersource_sfra/configuration/CS SFRA PaymentMethods vXX_X.xml’,

‘configuration/PayerAuth-Meta.xml’ into your sandbox.
Step 2. Login to SFCC’s Business Manager and go to 'Merchant Tools > Ordering > Payment Methods'.
Make sure the 'CREDIT_CARD' payment method is enabled and configured to use the
CYBERSOURCE_CREDIT payment processor.

Step 3. On the same page, select 'Credit/Debit cards' and check the payer authentication checkbox on
any credit card types you want to support Payer Authentication.

4
 Step 4. Go to 'Merchant Tools > Custom Preferences > CyberSource Core in Business Manager, fill
following Preferences.

Site Preference Group: CyberSource Core

Preference Name Usage
CS PA Merchant ID Payer Auth merchant ID
CS PA Save Proof.xml To enable/disable saving of proof.xml in order object
CS PA Save ParesStatus Default False
Save ParesStatus received as response from Pa Authenticate
request and send it as param in ccAuth request call. This field
should be enabled after verifying cybersource merchant account
settings

Step 5. Go to 'Merchant Tools > Custom Preferences > CruiseCredentials in Business Manager, fill
following Preferences.

Site Preference Group: CruiseCredentials

Preference Name Usage
CruiseApiKey A shared secret value between the merchant and Cardinal. This
value should never be exposed to the public.
CruiseApiIdentifier GUID used to identify the specific API Key
CruiseMerchantName Merchant Name
CruiseOrgUnitId GUID to identify the merchant organization within Cardinal systems
CardinalCruiseApiPath Songbird.js script API path

Test Cases for 3D Secure 2.x

https://developer.cybersource.com/library/documentation/dev_guides/Payer_Authentication_SO_API/html/
Topics/Test_Cases_for_3D_Secure_2_x.htm

4. Change Logs

Ac File Name Description

ti
on
int_cybersource_sfra/cartridges/LINK_cybersource/ Removed inclusion of "secureAcceptance" in
M cartridge/client/default/js/checkout.js document.ready
int_cybersource_sfra/cartridges/LINK_cybersource/ changed existing logic for appending class to
cartridge/client/default/js/checkout/billing.js 'submit-order' id element based on payment
M instrument
D int_cybersource_sfra/cartridges/LINK_cybersource/ removed as existing logic moved to
cartridge/client/default/js/checkout/cybersource/ cybersource-custom.js with some
5
 secureAcceptance.js modifications.
Begin method modified to send paymentClass
int_cybersource_sfra/cartridges/LINK_cybersource/ required for submit-order button based on
M cartridge/controllers/Checkout.js the paymentInstrument
1.SilentPostAuthorize method is added to
handle authorization of SA SilentPost.
2.In PlaceOrder method DFReferenceId
returned by cardinal commerce script after
initialization from httpParameterMap is set to
session.privacy.DFReferenceId and if
conditions for handling authorized status for
payer authentication flow.
3. InitPayerAuth method is added which
initializes the data like order object , JWT
token for cardinal commerce script
initialization.
4.PayerAuthentication controller method
updated for sending order object , JWT token,
authenticationTransactionId which are
int_cybersource_sfra/cartridges/LINK_cybersource/ responsible for populating the new 3DS 2.0
M cartridge/controllers/CheckoutServices.js popup.
Adding processorTransactionId returned by
int_cybersource_sfra/cartridges/LINK_cybersource/ cardinal commerce script to
M cartridge/controllers/COPlaceOrder.js session.privacy.processorTransactionId object
int_cybersource_sfra/cartridges/LINK_cybersource/ prototype object which is useful for creating
A cartridge/scripts/cardinal/AccountObject.ds order Object which is passed to cardinal script
int_cybersource_sfra/cartridges/LINK_cybersource/
cartridge/scripts/cardinal/ prototype object which is useful for creating
A Billing_Shipping_AddressObject.ds order Object which is passed to cardinal script
int_cybersource_sfra/cartridges/LINK_cybersource/ contains functions which are used to create
A cartridge/scripts/cardinal/CardinalUtils.ds order Object which is passed to cardinal script
int_cybersource_sfra/cartridges/LINK_cybersource/ prototype object which is useful for creating
A cartridge/scripts/cardinal/CartItemObject.ds order Object which is passed to cardinal script
int_cybersource_sfra/cartridges/LINK_cybersource/ prototype object which is useful for creating
A cartridge/scripts/cardinal/ConsumerObject.ds order Object which is passed to cardinal script
int_cybersource_sfra/cartridges/LINK_cybersource/ contains functions which create JWT Tokens
A cartridge/scripts/cardinal/JWTBuilder.ds required for cardinal script initialization
int_cybersource_sfra/cartridges/LINK_cybersource/ prototype object which is useful for creating
A cartridge/scripts/cardinal/OrderDetailsObject.ds order Object which is passed to cardinal script
int_cybersource_sfra/cartridges/LINK_cybersource/ prototype object which is useful for creating
A cartridge/scripts/cardinal/OrderObject.ds order Object which is passed to cardinal script
int_cybersource_sfra/cartridges/LINK_cybersource/ prototype object which is useful for creating
A cartridge/scripts/cardinal/TokenObject.ds order Object which is passed to cardinal script
functional methods added to handle new 3ds
int_cybersource_sfra/cartridges/LINK_cybersource/ updates for Secure Acceptance Silent Post
M cartridge/scripts/checkout/checkoutHelpers.js Authorization

6
 int_cybersource_sfra/cartridges/LINK_cybersource/
A cartridge/scripts/common/FindDeviceAgent.js script file added to return device type
1. getPartnerSolutionID changed to return
new one
2. methods added to get custompreference
values required for creating JWT Token
3. addPayerAuthEnrollInfo method modified
to add extra payerAuthEnrollService input
parameters
referenceID,mobilePhone,transactionMode.
4. addPayerAuthValidateInfo method
modified to add extra
payerAuthValidateService input parameter
authenticationTransactionID.
5. addPayerAuthReplyInfo method modified
to add paSpecificationVersion ,
directoryServerTransactionID input
parameters to ccAuthService request.
6. getTransactionMode method added to
int_cybersource_sfra/cartridges/LINK_cybersource/ return transactionmode value based on
M cartridge/scripts/cybersource/libCybersource.js device type.
1. CCAuthRequest method modified to pass
missing parameters required for
ccAuthService to addPayerAuthReplyInfo
method.
2. PayerAuthEnrollCheck modified to pass
phone number required for
payerauthenrollservice to
addPayerAuthEnrollInfo method and new
output parameters from
payerAuthEnrollReply
(authenticationTransactionID,specificationVer
sion,directoryServerTransactionID,CAVV,UCA
FAuthenticationData) response are set to
responseObject.
3. In PayerAuthValidation method, null check
is added for PaRes value and new output
parameters from payerAuthValidateReply
response
int_cybersource_sfra/cartridges/LINK_cybersource/ (specificationVersion,directoryServerTransacti
M cartridge/scripts/façade/CardFacade.ds onID) are set to responseObject.
addOrUpdateToken method added to call
addorupdatetoken service which is inluded in
int_cybersource_sfra/cartridges/LINK_cybersource/ CardResponse method replacing existing code
M cartridge/scripts/helper/CardHelper.js which calls addorupdatetoken service
M int_cybersource_sfra/cartridges/LINK_cybersource/ methods added to get transaction mode and
cartridge/scripts/helper/CommonHelper.js payment class added to submit-order button
7
 in review page
int_cybersource_sfra/cartridges/LINK_cybersource/ SilentPostAuthorize method added to
cartridge/scripts/hooks/payment/processor/ cybersource_credit payment processor for
M cybersource_credit.js Authorization of the cards.
In SilentPostResponse method 3DS updates
int_cybersource_sfra/cartridges/LINK_cybersource/ are added which includes setting orderNo to
cartridge/scripts/secureacceptance/adapter/ session.privacy.orderId and redirection to
M SecureAcceptanceAdapter.js CheckoutServices-InitPayerAuth service.
1. In CreateRequestData method
payment_token is added to
signed_field_names.
2. In AuthorizeCreditCard method,
authenticationTransactionID from payer
enroll service
int_cybersource_sfra/cartridges/LINK_cybersource/ session.privacy.process3DRequestParent set
cartridge/scripts/secureacceptance/helper/ to true are forwarded for 3DS 2.0
M SecureAcceptnaceHelper.js Redirection .
1. In PayerAuthEnrollCCAuthRequest method
authenticationTransactionID from
payerAuthEnrollReply response is set to
responseObject required for cardinal script
continue function and transaction mode,
phone number are passed to
int_cybersource_sfra/cartridges/LINK_cybersource/ addPayerAuthEnrollInfo method.
cartridge/scripts/visacheckout/façade/ 2. Null check added for PaRes value in
M VisaCheckoutFacade.js PayerAuthValidationCCAuthRequest method.
authenticationTransactionID from
payerAuthEnrollservice is set to
int_cybersource_sfra/cartridges/LINK_cybersource/ session.privacy.authenticationTransactionID
cartridge/scripts/visacheckout/helper/ which is sent to cardinal commerce script for
M VisaCheckoutHelper.js initialization.
int_cybersource_sfra/cartridges/LINK_cybersource/
M cartridge/scripts/Cybersource.js empty check added for PAXID
int_cybersource_sfra/cartridges/LINK_cybersource/
cartridge/static/default/custom/js/cybersource- added onclick event listeners for all the
M custom.js payments configured to place an order.
int_cybersource_sfra/cartridges/LINK_cybersource/ changes done in client/default/js/checkout.js
M cartridge/static/default/js/checkout.js are reflected in this file after npm build
This isml contains script and required html
dom elements and cardinal events
int_cybersource_sfra/cartridges/LINK_cybersource/ configured for initialising the cardinal script
cartridge/templates/default/cart/ and cardinal continue function to start a
A cardinalpayerauthentication.isml transaction.
int_cybersource_sfra/cartridges/LINK_cybersource/
cartridge/templates/default/checkout/billing/
M paymentOptions/creditCardTab.isml empty line deleted

8
 adding class to submit-order button based on
int_cybersource_sfra/cartridges/LINK_cybersource/ the payment choosen and removed existing
M cartridge/templates/default/checkout/checkout.isml class place-order
int_cybersource_sfra/cartridges/LINK_cybersource/ This isml contains script and required html
cartridge/templates/default/payerauthentication/ dom elements and cardinal events
A songbird.isml configured for initialising the cardinal script.
int_cybersource_sfra/cartridges/LINK_cybersource/
cartridge/webreferences/ wsdl properties modified for updating the
M CyberSourceTransaction.wsdl cybersource endpoint.
int_cybersource_sfra/cartridges/LINK_cybersource/
cartridge/webreferences/ new XSD file for updated cybersource
A CyberSourceTransaction_1.155.xsd endpoint
A configuration/PayerAuth-Meta.xml

5. Support French Processor

To support French Processor, follow one of the below steps:

I. Install the latest Cybersource cartridge from Salesforce Marketplace – This is recommended
approach (OR)
II. Manually add below changes (SFCC’s GitHub commit) into your workspace code. It is always
recommended to test (both 3ds2 and 3ds1 test cards) the changes in your lower box before
promoting to Production org.
https://github.com/SalesforceCommerceCloud/link_cybersource/commit/
6f0b66980ce7e60ffb135b65b94d173fe6027c64
https://github.com/SalesforceCommerceCloud/link_cybersource/commit/
97d2fc51084bb9a88b66101e75b5bbc91329ba14
https://github.com/SalesforceCommerceCloud/link_cybersource/commit/
dc7dc3ef176673b1247b49d2f0e54fbe90d2be8b