Hybrid Payer Authentication
|
If you are using tokenization, use the Cardinal Cruise Direct Connection API integration method and Payer Authentication Setup service. |
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
lCall the ics_pa_enroll: Payer Authentication Enrollment Check service
lInvoke the authentication
lHandle declines
lCall the following services:
-ics_pa_validate: Payer Authentication Validation (only for Hybrid integration)
-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 Hybrid 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.
5You request the Enrollment Check service, passing in transaction details and the pa_reference_id request field.
6If the issuing bank does not require authentication, you receive the following information in the Enrollment Check response:
nE-commerce indicator
nCAVV (all card types except Mastercard)
nAAV (Mastercard only)
nTransaction ID
n3D Secure version
nDirectory server transaction ID
7If the issuing bank requires authentication, you receive a response with the ACS URL of the issuing bank, the payload, and the transaction ID that you include in the Cardinal.continue JavaScript call.
8The JavaScript displays the authentication window, and 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 Validate Authentication service, extracting the processor transaction ID value from the JWT and sending it in the pa_authentication_transaction_id request field. You receive the e-commerce indicator, CAVV or AAV, transaction ID, 3D Secure version, and directory 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 Validation Service .
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.
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 Hybrid integration uses JWTs as the method of authentication.
|
For security reasons, all JWT creation must be done on the server side. |
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.
{ "jti": "a5a59bfb-ac06-4c5f-be5c-351b64ae608e", "iat": 1448997865, "iss": "56560a358b946e0c8452365ds", "OrgUnitId": "565607c18b946e058463ds8r", "Payload": { "OrderDetails": { "OrderNumber": "0e5c5bf2-ea64-42e8-9ee1-71fff6522e15", "Amount": "1500", "CurrencyCode": "840" } }, "ObjectifyPayload": true, "ReferenceId": "c88b20c0-5047-11e6-8c35-8789b865ff15", "exp": 1449001465, } |
Example 45 shows the JSON content of a basic JWT payload that passes a string within the payload claim.
{ "jti": "29311a10-5048-11e6-8c35-8789b865ff15", "iat": 1448997875, "iss": "56560a358b946e0c8452365ds", "OrgUnitId": "565607c18b946e058463ds8r", "Payload": "{\"OrderDetails\":{\"OrderNumber\":\"19ec6910-5048-11e6-8c35-8789b865ff15\",\"Amount\":\"1500\",\"CurrencyCode\":\"840\"}}", "ObjectifyPayload" false "ReferenceId": "074fda80-5048-11e6-8c35-8789b865ff15" "exp":1449001465, } |
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 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 Hybrid Payer Authentication
Requesting the Check Enrollment Service (Hybrid)
Request the Check Enrollment service to verify that the card is enrolled in a card authentication program. 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. |
For further details on required and optional fields, see Request-Level Fields.
You can use the enrollment check and card authorization services in the same request or in separate requests:
nSame request: Cybersource attempts to authorize the card if your customer is not enrolled in a payer authentication program. 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 authentication is required, processing automatically stops.
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 37 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 response flag DAUTHENTICATE if the customer’s card is enrolled in a payer authentication program. When you receive this response, you can proceed to validate authentication.
nCards Not Enrolled
You receive response flag SOK in the following cases:
lWhen the account number is not enrolled in a payer authentication program. The other services in your request are processed normally.
lWhen payer authentication is not supported by the card type.
When you receive this response, you can proceed to card authorization.
When you have verified that a customer’s card is enrolled in a card authentication program, you must include the URL of the card-issuing bank’s Access Control Server (ACS), the payload, and the pa_enroll_authentication_transaction_id response field in the Cardinal.continue function in order to proceed with the authentication session as shown in Example 46 .
Cardinal.continue( { "AcsUrl":"https://testcustomer34.cardinalcommerce.com/merchantacsfrontend/pareq.jsp?vaa=b&gold=AAAAAAAA...AAAAAAA", "Payload":"eNpVUk1zgjAQvedXME7PJEFBVdKt1CECeDkVCk2PcfcnNjv8Kr+7tx4nlbGOcz/se6G1uMENPTPeeIz1G37WGEUth7YnpO21TfTvF3wDCBqspQ==" }, { "OrderDetails":{ "TransactionId" :"123456abc"
} } ); |
Cardinal.continue displays the authentication window if necessary and automatically redirects the customer’s session over to the ACS URL for authentication. The customer’s browser displays the authentication window with the option to enter their password.
Receiving the Authentication Results
Next, payments.validated launches, and returns the authentication results and response JWT along with the processor transaction ID as shown in Example 47 .
Example 47Decoded Response JWT
{ "iss": "5a4504be6fe3d1127cdfd94e", "iat": 1555075930, "exp": 1555083130, "jti": "cc532159-636d-4fa8-931d-d4b0f4c83b99", "ConsumerSessionId": "0_9a16b7f5-8b94-480d-bf92-09cd302c9230", "aud": "d0cf3392-62c5-4107-bf6a-8fc3bb49922b", "Payload": { "Payment": { "Type": "CCA", "ProcessorTransactionId": "YGSaOBivyG0dzCFs2Zv0" }, "ErrorNumber": 0, "ErrorDescription": "Success" } } |
Requesting the Validation Service
For enrolled cards, the next step is to request the validation service. When you make the validation request, you must:
nSend the pa_authentication_transaction_id request field
nSend the credit card information including the PAN, currency, and expiration date (month and year).
The response that you receive contains the validation result.
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 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 38 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 do 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 response flag SOK, and other service requests, including authorization, are processed normally.
nFailure:
You receive the response 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.