Cybersource Payer Authentication: Using The Simple Order API
Cybersource Payer Authentication: Using The Simple Order API
Cybersource Payer Authentication: Using The Simple Order API
Copyright
© 2021. Cybersource Corporation. All rights reserved. Cybersource Corporation ("Cybersource") furnishes this
document and the software described in this document under the applicable agreement between the reader of
this document ("You") and Cybersource ("Agreement"). You may use this document and/or software only in
accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information
contained in this document is subject to change without notice and therefore should not be interpreted in any way
as a guarantee or warranty by Cybersource. Cybersource assumes no responsibility or liability for any errors that
may appear in this document. The copyrighted software that accompanies this document is licensed to You for
use only in strict accordance with the Agreement. You should read the Agreement carefully before using the
software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this
document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical,
recording, or otherwise, without the prior written consent of Cybersource.
Trademarks
Authorize.Net, eCheck.Net, and The Power of Payment are registered trademarks of Cybersource Corporation.
Cybersource, Cybersource Payment Manager, Cybersource Risk Manager, Cybersource Decision Manager, and
Cybersource Connect are trademarks and/or service marks of Cybersource Corporation. Visa, Visa International,
Cybersource, the Visa logo, and the Cybersource logo are the registered trademarks of Visa International in the
United States and other countries. All other trademarks, service marks, registered marks, or registered service
marks are the property of their respective owners.
Version: 21.05
2
CONTENTS
Contents
Request Fields 24
Important Response Fields 24
Field Definitions and Details 24
Request and Response API Examples 25
Step 2: Device Data Collection Iframe 25
Building the Iframe 25
Step 3: Payer Authentication Check Enrollment Service 27
Request Fields 27
Field Definitions and Details 28
Combining Services 29
Interpreting the Response 29
Important Response Fields 30
Field Definitions and Details 30
Step 4: Step-Up IFrame 30
Building the Iframe 30
Receiving the Step-Up Results 32
Step 5: Payer Authentication Validation Service 33
Request Fields 33
Field Definitions and Details 33
Request and Response API Examples 33
Combining Services or Mapping Authorization Fields 33
Interpreting the Response 34
Redirecting Customers to Pass or Fail Message Page 35
<PARes> 224
<AuthInfo> 226
Examples 227
Failed Enrollment Check 227
Successful Authentication 228
Glossary 255
Release Changes
21.05 Updated the process to obtain credentials to generate your API keys for the Cardinal Mobile
SDK integration. See "Credentials/API Keys."
Updated "Test Case 38: American Express SafeKey Card Enrolled: Successful
Authentication" to fix a missing credit card digit.
Added note that XID is not returned for Mastercard transactions. See "Test Cases for 3D
Secure 2.x."
Updated "Test Case 2.8: Time-Out (Cruise Direct and Hybrid Only)" from PARes status = U
to VERes enrolled = U.
21.04 Updated the card_cardType field description to specify it is required for the Payer
Authentication Setup service when the card type is Cartes Bancaires.
Updated the length of the payerAuthEnrollService_sdkMaxTimeout field from 1 to 2.
Updated the size of the device data collection iframe to 10x10. See "Step 2: Device Data
Collection Iframe," page 25.
21.03 Added support for China UnionPay and Elo cards, including new test cases and updated API
fields. See "Elo Compra Segura," "China UnionPay," "Test Cases for 3D Secure 2.x," and
Appendix A, "API Fields," on page 147.
Added JCB, Elo, and China UnionPay card numbers to 2.x test cases. See "Test Cases for
3D Secure 2.x."
Updated the 2.x test cases to include all card types in a single set of test cases. See "Test
Cases for 3D Secure 2.x."
Updated the following field descriptions to specify required for China and add additional
information:
billTo_state
shipTo_state
Release Changes
21.02 Updated 3D Secure requestor ID and 3D Secure requestor name to be optional. See
"Required Merchant Information."
Added vbv_failure as a possible value along with internet for the e-commerce indicator for
1.0 Visa test cases 4, 7, 8, 10, and 11. See "Test Cases for 3D Secure 1.0."
Added card numbers for Cartes Bancaires Visa and Mastercard. See "Test Cases for 3D
Secure 2.x."
Updated the following field descriptions to specify they are not limited to Cartes Bancaires
transactions:
payerAuthEnrollService_merchantScore
payerAuthEnrollReply_authorizationPayload
payerAuthEnrollReply_effectiveAuthentication Type
payerAuthValidateReply_authorizationPayload
payerAuthValidateReply_effectiveAuthentication Type
Updated the length of following fields from 20 to 8 to match the EMV® Specifications.
payerAuthEnrollReply_specificationVersion
payerAuthValidateReply_specificationVersion
21.01 Reformatted all card numbers with line breaks and spacing. See Chapter 5, "Testing Payer
Authentication Services," on page 64.
Updated the following fields to change the data type from integer to string:
payerAuthEnrollReply_authenticationStatus Reason
payerAuthEnrollReply_challengeCancelCode
payerAuthEnrollReply_ networkScore
payerAuthValidateReply_authenticationStatus Reason
payerAuthValidateReply_challengeCancelCode
Updated the following field descriptions to remove required for transactions in Brazil:
payerAuthEnrollService_MCC
payerAuthEnrollService_mobilePhone
payerAuthEnrollService_overridePaymentMethod
payerAuthEnrollService_productCode
20.05 Revised Chapter 2, "Implementing Cardinal Cruise Direct Connection API Payer
Authentication," on page 23.
Added new request fields for the Payer Authentication Setup service:
payerAuthEnrollService_returnURL
payerAuthValidateService_responseAccessToken
Added new response fields for the Payer Authentication Setup service:
payerAuthEnrollReply_accessToken
payerAuthSetupReply_accessToken
Added new examples for the Payer Authentication Setup service and Cardinal Cruise Direct
Connection API. See Appendix C, "Request and Response Examples," on page 195.
Scope
This guide describes how to use the Simple Order API to integrate payer authentication
services with your order management system. It does not describe how to get started
using the Simple Order API nor does it explain how to use Cybersource services other
than payer authentication. For that information, see "Related Documents," page 15.
Conventions
Related Documents
Getting Started with Cybersource Advanced for the Simple Order API describes how
to get started using the Simple Order API. (PDF | HTML)
Decision Manager Developer Guide Using the Simple Order API describes how to
integrate Decision Manager, a fraud detection service, with your order management
system. (PDF | HTML)
Credit Card Services Using the Simple Order API describes how to integrate
Cybersource payment processing services into your business. (PDF | HTML)
Secure Acceptance Checkout API Integration Guide describes how to create Secure
Acceptance profiles, which enable you to integrate your order management system
with a website to process transactions. (PDF | HTML)
Reporting Developer Guide describes how to view and configure Business Center
reports. (PDF | HTML)
The Cybersource API Versions page provides information about the API versions.
Customer Support
For support information about any Cybersource service, visit the Support Center:
http://www.cybersource.com/support
Cybersource Payer Authentication services use JavaScript and the ICS services to
provide authentication.
Payer Authentication services enable you to add support to your web store for card
authentication services, including Visa SecureSM, Mastercard Identity Check®, Maestro®
(UK Domestic and international), American Express SafeKeySM, JCB J/Secure™, Diners
Club ProtectBuy, Discover ProtectBuy, China UnionPay, and Elo Compra Segura.
These card authentication services deter unauthorized card use and protect you from
fraudulent chargeback activity referred to as liability shift. However, Cybersource Payer
Authentication is not a fraud management service, such as Decision Manager with
Advanced Fraud Screen. Cybersource recommends that you implement a comprehensive
fraud management program in addition to payer authentication services.
You can use payer authentication services with specific payment processors. To find out if
your payment processor supports this feature, see the “Payer Authentication” section in
Credit Card Services Using the Simple Order API (PDF | HTML).
Chargebacks occur after a transaction is processed, and how they are handled varies
according to the region that issued the card. Payment card company rules might vary over
time and across geographical regions. Cybersource recommends that you contact your
merchant account provider to find out exactly how to interpret chargeback requirements
and which chargeback protections are offered.
PSD2
PSD2 (Payment Service Directive 2) is the new European regulatory framework that
governs payment processing and customer security and authentication. PSD2 establishes
a European Economic Area (EEA) single market for payments (including the UK even if
departed from the EEA) to encourage safer and more innovative payment services. PSD2
mandates Strong Customer Authentication (SCA) for all electronic payments. This
requirement affects the way merchants receive payments from customers and how
customers are authenticated. PSD2 stipulates that two-factor authentication be applied for
all electronic payments.
3D Secure 2.x
3D Secure 2.x is the authentication protocol provided by the card networks to support
SCA. To comply with SCA, merchants must deploy 3D Secure 2.x to their checkout page
or use a compliant hosted checkout.
Additional data can be passed in now and will be automatically sent to issuers as they
upgrade to 3D Secure 2.x. Cybersource Payer Authentication service is also backward-
compatible with 3D Secure 1.0.
If you are using tokenization, use the Cardinal Cruise Direct Connection API
integration method and Payer Authentication Setup service.
The Cardinal Cruise Direct Connection API is the recommended integration method.
If you are currently using 3D Secure 1.0, see Chapter 4, "Upgrading Your
Payer Authentication Implementation," on page 60.
You can also use Secure Acceptance to enable 3D Secure 2.x for payer authentication
services. For more information, see "Using Secure Acceptance with Payer
Authentication."
Step 1 Contact your Cybersource account manager or sales manager to learn more about 3D
Secure 2.x and PSD2.
Step 1 Contact your Cybersource account manager, sales manager, or technical account
manager to learn more about 3D Secure 2.x and PSD2.
Step 5 Configure your account for production. Repeat Steps 2-4 for the production environment.
Step 1 Contact your Cybersource account manager, sales manager, or technical account
manager to learn more about 3D Secure 2.x and PSD2.
Step 5 Configure your account for production. Repeat Steps 2-4 for the production environment.
For more information on implementing Secure Acceptance with payer authentication, see
the Secure Acceptance Hosted Checkout Integration Guide or Secure Acceptance
Checkout API Integration Guide.
You must provide the information listed in Table 1 to Cybersource before payer
authentication services can be enabled:
Information Description
About your company Your Cybersource merchant ID.
URL of your company’s website, for example:
http://www.example.com
Two-character ISO code for your country.
3D Secure requestor ID (optional)
3D Secure requestor name (optional)
Merchant category code
Bank information Name of your bank acquirer.
Complete name and address of your bank contact,
including email address.
Visa, Mastercard, Maestro, Information provided by your bank acquirer about each
American Express, JCB, Diners payment card company for which you are configured:
Club, Discover, China
6-digit BIN numbers.
UnionPay, and Elo information
Acquirer merchant ID: merchant ID assigned by your
Acquirer merchant ID
acquirer.
All currencies that you are set up to process.
The implementation still requires the use of JavaScript on the page, and it uses
CardinalCommerce JavaScript to leverage the authentication. However, the
CardinalCommerce JavaScript is hosted and contained in the iframe and does not directly
access your webpage.
Prerequisites
Notify your Cybersource account representative that you want to implement payer
authentication (3D Secure) using the Cardinal Cruise Direct Connection API. Give them
the Cybersource merchant ID that you will use for testing. For more information, see
"Required Merchant Information," page 22.
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.
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:
card_accountNumber
encryptedPayment_data
encryptedPayment_descriptor
recurringSubscriptionInfo_subscriptionID
tokenSource_transientToken
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
Form POST Action: The URL posted to the iframe is from the
payerAuthSetupReply_deviceDataCollectionURL response field discussed in
"Step 1: Payer Authentication Setup Service."
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."
<script>
window. {
var ddcForm = document.querySelector('#ddc-form');
if(ddcForm) // ddc form exists
ddcForm.submit();
}
</script>
Test: https://centinelapistag.cardinalcommerce.com
Production: 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.
<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('Merchant received a message:', data);
}
if (data !== undefined && data.Status) {
console.log('Songbird ran DF successfully');
}
}, false);
</script>
Example 4 shows a response payload from the event. None of the data returned must be
stored for future use.
{
"MessageType": "profile.completed",
"Session Id": "f54ea591-51ac-48de-b908-eecf4ff6beff",
"Status": true
}
Request Fields
payerAuthEnrollService_referenceID field is mapped from the payerAuthSetupReply_
referenceID field as discussed in "Step 1: Payer Authentication Setup Service."
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:
card_accountNumber
encryptedPayment_data
encryptedPayment_descriptor
recurringSubscriptionInfo_subscriptionID
tokenSource_transientToken
billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_cardType
card_expirationMonth
card_expirationYear
merchantID
merchantReference Code
payerAuthEnrollService_referenceID
payerAuthEnrollService_returnURL
payerAuthEnrollService_run
purchaseTotals_currency
purchaseTotals_grandTotalAmount
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 payerAuthEnrollService_
acsWindowSize 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.
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.
Separate requests: you must manually include the enrollment check result values
(Enrollment Check Response Fields) in the authorization service request (Card
Authorization Request Fields).
Enrolled cards
You receive reason code 475 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."
When 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.
When 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 reason code 100, you receive liability shift
protection.
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
Form POST Action: The URL posted by the iframe is from the
payerAuthEnrollReply_stepUpUrl response field discussed in "Step 3: Payer
Authentication Check Enrollment Service."
{
"messageType":"CReq","messageVersion":"2.2.0",
"threeDSServerTransID":"c4b911d6-1f5c-40a4-bc2b-51986a98f991",
"acsTransID":"47956453-b477-4f02-a9ef-0ec3f9f779b3",
"challengeWindowSize":"02"
}
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.
<script>
window. {
var stepUpForm = document.querySelector('# step-up-form');
if(stepUpForm) // Step-Up form exists
stepUpForm.submit();
}
</script>
The response sent back to the return URL contains the following:
MD: merchant data returned if present in the POST to step-up URL. Otherwise, null.
TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=null
Request Fields
payerAuthValidateService_authenticationTransactionID field is mapped from the
payerAuthEnrollReply_authenticationTransactionID field in "Step 4: Step-Up
IFrame."
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:
For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo
include the CAVV (cardholder authentication verification value).
For 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.
Proceed with the order according to the validation response that you receive. The
responses are similar for all card types:
Success:
You receive the reason code 100, and other service requests, including authorization,
are processed normally.
Failure:
You receive reason code 476 indicating that the authentication failed, so the other
services in your request are not processed.
Error:
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.
Authentication Failed
Your card issuer cannot authenticate this card. Please select another card
or form of payment to complete your purchase.
This chapter summarizes the process of integrating SDK Payer Authentication services
into your mobile application. Cybersource Payer Authentication services use the Cardinal
Mobile SDK for iOS or Android to facilitate the authentication.
The SDK is only designed to handle 2.x transactions. If a 1.0 transaction occurs, you must
include functionality to open up a WebView.
Implementation Overview
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," page 22.
Download, import, and configure the Cardinal Mobile SDK for either iOS or Android
Use the test cases to test your preliminary code and make appropriate changes. See
Chapter 5, "Testing Payer Authentication Services," on page 64.
2 Contact CardinalCommerce Customer Support for instructions to register for an API key.
3 Download and import the Cardinal Mobile SDK for either iOS or Android.
7 Create an API call to your merchant server to request the Enrollment Check service,
passing in transaction details and the payerAuthEnrollService_referenceID request
field.
8 If the issuing bank does not require authentication, you receive the following information in
the Enrollment Check response:
E-commerce indicator
CAVV (all card types except Mastercard)
AAV (Mastercard only)
Transaction ID
3D Secure version
Directory server transaction ID
9 If the issuing bank requires authentication, you receive a response with the payload, and
the transaction ID that you include in the Cardinal.continue call from your SDK.
10 The Cardinal Mobile SDK displays the authentication window, and the customer enters the
authentication information.
11 The bank validates the customer credentials and a JWT is returned by the SDK in the
onValidated callback that the merchant is required to validate server-side for security
reasons.
12 Create an API call to your merchant server to request the Validate Authentication service,
extracting the processor transaction ID value from the JWT and sending it in the
payerAuthValidateService_authenticationTransactionID 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," page 57.
Implementing the SDK in your mobile application requires either Android or iOS platform
application programming skills. Android API 19 or iOS 8 and XCode 8 are required.
Credentials/API Keys
API keys are required in order to create the JSON Web Token (JWT). To obtain
credentials to generate your API keys, contact Cybersource Customer Support.
You will receive an email with your user name and a temporary password. Your user name
will be in the following format:
Once your receive your credentials, log in to your JFrog account and update your
temporary password. Follow the process below to generate your API key.
Step 2 In the top-right of the JFrog Platform, select the Welcome drop-down menu and click Edit
Profile.
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 5 lists the standard claims that can be used in a JWT claim set.
Payload The JSON data object being sent. This object is usually an
order object.
Optional ReferenceId Merchant-supplied identifier that can be used to match up
data collected from the Cardinal Mobile SDK and
enrollment check service.
ObjectifyPayload Boolean flag that indicates how the API should consume
the payload claim. If set to true, the payload claim is an
object. If set to false, the payload claim is a stringified
object. Some JWT libraries do not support passing objects
as claims; this allows those who only allow strings to use
their libraries without customization.
JWT Examples
Example 9 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 10 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,
}
repositories {
...
maven {
url "https://cardinalcommerceprod.jfrog.io/artifactory/android"
credentials {
username ''//Artifactory username
password ''//Artifactory user API Key
}
}
}
dependencies {
...
//Cardinal Mobile SDK
implementation
'org.jfrog.cardinalcommerce.gradle:cardinalmobilesdk:2.2.5-1'
}
If your project uses Progurad, add the lines shown in Example 12 to the proguard-
rules.pro file.
Example 12 Progurad
Example 13 Cardinal.configure
cardinalConfigurationParameters.setEnvironment(CardinalEnvironment.STAG
ING);
cardinalConfigurationParameters.setTimeout(8000);
JSONArray rType = new JSONArray();
rType.put(CardinalRenderType.OTP);
rType.put(CardinalRenderType.SINGLE_SELECT);
rType.put(CardinalRenderType.MULTI_SELECT);
rType.put(CardinalRenderType.OOB);
rType.put(CardinalRenderType.HTML);
cardinalConfigurationParameters.setRenderType(rType);
cardinalConfigurationParameters.setUiType(CardinalUiType.BOTH);
cardinalConfigurationParameters.setUICustomization(yourUICustomizationO
bject);
cardinal.configure(this,cardinalConfigurationParameters);
}
cardinal = Cardinal.getInstance();
String serverJwt = "INSERT_YOUR_JWT_HERE";
cardinal.init(serverJwt ,
new CardinalInitService() {
/**
* You may have your Submit button disabled on page load. Once you are
* set up for CCA, you may then enable it. This will prevent users
* from submitting their order before CCA is ready.
*/
@Override
public void onSetupCompleted(String consumerSessionId) {
}
/**
* If there was an error with set up, Cardinal will call this function
* with validate response and empty serverJWT
* @param validateResponse
* @param serverJwt will be an empty
*/
@Override
public void onValidated(ValidateResponse validateResponse, String
serverJwt) {
}
});
See the "Implementing SDK Payer Authentication" section for next steps.
curl -L -u <USER_NAME>
:<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/
<VERSION>-<BUILD_NUMBER>/cardinalmobilesdk.zip
-o <LOCAL_FILE_NAME.EXT>
#Example:
curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/
artifactory/ios/2.2.5-1/cardinalmobilesdk.zip" -o cardinalmobile2.2.5-
1.zip
curl -L -u <USER_NAME>
:<API_KEY> https://cardinalcommerceprod.jfrog.io/artifactory/ios/
<VERSION>-<BUILD_NUMBER>/CardinalMobileiOSXC.zip
-o <LOCAL_FILE_NAME.EXT>
#Example:
curl -L -u UserName:ApiKey "https://cardinalcommerceprod.jfrog.io/
artifactory/ios/2.2.5-1/CardinalMobileiOSXC.zip" -o
cardinalmobile2.2.5-1.zip
In your XCode project, drag the CardinalMobile.framework file into the Frameworks group
in your Xcode Project. (Create the group if it doesn't already exist.) In the import dialog
box, check the box to Copy items into the destinations group folder (or Destination: Copy
items if needed). The iOS SDK files are now available for linking in your project.
Step 1 Open Xcode and choose your project in the source list to the left of the main editor area.
Step 2 Select your application under the Targets section and open the General tab.
Step 3 Expand the Embedded Binaries section and click the small plus (+) at the bottom of the
list.
Objective-C Example
Example 17 CardinalSession new (iOS SDK - Objective-C)
#import <CardinalMobile/CardinalMobile.h>
CardinalSession *session;
CardinalSessionRenderTypeArray *renderType =
[[CardinalSessionRenderTypeArray alloc] initWithObjects:
CardinalSessionRenderTypeOTP,
CardinalSessionRenderTypeHTML,
nil];
config.renderType = renderType;
config.enableQuickAuth = false;
[session configure:config];
}
Swift Example
Example 18 CardinalSession new (iOS SDK - Swift)
import CardinalMobile
config.renderType = [CardinalSessionRenderTypeOTP,
CardinalSessionRenderTypeHTML]
config.enableQuickAuth = true
session.configure(config)
}
Objective-C Example
Example 19 Cardinal session setup (iOS SDK - Objective-C)
[session setupWithJWT:jwtString
didComplete:^(NSString * _Nonnull consumerSessionId){
//
// You may have your Submit button disabled on page load. Once you are
// setup for CCA, you may then enable it. This will prevent users
// from submitting their order before CCA is ready.
//
} didValidate:^(CardinalResponse * _Nonnull validateResponse) {
// Handle failed setup
// If there was an error with setup, cardinal will call this
// function with validate response and empty serverJWT
}];
Swift Example
Example 20 Cardinal session setup (iOS SDK - Swift)
The Check Enrollment service verifies that the card is enrolled in a card authentication
program. The following fields are required:
billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_cardType
card_expirationMonth
card_expirationYear
merchantID
merchantReference Code
payerAuthEnrollService_referenceID
payerAuthEnrollService_run
purchaseTotals_currency
purchaseTotals_grandTotalAmount
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 Fields," page 149.
You can use the enrollment check and card authorization services in the same request or
in separate requests:
Same 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.
Separate requests: you must manually include the enrollment check result values
(Enrollment Check Response Fields) in the authorization service request (Card
Authorization Request Fields).
Enrolled Cards
You receive reason code 475 if the customer’s card is enrolled in a payer
authentication program. When you receive this response, you can proceed to validate
authentication.
When the account number is not enrolled in a payer authentication program. The
other services in your request are processed normally.
When payer authentication is not supported by the card type.
When you receive this response, you can proceed to card authorization.
These values identify whether it is a 2.x transaction and that a challenge is required. If the
3D Secure version is 1.0, then the SDK is no longer applicable and you must open up a
WebView.
Once you validate these fields, you call Cardinal.cca_continue (Android SDK) or Cardinal
session continue (iOS SDK) in order for the SDK to perform the challenge between the
customer and the issuing bank.
/**
* Cca continue.
*
* @param transactionId the transaction id
* @param payload the payload
* @param currentActivity the current activity
* @throws InvalidInputException the invalid input exception
* @throws JSONException the json exception
* @throws UnsupportedEncodingException the unsupported encoding
exception
*/
try {
cardinal.cca_continue("[TRANSACTION ID ]", "[PAYLOAD]", this, new
CardinalValidateReceiver() {
/**
* This method is triggered when the transaction
* has been terminated. This is how SDK hands back
* control to the merchant's application. This method will
* include data on how the transaction attempt ended and
* you should have your logic for reviewing the results of
* the transaction and making decisions regarding next steps.
* JWT will be empty if validate was not successful.
*
* @param validateResponse
* @param serverJWT
*/
@Override
public void onValidated(Context currentContext,
ValidateResponse validateResponse, String serverJWT) {
}
});
}
catch (Exception e) {
// Handle exception
}
Objective-C Examples
Example 22 Cardinal session continue (iOS SDK - Objective-C)
}
@end
@implementation YourViewController
/**
* This method is triggered when the transaction has
* been terminated.This is how SDK hands back
* control to the merchant's application. This method will
* include data on how the transaction attempt ended and
* you should have your logic for reviewing the results of
* the transaction and making decisions regarding next steps.
* JWT will be empty if validate was not successful
*
* @param session
* @param validateResponse
* @param serverJWT
*/
-(void)cardinalSession:(CardinalSession *)session
stepUpDidValidateWithResponse:(CardinalResponse *)validateResponse
serverJWT:(NSString *)serverJWT{
@end
If Continue is called in the same class, call the method shown in Example 23 to start
StepUpFlow.
Swift Examples
Example 24 Cardinal session continue (iOS SDK - Swift)
class YourViewController:CardinalValidationDelegate {
/**
* This method is triggered when the transaction has been
* terminated.This is how SDK hands back
* control to the merchant's application. This method will
* include data on how the transaction attempt ended and
* you should have your logic for reviewing the results of
* the transaction and making decisions regarding next steps.
* JWT will be empty if validate was not successful
*
* @param session
* @param validateResponse
* @param serverJWT
*/
func cardinalSession(cardinalSession session: CardinalSession!,
stepUpValidated validateResponse: CardinalResponse!, serverJWT: String!)
{
If Continue is called in the same class, call the method shown in Example 25 to start
StepUpFlow.
The SDK displays the authentication window if necessary and the customer enters their
authentication information.
{
"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"
}
}
Send the credit card information including the PAN, currency, and expiration date
(month and year).
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:
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:
For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo
include the CAVV (cardholder authentication verification value).
For Mastercard, include the UCAF (universal cardholder authentication field) and the
collection indicator.
Proceed with the order according to the validation response that you receive. The
responses are similar for all card types:
Success:
You receive the reason code 100, and other service requests, including authorization,
are processed normally.
Failure:
You receive reason code 476 indicating that the authentication failed, so the other
services in your request are not processed.
Error:
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.
Authentication Failed
Your card issuer cannot authenticate this card. Please select another card
or form of payment to complete your purchase.
Benefits
3D Secure 2.x provides the following benefits:
Easier to upgrade to 3D Secure 2.2 when it becomes available. Version 2.2 includes
support for exemptions for PSD2 which might allow frictionless authentication,
including acquirer/issuer transactional risk assessment; white listing; low value, one
leg out, and merchant-initiated transactions. These exemptions will be defined as they
become available.
PSD2 Impact
Upgrading to 3D Secure 2.x is necessary if you are affected by PSD2.
PSD2 means changes for all companies in Europe that deal with payments. It has
implications for merchants including:
Two-factor authentication will be required for all electronic payments, although there
are exemptions to allow a frictionless flow.
If you are impacted by PSD2 changes, it is very important that you upgrade to 3D Secure
2.x.
Mandates
PSD2 includes mandates around strong customer authentication (SCA) and exemptions
and challenges. See the following page for more information on the mandates:
https://demos.cardinalcommerce.com/3DS_Info/Country_Mandates/index.html
Timelines
See the following page for PSD2 compliance timelines:
https://demos.cardinalcommerce.com/3DS_Info/Cardinal_Timelines/index.html
Recommended Integration
Four types of integration are available for 3D Secure 2.x:
Cardinal Cruise Direct Connection API
SDK integration for your mobile application
Hybrid integration
Standard integration
If you are currently using Payer Authentication services in your existing business
processes and need to upgrade to 3D Secure 2.x, Cybersource recommends using the
Cardinal Cruise Direct Connection API integration.
The Cardinal Cruise Direct Connection API integration most closely resembles the current
process in which you request the Enrollment Check service to verify that the customer is
enrolled in one of the card authentication programs and receive a response. With 3D
Secure 2.x, the response includes a new value, the processor transaction ID.
For enrolled cards, include the ACS URL, payload, and processor transaction ID to
proceed with the authentication session.
Then request the validation service, sending the processor transaction ID with your
request, and receive a response with the e-commerce indicator and CAVV or AAV.
For more information about the Cardinal Cruise Direct Connection API, see Chapter 2,
Implementing Cardinal Cruise Direct Connection API Payer Authentication.
For details about the other integrations, see Chapter 3, Implementing SDK Payer
Authentication or Appendix H, Implementing Hybrid or Standard Payer Authentication.
If you are using tokenization, use the Cardinal Cruise Direct Connection API
integration method and Payer Authentication Setup service.
Migration FAQ
Q: Do I need to send in a new JWT for each transaction?
A: Yes, even though the JWT does not expire for two hours, you should send a new JWT
with each new transaction.
You can create a reference ID in the original JWT and then pass that same value for
the payerAuthEnrollService_referenceID request field for the Check Enrollment
service.
Payments.setupComplete returns a session ID and you can use that value for the
payerAuthEnrollService_referenceID request field for the Check Enrollment
service.
Q: When will the Payer Authentication reports include the new fields for 3D Secure 2.x?
A: Use the test cases ("Test Cases for 3D Secure 2.x," page 114) to test your preliminary
code and make the appropriate changes.
Q: How does 3D Secure 2.x authentication improve the experience for a customer who
uses a mobile or tablet device?
A: 3D Secure 2.x is agnostic to the device and you have control over the formatting of the
authentication form. 3D Secure 2.x also supports newer, more secure authentication
delivery tools, such as a one-time password (OTP) sent to a customer’s mobile device or
email.
After you have completed the necessary changes to your Web and API integration, verify
that all components are working correctly by performing all the tests for the cards that you
support. Each test contains the specific input data and the most important results fields
that you receive in the API response.
Testing Process
Use the card number specified in the test with the card’s expiration date set to the month
of December and the current year plus three. For example, for 2021, use 2024. You also
need the minimum required fields for an order.
Enrollment Check
For some of the enrolled cards, an authentication window appears after the enrollment
check completes.
To view the authentication window, you must enable your browser to display
popup windows.
The test password is always 1234.
If the user submits the password for the enrolled card, you receive the URL of the
Access Control Server (ACS) where the customer can be authenticated.
If the user clicks the Exit link and clicks OK in the verification window, authentication
does not occur.
Authentication Validation
Table 11 lists only the response fields used in the test cases.
Expected Results
These flowcharts summarize the payer authentication process based on the enrollment
status of the card and the subsequent customer experience with the authentication path.
Use this information with the test cases to determine how to process orders.
Figure 1 Authentication Path for Visa, American Express, JCB, Diners Club, Discover, China
UnionPay, and Elo
Visa Secure
You can use Payer Authentication services with 16- and 19-digit Visa cards if they are
supported by your processor.
Test Case 2: Visa Secure Card Enrolled: Successful Authentication but Invalid PARes
Test Case 6: Visa Secure Card Enrolled: Unsuccessful Authentication (Customer Exited)
Test Case 16: Mastercard Identity Check Card Enrolled: Successful Authentication
Test Case 17: Mastercard Identity Check Card Enrolled: Successful Authentication but Invalid
PARes
Test Case 18: Mastercard Identity Check Card Enrolled: Attempts Processing
Test Case 19: Mastercard Identity Check Card Enrolled: Incomplete Authentication
Test Case 19: Mastercard Identity Check Card Enrolled: Incomplete Authentication
Test Case 20: Mastercard Identity Check Card Enrolled: Unsuccessful Authentication
Test Case 21: Mastercard Identity Check Card Enrolled: Unsuccessful Authentication
(Customer Exited)
Test Case 21: Mastercard Identity Check Card Enrolled: Unsuccessful Authentication
(Customer Exited)
Test Case 22: Mastercard Identity Check Card Enrolled: Unavailable Authentication
Test Case 23: Mastercard Identity Check Card Enrolled: Authentication Error
Test Case 23: Mastercard Identity Check Card Enrolled: Authentication Error
Maestro
Test Case 30: Maestro Card Enrolled: Successful Authentication
Test Case 31: Maestro Card Enrolled: Successful Authentication but Invalid PARes
Test Case 38: American Express SafeKey Card Enrolled: Successful Authentication
Test Case 39: American Express SafeKey Card Enrolled: Successful Authentication but Invalid
PARes
Test Case 40: American Express SafeKey Card Enrolled: Attempts Processing
Test Case 41: American Express SafeKey Card Enrolled: Incomplete Authentication
Test Case 42: American Express SafeKey Card Enrolled: Unsuccessful Authentication
Test Case 43: American Express SafeKey Card Enrolled: Unavailable Authentication
Test Case 44: American Express SafeKey Card Enrolled: Authentication Error
JCB J/Secure
Table 15 Possible Values for JCB J/Secure Response Fields
Test Case 49: JCB J/Secure Card Enrolled: Successful Authentication but Invalid PARes
(Signature Failure)
Test Case 51: JCB J/Secure Card Enrolled: Incomplete Authentication (Unavailable)
Test Case 54: JCB J/Secure Card Enrolled: Authentication Error Processing PARes
Test Case 57: JCB J/Secure Enrollment Check: Lookup Error Processing Message Request
Test Case 58: Diners Club ProtectBuy Card Enrolled: Successful Authentication
Test Case 59: Diners Club ProtectBuy Card Enrolled: Successful Authentication but Invalid PARes
Test Case 60: Diners Club ProtectBuy Card Enrolled: Attempts Processing
Test Case 61: Diners Club ProtectBuy Card Enrolled: Incomplete Authentication
Test Case 62: Diners Club ProtectBuy Card Enrolled: Unsuccessful Authentication
Test Case 63: Diners Club ProtectBuy Card Enrolled: Unavailable Authentication
Test Case 64: Diners Club ProtectBuy Card Enrolled: Authentication Error
Discover ProtectBuy
Table 17 Possible Values for Discover ProtectBuy Response Fields
Test Case 69: Discover ProtectBuy Card Enrolled: Successful Authentication but Invalid PARes
China UnionPay
Table 19 Possible Values for China UnionPay Response Fields
XID values are included in 3D Secure 2.x test cases for legacy reasons. XID
is not returned for Mastercard transactions only.
The 3D Secure version and directory server transaction ID fields are returned
for the Check Enrollment and Validate Authentication services but are not
included in the 3D Secure 2.x test cases.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1005
CardType = 001
Visa 19-digit PAN 445653
00 0000 0001 007
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3001
CardType = 036
Mastercard 520000
00 0000 1005
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3001
CardType = 036
American Express 340000
00 0001 007
CardType = 003
Discover 601100
00 0000 1002
CardType = 004
Diners Club 601100
00 0000 1002
CardType = 005
JCB J/Secure 333700
00 0000 0008
CardType = 007
Elo 650505
00 0000 1000
CardType = 054
China UnionPay 620001
00 0020 0000
CardType = 062
Action
If you request Check Enrollment and authorization services separately, add the required
payer authentication values to your authorization request. If you request the Check
Enrollment and authorization services together, the process described above occurs
automatically.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1013
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3019
CardType = 036
Mastercard 520000
00 0000 1013
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3019
CardType = 036
American Express 340000
00 0001 015
CardType = 003
Discover 601100
00 0000 1010
CardType = 004
Diners Club 601100
00 0000 1010
CardType = 005
JCB J/Secure 333700
00 0000 0990
CardType = 007
Elo 650505
00 0000 1018
CardType = 054
China UnionPay 620001
00 0010 0010
CardType = 062
Action
It is not recommended to submit this transaction for authorization. Instead ask the
customer for another form of payment.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1021
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3027
CardType = 036
Mastercard 520000
00 0000 1021
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3027
CardType = 036
American Express 340000
00 0001 023
CardType = 003
Discover 601100
00 0000 1028
CardType = 004
Diners Club 601100
00 0000 1028
CardType = 005
JCB J/Secure 333700
00 0000 7045
CardType = 007
Elo 650505
00 0000 1026
CardType = 054
China UnionPay 620001
00 0000 0020
CardType = 062
Action
If you request Check Enrollment and authorization services separately, add the required
payer authentication values to your authorization request. If you request the Check
Enrollment and authorization services together, the process described above occurs
automatically.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1039
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3035
CardType = 036
Mastercard 520000
00 0000 1039
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3035
CardType = 036
American Express 340000
00 0001 031
CardType = 003
Discover 601100
00 0000 1036
CardType = 004
Diners Club 601100
00 0000 1036
CardType = 005
JCB J/Secure 333700
00 0000 0735
CardType = 007
Elo 650505
00 0000 1034
CardType = 054
China UnionPay 620001
00 0040 0030
CardType = 062
Action
Submit your authorization request. No liability shift.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1047
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3043
CardType = 036
Mastercard 520000
00 0000 1047
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3043
CardType = 036
American Express 340000
00 0001 049
CardType = 003
Discover 601100
00 0000 1044
CardType = 004
Diners Club 601100
00 0000 1044
CardType = 005
JCB J/Secure 333700
00 0000 0321
CardType = 007
Elo 650505
00 0000 1042
CardType = 054
China UnionPay 620001
00 0030 0040
CardType = 062
Action
You are not permitted to submit this transaction for authorization. Instead ask the
customer for another form of payment.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1054
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3050
CardType = 036
Mastercard 520000
00 0000 1054
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3050
CardType = 036
American Express 340000
00 0001 056
CardType = 003
Discover 601100
00 0000 1051
CardType = 004
Diners Club 601100
00 0000 1051
CardType = 005
JCB J/Secure 333700
00 0000 6765
CardType = 007
Elo 650505
00 0000 1059
CardType = 054
China UnionPay 620001
00 0060 0050
CardType = 062
Action
Submit your authorization request. No liability shift.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1062
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3068
CardType = 036
Mastercard 520000
00 0000 1062
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3068
CardType = 036
American Express 340000
00 0001 064
CardType = 003
Discover 601100
00 0000 1069
CardType = 004
Diners Club 601100
00 0000 1069
CardType = 005
JCB J/Secure 333700
00 0000 0016
CardType = 007
Elo 650505
00 0000 1067
CardType = 054
China UnionPay 620001
00 0050 0060
CardType = 062
Action
Proceed with the authorization request, and contact your support representative to resolve
the issue. No liability shift. If you requested payer authentication and authorization
together, the authorization is processed automatically.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1070
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3076
CardType = 036
Mastercard 520000
00 0000 1070
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3076
CardType = 036
American Express 340000
00 0001 072
CardType = 003
Discover 601100
00 0000 1077
CardType = 004
Diners Club 601100
00 0000 1077
CardType = 005
JCB J/Secure 333700
00 0000 0081
CardType = 007
Elo 650505
00 0000 1075
CardType = 054
China UnionPay 620001
00 0090 0070
CardType = 062
Action
After 10-12 seconds, proceed with the authorization request. No liability shift.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1088
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3084
CardType = 036
Mastercard 520000
00 0000 1088
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3084
CardType = 036
American Express 340000
00 0001 080
CardType = 003
Discover 601100
00 0000 1085
CardType = 004
Diners Club 601100
00 0000 1085
CardType = 005
JCB J/Secure 333700
00 0000 0537
CardType = 007
Elo 650505
00 0000 1083
CardType = 054
China UnionPay 620001
00 0080 0080
CardType = 062
Action
Submit your authorization request. No liability shift.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1096
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3134
CardType = 036
Mastercard 520000
00 0000 1096
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3092
CardType = 036
American Express 340000
00 0001 098
CardType = 003
Discover 601100
00 0000 1093
CardType = 004
Diners Club 601100
00 0000 1093
CardType = 005
JCB J/Secure 333700
00 0020 0004
CardType = 007
Elo 650505
00 0000 1091
CardType = 054
China UnionPay 620001
99 9980 0019
CardType = 062
Action
If you request Validate Authentication and authorization services separately, add the
required payer authentication values to your authorization request. If you request the
Validate Authentication and authorization services together, the process described above
occurs automatically.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1096
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3134
CardType = 036
Mastercard 520000
00 0000 1096
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3092
CardType = 036
American Express 340000
00 0001 098
CardType = 003
Discover 601100
00 0000 1093
CardType = 004
Diners Club 601100
00 0000 1093
CardType = 005
JCB J/Secure 333700
00 0020 0004
CardType = 007
Elo 650505
00 0000 1091
CardType = 054
China UnionPay 620001
99 9980 0019
CardType = 062
Action
If you request Check Enrollment and authorization services separately, add the required
payer authentication values to your authorization request. If you request the Check
Enrollment and authorization services together, the process described above occurs
automatically.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1104
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3092
CardType = 036
Mastercard 520000
00 0000 1104
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3100
CardType = 036
American Express 340000
00 0001 106
CardType = 003
Discover 601100
00 0000 1101
CardType = 004
Diners Club 601100
00 0000 1101
CardType = 005
JCB J/Secure 333700
00 0020 0087
CardType = 007
Elo 650505
00 0000 1109
CardType = 054
China UnionPay 620001
99 9970 0029
CardType = 062
Action
You are not permitted to submit this transaction for authorization. Instead ask the
customer for another form of payment.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1104
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3092
CardType = 036
Mastercard 520000
00 0000 1104
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3100
CardType = 036
American Express 340000
00 0001 106
CardType = 003
Discover 601100
00 0000 1101
CardType = 004
Diners Club 601100
00 0000 1101
CardType = 005
JCB J/Secure 333700
00 0020 0087
CardType = 007
Elo 650505
00 0000 1109
CardType = 054
China UnionPay 620001
99 9970 0029
CardType = 062
Action
You are not permitted to submit this transaction for authorization. Instead ask the
customer for another form of payment.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1112
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3100
CardType = 036
Mastercard 520000
00 0000 1112
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3118
CardType = 036
American Express 340000
00 0001 114
CardType = 003
Discover 601100
00 0000 1119
CardType = 004
Diners Club 601100
00 0000 1119
CardType = 005
JCB J/Secure 333700
00 0020 0079
CardType = 007
Elo 650505
00 0000 1117
CardType = 054
China UnionPay 620001
99 9960 0039
CardType = 062
Action
Retry authentication or process without liability shift.
Card Numbers
Card Type Test Card Number
Visa 445653
00 0000 1112
CardType = 001
Cartes Bancaires Visa 445653
00 0000 3100
CardType = 036
Mastercard 520000
00 0000 1112
CardType = 002
Cartes Bancaires Mastercard 520000
00 0000 3118
CardType = 036
American Express 340000
00 0001 114
CardType = 003
Discover 601100
00 0000 1119
CardType = 004
Diners Club 601100
00 0000 1119
CardType = 005
JCB J/Secure 333700
00 0020 0079
CardType = 007
Elo 650505
00 0000 1117
CardType = 054
China UnionPay 620001
99 9960 0039
CardType = 062
Action
Retry authentication or process without liability shift.
This appendix describes the Simple Order API fields that you can use to access
Cybersource Payer Authentication services. The API and client toolkits can be
downloaded from the Cybersource website at the following URL:
http://www.cybersource.com/developers/develop/integration_methods/simple_order_
and_soap_toolkit_api/
Formatting Restrictions
Unless otherwise noted, all field names are case sensitive and all fields accept special
characters such as @, #, and %.
The values of the item_#_ fields must not contain carets (^) or colons (:)
because these characters are reserved for use by the Cybersource services.
For Atos, the billTo_ fields must not contain colons (:).
The values of all request fields must not contain new lines or carriage returns.
However, they can contain embedded spaces and any other printable
characters. All leading and trailing spaces will be removed.
http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/
Numbered Elements
The Cybersource XML schema includes several numbered elements. You can include
these complex elements more than once in a request. For example, when a customer
order includes more than one item, you must include multiple <item> elements in your
request. Each item is numbered, starting with 0. The XML schema uses an id attribute in
the item’s opening tag to indicate the number. For example:
<item id="0">
As a name-value pair field name, this tag is called item_0. In this portion of the field
name, the underscore before the number does not indicate hierarchy in the XML schema.
The item fields are generically referred to as item_#_<element name> in the
documentation.
Below is an example of the numbered <item> element and the corresponding name-
value pair field names. If you are using the Simple Object Access Protocol (SOAP), the
client contains a corresponding Item class.
When a request in XML format includes an <item> element, the element must
include an id attribute. For example: <item id="0">.
Request Fields
See Credit Card Services Using the Simple Order API (PDF | HTML) and Getting Started
with Cybersource Advanced (PDF | HTML) for more information about using the Simple
Order API to access Cybersource services using either name-value pairs or XML.
The fields in the following table refer to the enroll and validate services only.
Please review Credit Card Services Using the Simple Order API (PDF | HTML)
for more information about the fields specific to the authorization.
001: Visa
002: Mastercard
003: American Express
004: Discover
005: Diners Club
007: JCB
024: Maestro (UK Domestic)
036: Cartes Bancaires
042: Maestro (International)
054: Elo
062: China UnionPay
Note For the Payer Authentication Check
Enrollment Service and Payer Authentication
Validation Service, this field is required. You
must supply a value for it and include it in your
request.
For the Payer Authentication Setup service, the
field is required when card type is Cartes
Bancaires.
card_expirationMonth Expiration month (MM) of the card. Required for Enroll (R) String (2)
the Validate service if card_accountNumber is
Setup (R)
included.
Validate (O)
card_expirationYear Expiration year (YYYY) of the card. Required Enroll (R) String (4)
for the Validate service if card_
Setup (R)
accountNumber is included.
Validate (O)
encryptedPayment_data The encrypted payment data value. Setup (R)
encryptedPayment_ Format of the encrypted payment data. Setup (O) String (128)
descriptor
item_#_ Passenger's first name. Enroll (O) String (60)
passengerFirstName
See "Numbered Elements," page 148.
item_#_ Passenger's last name. Enroll (O) String (60)
passengerLastName
See "Numbered Elements," page 148.
shipTo_phoneNumber Phone number for the shipping address. Enroll (O) String (15)
For information on formatting, see billTo_
phoneNumber.
shipTo_postalCode Postal code for the shipping address. The Enroll (O) String (10)
postal code must consist of 5 to 9 digits.
When the shipping country is the U.S., the 9-
digit postal code must follow this format:
[5 digits][dash][4 digits]
Example 12345-6789
When the shipping country is Canada, the 6-
digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example A1B 2C3
Required if the shipTo_country field value is
US or CA.
Required for American Express SafeKey (U.S.).
Response Fields
Table 21 Response Fields
The following table lists the reason codes that are returned with the response.
Cybersource reserves the right to add new reason codes at any time. If your error handler
receives a reason code that it does not recognize, it should use the decision field to
determine the result.
This appendix contains examples for the check enrollment service and the validate
authentication service. All examples are in name-value pair format.
These examples contain only the fields essential to the demonstration. Do not
prepare your implementation according to the fields shown in these examples.
They are provided for your information only.
billTo_city=Mountain View
billTo_country=US
billTo_email=test@yahoo.com
billTo_firstName=Tanya
billTo_lastName=Lee
billTo_postalCode=94043
billTo_state=CA
billTo_street1=1234 Gold Ave
card_accountNumber=XXXXXXXXXXXXXXXX
card_cardType=001
card_expirationMonth=12
card_expirationYear=2030
merchantID=patest
merchantReferenceCode=0001
payerAuthSetupService_run=true
decision=ACCEPT
merchantReferenceCode=0001
payerAuththSetupReply_deviceDataCollectionURL=https://
centinelapistag.cardinalcommerce.com/V1/Cruise/Collect
payerAuthSetupReply_reasonCode=100
payerAuthSetupReply_referenceID=f13fe5e0-9b47-4ea1-a03a-ec360f4d0f9f
payerAuthSetupReply_
accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1MDc4OTI0Mi
0zYmEzLTRhZTItYWQwOS1kZjZkODk2NWQ5MjciLCJpYXQiOjE1OTgyOTk1MjQsImlzcyI6I
jVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5ODMwMzEyNCwiT3JnVW5pdElk
IjoiNTVlZjNmMTBmNzIzYWE0MzFjOTliNWViIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHR
wczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1
NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFa
UxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxj
bFJ5WVc1elNVUWlPaUkzTkRNeVlUWXdNQzA0TXpNMkxUUm1PRGN0WVdKbE9TMDJObVkzTkR
FM01EaGhNV1FpTENKaFkzTlVjbUZ1YzBsRUlqb2lPR0U1TkRkaU9ETXRNRFJpTkMwMFltVm
lMV0V5WWpNdFpHTmpNV0UxWmprMFlURXlJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2W
lNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiVEQ1b1MwbzFGQzY1cWF2MHhzeDAifSwi
T2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmN
vbS9zdGVwLXVwLXJldHVybi11cmwuanNwIn0.8wZ8XhLgOIIRvgEUugvYrRAi-
efavZTNM0tWInYLTfE
payerAuthSetupReply_reasonCode=100
requestID=5982993692286989203011
requestToken=AxjzbwSTRFa3h+A4wXZDABEBURwlqraRpAy7gDthk0kyro9JLIYA8AAA2w
K2
billTo_city=Mountain View
billTo_country=US
billTo_email=test@yahoo.com
billTo_firstName=Tanya
billTo_lastName=Lee
billTo_postalCode=94043
billTo_state=CA
billTo_street1=1234 Gold Ave
card_accountNumber=XXXXXXXXXXXXXXXX
card_cardType=001
card_cvNumber=111
card_expirationMonth=12
card_expirationYear=2030
ccAuthService_run=true
merchantID=patest
merchantReferenceCode=0001
payerAuthEnrollService_referenceID=f13fe5e0-9b47-4ea1-a03a-ec360f4d0f9f
payerAuthEnrollService_returnURL=https://example.com/step-up-return-
url.jsp
payerAuthEnrollService_run=true
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=30.00
decision=REJECT
merchantReferenceCode=0001
payerAuthEnrollReply_
accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1MDc4OTI0Mi
0zYmEzLTRhZTItYWQwOS1kZjZkODk2NWQ5MjciLCJpYXQiOjE1OTgyOTk1MjQsImlzcyI6I
jVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTU5ODMwMzEyNCwiT3JnVW5pdElk
IjoiNTVlZjNmMTBmNzIzYWE0MzFjOTliNWViIiwiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHR
wczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20vTWVyY2hhbnRBQ1
NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFa
UxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxj
bFJ5WVc1elNVUWlPaUkzTkRNeVlUWXdNQzA0TXpNMkxUUm1PRGN0WVdKbE9TMDJObVkzTkR
FM01EaGhNV1FpTENKaFkzTlVjbUZ1YzBsRUlqb2lPR0U1TkRkaU9ETXRNRFJpTkMwMFltVm
lMV0V5WWpNdFpHTmpNV0UxWmprMFlURXlJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2W
lNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiVEQ1b1MwbzFGQzY1cWF2MHhzeDAifSwi
T2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmN
vbS9zdGVwLXVwLXJldHVybi11cmwuanNwIn0.8wZ8XhLgOIIRvgEUugvYrRAi-
efavZTNM0tWInYLTfE
payerAuthEnrollReply_acsTransactionID=8a947b83-04b4-4beb-a2b3-
dcc1a5f94a12
payerAuthEnrollReply_acsURL=https://
0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp
payerAuthEnrollReply_authenticationTransactionID=TD5oS0o1FC65qav0xsx0
payerAuthEnrollReply_cardBin=400000
payerAuthEnrollReply_cardTypeName=VISA
payerAuthEnrollReply_challengeRequired=false
payerAuthEnrollReply_directoryServerTransactionID=395fb036-cfc6-462b-
b28d-d6ed7c970cdd
payerAuthEnrollReply_
paReq=eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwid
GhyZWVEU1NlcnZlclRyYW5zSUQiOiI3NDMyYTYwMC04MzM2LTRmODctYWJlOS02NmY3NDE3
MDhhMWQiLCJhY3NUcmFuc0lEIjoiOGE5NDdiODMtMDRiNC00YmViLWEyYjMtZGNjMWE1Zjk
0YTEyIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0
payerAuthEnrollReply_reasonCode=475
payerAuthEnrollReply_specificationVersion=2.2.0
payerAuthEnrollReply_stepUpUrl=https://
centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp
payerAuthEnrollReply_threeDSServerTransactionID=7432a600-8336-4f87-
abe9-66f741708a1d
payerAuthEnrollReply_veresEnrolled=Y
reasonCode=475
requestID=5982995245816268803007
requestToken=AxjzbwSTRFa9DM1xnUu/
ABEBURwlqsQ5pAy7gDtXb0kyro9JLIYA8AAA2wK2
billTo_city=Mountain View
billTo_country=US
billTo_email=null@cybersource.com
billTo_firstName=John
billTo_lastName=Doe
billTo_postalCode=94043
billTo_state=CA
billTo_street1=1295 Charleston Road
card_accountNumber=XXXXXXXXXXXXXXXX
card_cardType=001
card_cvNumber=111
card_expirationMonth=12
card_expirationYear=2030
ccAuthService_run=true
merchantID=patest
merchantReferenceCode=0001
payerAuthValidateService_
authenticationTransactionID=TD5oS0o1FC65qav0xsx0
payerAuthValidateService_run=true
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=30.00
merchantID=patest
merchantReferenceCode=0001
payerAuthValidateService_
authenticationTransactionID=hejNPA0YQlL5gVwZ6OX0
payerAuthValidateService_run=true
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=30.00
ccAuthReply_amount=30.00
ccAuthReply_authorizationCode=888888
ccAuthReply_authorizedDateTime=2020-08-24T20:06:35Z
ccAuthReply_avsCode=X
ccAuthReply_avsCodeRaw=I1
ccAuthReply_cvCode=M
ccAuthReply_cvCodeRaw=M
ccAuthReply_paymentNetworkTransactionID=123456789619999
ccAuthReply_processorResponse=100
ccAuthReply_reasonCode=100
ccAuthReply_reconciliationID=734426477E432MHS
merchantReferenceCode=0001
payerAuthValidateReply_acsTransactionID=8a947b83-04b4-4beb-a2b3-
dcc1a5f94a12
payerAuthValidateReply_authenticationResult=0
payerAuthValidateReply_authenticationStatusMessage=Success
payerAuthValidateReply_cardBin=400000
payerAuthValidateReply_cardTypeName=VISA
payerAuthValidateReply_cavv=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
payerAuthValidateReply_commerceIndicator=vbv
payerAuthValidateReply_directoryServerTransactionID=395fb036-cfc6-462b-
b28d-d6ed7c970cdd
payerAuthValidateReply_eci=05
payerAuthValidateReply_eciRaw=05
payerAuthValidateReply_paresStatus=Y
payerAuthValidateReply_reasonCode=100
payerAuthValidateReply_specificationVersion=2.2.0
payerAuthValidateReply_threeDSServerTransactionID=7432a600-8336-4f87-
abe9-66f741708a1d
payerAuthValidateReply_xid=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
purchaseTotals_currency=USD
reasonCode=100
requestID=5982995945196028003011
requestToken=Axj/7wSTRFa/
iOJ7uYLDABEg3ZtGjJs0bt4rRmymyKaiOEtVlSQFRHCWqypOkDLuAO1eDSTKuj0kshoD5NE
Vr+I4nu5gsMAA9ACm
decision=ACCEPT
merchantReferenceCode=0001
payerAuthValidateReply_acsTransactionID=ff412c09-4ea8-4f37-923e-
4c405fb3951c
payerAuthValidateReply_authenticationResult=0
payerAuthValidateReply_authenticationStatusMessage=Success
payerAuthValidateReply_cardBin=400000
payerAuthValidateReply_cardTypeName=VISA
payerAuthValidateReply_cavv=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
payerAuthValidateReply_commerceIndicator=vbv
payerAuthValidateReply_directoryServerTransactionID=6c29615b-1a1e-4c13-
9739-0394917163a3
payerAuthValidateReply_eci=05
payerAuthValidateReply_eciRaw=05
payerAuthValidateReply_paresStatus=Y
payerAuthValidateReply_reasonCode=100
payerAuthValidateReply_specificationVersion=2.1.0
payerAuthValidateReply_threeDSServerTransactionID=2c2294e9-6b70-4b19-
bedb-7b43065f20ce
payerAuthValidateReply_xid=MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
reasonCode=100
requestID=6001869286506329603009
requestID=0340290070000167905080
merchantReferenceCode=23AEE8CB6B62EE2AF07
purchaseTotals_currency=USD
decision=ACCEPT
reasonCode=100
payerAuthEnrollReply_reasonCode=100
payerAuthEnrollReply_authenticationResult=0
payerAuthEnrollReply_authenticationStatusMessage=Success
payerAuthEnrollReply_authenticationTransactionID=Fl8d1UW9VwTyawKTdex0
payerAuthEnrollReply_cavv=Y2FyZGluYWxjb21tZXJjZWF1dGg=
payerAuthEnrollReply_commerceIndicator=vbv
payerAuthEnrollReply_eci=5
payerAuthEnrollReply_eciRaw=05
payerAuthEnrollReply_paresStatus=Y
payerAuthEnrollReply_reasonCode=100
payerAuthEnrollReply_specificationVersion=2.0.1
payerAuthEnrollReply_veresEnrolled=Y
payerAuthEnrollService_run=true
merchantID=patest
merchantReferenceCode=23AEE8CB6B62EE2AF07
item_0_unitPrice=19.99
purchaseTotals_currency=USD
card_expirationMonth=01
card_expirationYear=2020
card_accountNumber=xxxxxxxxxxxxxxxx
card_cardType=001
...
<Other 2.0 optional fields>
referenceID=CybsTester-778d0f67
requestID=0340290070000167905080
merchantReferenceCode=23AEE8CB6B62EE2AF07
purchaseTotals_currency=USD
decision=REJECT
reasonCode=475
payerAuthEnrollReply_reasonCode=475
payerAuthEnrollReply_acsURL=https://www.example.com
payerAuthEnrollReply_authenticationTransactionID=x0Jpbq2uIT7o0tQqwd60
payerAuthEnrollReply_paReq=value in base64:
eJxVUuFygjAMfhXPw9Tkv9g6...
payerAuthEnrollReply_specificationVersion=2.0.1
payerAuthEnrollReply_veresEnrolled=Y
request_
token=AhjzbwSTHCfKtXsaE6elEQJP+BFNcZtIHTiD9au3tjijj5Uar+AuAAAAkAY5
payerAuthValidateService_run=true
merchantID=patest
merchantReferenceCode=23AEE8CB6B62EE2AF07
item_0_unitPrice=19.99
purchaseTotals_currency=USD
card_expirationMonth=01
card_expirationYear=2020
card_accountNumber=xxxxxxxxxxxxxxxx
card_cardType=001
payerAuthValidateService_authenticationTransactionID=
UhGFMeW6IPZbgt9diHK0
referenceID=CybsTester-cc719e84
requestID=0340290070000167905080
merchantReferenceCode=23AEE8CB6B62EE2AF07
purchaseTotals_currency=USD
decision=ACCEPT
reasonCode=100
payerAuthValidateReply_reasonCode=100
payerAuthValidateReply_authenticationResult=0
payerAuthValidateReply_authenticationStatusMessage=Success
payerAuthValidateReply_cavv=Y2FyZGluYWxjb21tZXJjZWF1dGg=
payerAuthValidateReply_commerceIndicator=vbv
payerAuthValidateReply_eci=5
payerAuthValidateReply_eciRaw=05
payerAuthValidateReply_paresStatus=Y
payerAuthValidateReply_reasonCode=100
payerAuthValidateReply_specificationVersion=2.0.1
request_
token=AhjzbwSTHCfKtXsaE6elEQJP+BFNcZtIHTiD9au3tjijj5Uar+AuAAAAkAY5
This appendix contains information about modifying your website to integrate Cybersource
Payer Authentication services into your checkout process. It also provides links to
payment card company websites where you can download the appropriate logos.
Order submission button: disable the final “buy” button until the customer completes
all payment and authentication requirements.
Browser back button: account for unexpected customer behavior. Use session checks
throughout the authentication process to prevent authenticating transactions twice.
Avoid confusing messages, such as warnings about expired pages.
Make sure you have downloaded the appropriate logos of the cards that you support
and place these logos next to the card information entry fields on your checkout
pages. For more information about obtaining logos and using them, see "3D Secure
Services Logos," page 208.
Add a message next to the final “buy” button and the card logo to inform your
customers that they may be prompted to provide their authentication password or to
sign up for the authentication program specific to their card. For examples of
messages you can use, see "Informational Message Examples," page 209.
The following examples may be used, but consult your specific card authentication
program to make sure you conform to their messaging requirements.
Example 42
Example 43
Your card may be eligible for enrollment or is enrolled in the Visa Secure, Mastercard,
Maestro, American Express SafeKey, JCB J/Secure, Diners Club ProtectBuy, or Discover
ProtectBuy programs. After you submit your order, your card issuer may prompt you for
your password before you complete your purchase.
With other services, green means that the service request was successful, red means that
it failed, and black means that the service request was not run. However, you need to
interpret the result of the enrollment check differently:
If the card is enrolled, the application result is shown in red, which indicates that you
need to authenticate the user before you can request card authorization.
If the card is not enrolled, the application result is shown in green because you do not
need to authenticate the user. You can authorize the card immediately.
Enrolled Card
When a card is enrolled, the process consists of two steps: after you check for enrollment,
you need to authenticate the customer.
Enrollment Check
For the enrollment check for an enrolled card, payer authentication data is located in the
Transaction Search Details window in the following sections:
Request Information section: The enrollment check service is shown in red because
the card is enrolled. You receive the corresponding response information. If the card
authorization service had been requested at the same time, it would not have been
run and would appear in black.
You can obtain additional information about related orders by clicking the links on the
right (Event Search and Details).
Order Information section: When authentication is required, save the XID for use later.
You do not receive an ECI or AAV_CAVV because the authentication is not complete.
You can use the link to find the details page that shows the associated card validation and
authorization results. On the results page:
The most recent event is the successful authentication. If you click the request ID, the
authentication details page opens. If the event also returned an XID value, the By
Payer Authentication History link is present. If you click it, you return to the results
page.
If the card authorization service had been requested at the same time as payer
authentication, authorization would not have run with the enrollment check but with the
validate authentication request. On the results page:
The most recent event is the combined successful customer authentication and card
authorization. If you click the request ID, the details page opens.
The older event is the enrollment check in red because the card is enrolled.
Authentication Validation
For a transaction in which the validation and the card authorization services were
processed successfully, payer authentication data is located in the Transaction Search
Details window in the following sections:
Request Information section: The validation service succeeded. You receive the
reason code 100, and the corresponding response message. The necessary payer
authentication information was passed to the card authorization service, which was
processed successfully. Both services are shown in green.
Order Information section: You received a value for all three parameters because the
validation was successful. You may not receive an ECI value when a system error
prevents the card issuer from performing the validation or when the cardholder does
not complete the process.
Transaction Details
For a transaction in which the card is not enrolled, payer authentication data is located in
the Transaction Search Details window in the following sections:
Request Information section: the service is shown in green. You can obtain additional
information about related orders by clicking the link on the right.
Order Information section: the detailed information for the authorization service:
The AAV/CAVV area is empty because you receive a value only if the customer is
authenticated.
Search options:
Use the XID as search parameter to find both parts of a transaction processed
with an enrolled card. When using the XID as search option, make sure to keep
the = sign at the end of the string.
The list of applications is simplified to facilitate searching for the relevant service
requests.
Search results: the results options include the XID and the customer’s account
number (PAN). Use the XID to find all parts of the transaction.
Payer authentication details: all transaction details are discussed under "Searching for
Payer Authentication Details," page 210.
You may be required to show the values that you receive in the PARes, the proof XML,
and the PAReq fields as proof of enrollment checking for any payer authentication
transaction that you present again because of a chargeback. Your account provider may
require that you provide all data in human-readable format, so make sure that you can
decode the PAReq and PARes. For enrollment response examples, see Appendix C,
"Request and Response Examples," on page 195. The responses are similar for all card
types.
Payment card companies have implemented the 3D Secure protocol in different ways
throughout the world. Cybersource recommends that you contact your merchant account
provider to find out what is required. For more information on decrypting and providing the
PARes contact your account manager.
This chapter describes the reports that you can download from the Business Center. All
reports on the production servers are retained for 16 months but the transaction history is
only kept in the database for six months. All reports on the test servers are deleted after 60
days. Only transactions that were processed are reported. Those that resulted in system
error or time-out are not. For more information about API responses and their meanings,
see Appendix A, "API Fields," on page 147.
To obtain the reports, you must file a support ticket in the Support Center.
Step 2 Under Transaction Reports, click Payer Auth Summary. The Payer Auth Summary
Report page appears.
Step 3 In the search toolbar, select Date Range you want to include in the report. Account level
users must select a merchant as well.
Step 4 Based on the Date Range selected, choose the specific day, week, or month you want to
review.
Only months which have already occurred in the current year display in the Month list – to
view all months of a previous year, select the year first, then choose the desired month.
To view results from the period prior to or following the selected period, click Previous or
Next below the search toolbar.
Transactions are divided into two groups: those for which you are protected and those for
which you are not:
For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo:
liability shift for VbV and VbV attempted
The values (amounts and counts) in the Payer Authentication report may not match
exactly your other sources of reconciliation because this report shows the transactions
that were validated by payer authentication, not necessarily the transactions that were
authorized. There are more likely to be reconciliation discrepancies if you process your
authorizations outside of Cybersource.
The amounts and numbers can be higher in the Payer Authentication report than in the
payment reports. In this example, it shows the results of the first two numbers in the Payer
Authentication report and the last one in the payment reports.
To reconcile your reports more easily when using payer authentication, we recommend
that you attempt to authenticate the same amount that you want to authorize.
https://ics2ws.in.ic3.com/commerce/1.x/transactionProcessor.
Report Elements
<Report>
The <Report> element is the root element of the report.
<Report>
<PayerAuthDetails>
(PayerAuthDetail+)
</PayerAuthDetails>
</Report>
<PayerAuthDetail>
The <PayerAuthDetail> element contains information about a single transaction.
<PayerAuthDetail>
(RequestID)
(MerchantID)
(RequestDate)
(TransactionType)
(ProofXML)?
(VEReq)?
(VERes)?
(PAReq)?
(PARes)?
(AuthInfo)?
</PayerAuthDetail>
<TransactionType> Cybersource service requested in SCMP format. This field can String (20)
contain one of the following values:
ics_auth: Card authorization service
ics_pa_enroll: Payer Authentication Enrollment Check
ics_pa_validate: Payer Authentication Validation
<ProofXML> Data that includes the date and time of the enrollment check and String (1024)
the VEReq and VERes elements. This field corresponds to the
payerAuthEnrollReply_proofXML API field.
<VEReq> Verify Enrollment Request (VEReq) sent by the merchant’s server
to the directory server and by the directory server to the ACS to
determine whether authentication is available for the customer’s
card number. For a list of child elements, see "<VEReq>,"
page 221.
<VERes> Verify Enrollment Response (VERes) sent by the directory server.
For a list of child elements, see "<VERes>," page 222.
<PAReq> Payer Authentication Request message that you send to the ACS
through the payment card company. Corresponds to the
payerAuthEnrollReply_paReq API field.
For a list of child elements, see "<PAReq>," page 223.
<PayerAuthDetail>
<RequestID>0004223530000167905139</RequestID>
<MerchantID>example_merchant</MerchantID>
<RequestDate>2020-02-09T08:00:09-08:00</RequestDate>
<TransactionType>ics_pa_enroll</TransactionType>
<ProofXML>
...
</ProofXML>
<VEReq>
...
</VEReq>
<VERes>
...
</VERes>
<PAReq>
...
</PAReq>
<PARes>
...
</PARes>
</PayerAuthDetail>
<ProofXML>
The <ProofXML> element contains data that includes the date and time of the enrollment
check and the VEReq and VERes elements. This element corresponds to the
payerAuthEnrollReply_proofXML API field.
<ProofXML>
(Date)
(DSURL)
(PAN)
(AcqBIN)
(MerID)
(Password)
(Enrolled)
</ProofXML>
<PAN> Customer’s masked account number. This element corresponds to the String (19)
payerAuthEnrollReply_proxyPAN API field.
<AcqBIN> First six digits of the acquiring bank’s identification number. Numeric (6)
<MerID> Identifier provided by your acquirer; used to log into the ACS URL. String (24)
<Password> Merchant's masked authentication password to the ACS; provided by String (8)
your acquirer. Applies only to cards issued outside the U.S.
<Enrolled> Result of the enrollment check. This field can contain one of these String (1)
values:
Y: Authentication available.
N: Cardholder not participating.
U: Unable to authenticate regardless of the reason.
<ProofXML>
<Date>20200209 08:00:34</Date>
<DSURL>https:123.456.789.01:234/DSMsgServlet</DSURL>
<PAN>XXXXXXXXXXXX0771</PAN>
<AcqBIN>123456</AcqBIN>
<MerID>4444444</MerID>
<Password />
<Enrolled>Y</Enrolled>>
</ProofXML>
<VEReq>
The <VEReq> element contains the enrollment check request data.
<VEReq>
(PAN)
(AcqBIN)
(MerID)
</VEReq>
<MerID> Identifier provided by your acquirer; used to log in to the ACS URL. String (24)
<VEReq>
<PAN>XXXXXXXXXXXX0771</PAN>
<AcqBIN>123456</AcqBIN>
<MerID>example</MerID>
</VEReq>
<VERes>
The <VERes> element contains the enrollment check response data.
<VERes>
(Enrolled)
(AcctID)
(URL)
</VERes>
<URL> URL of Access Control Server where to send the PAReq. This element String (1000)
corresponds to the payerAuthEnrollReply_acsURL API field.
<VERes>
<Enrolled>Y</Enrolled>
<AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
<URL>https://www.example_url.com</URL>
</VERes>
<PAReq>
The <PAReq> element contains the payer authentication request message. This element
corresponds to the payerAuthEnrollReply_paReq API field.
<PAReq>
(AcqBIN)
(MerID)
(Name)
(Country)
(URL)
(XID)
(Date)
(PurchaseAmount)
(AcctID)
(Expiry)
</PAReq>
<MerID> Identifier provided by your acquirer; used to log in to the ACS URL. String (24)
<Country> Two-character code for the merchant’s country of operation. String (2)
<XID> Unique transaction identifier generated by Cybersource for each String (28)
Payment Authentication Request (PAReq) message. The PARes sent
back by the issuing bank contains the XID of the PAReq. To ensure that
both XIDs are the same, compare it to the XID in the response. To find
all requests related to a transaction, you can also search transactions
for a specific XID.
<Date> Date and time of request. DateTime (25)
Note Although the date and time should appear sequentially during all
stages of the processing of an order, they may not because of differing
time zones and synchronization between servers.
<Purchase Authorization amount and currency for the transaction. This element Amount (15)
Amount> corresponds to the totals of the offer lines or from the following fields:
ccAuthReply_amount (see Credit Card Services Using the Simple
Order API [PDF | HTML]) or purchaseTotals_grandTotalAmount
from external data.
<AcctID> Masked string used by the ACS. String (28)
<Expiry> Expiration month and year of the customer’s card. Number (4)
<PAReq>
<AcqBIN>123456</AcqBIN>
<MerID>444444</MerID>
<Name>example</Name>
<Country>US</Country>
<URL>http://www.example.com</URL>
<XID>fr2VCDrbEdyC37MOPfIzMwAHBwE=</XID>
<Date>2020-02-09T08:00:34-08:00</Date>
<PurchaseAmount>1.00 USD</PurchaseAmount>
<AcctID>NDAxMjAwMTAxMTAwMDc3MQ==</AcctID>
<Expiry>2309</Expiry>
</PAReq>
<PARes>
The <PARes> element contains the payer authentication response message.
<PARes>
(AcqBIN)
(MerID)
(XID)
(Date)
(PurchaseAmount)
(PAN)
(AuthDate)
(Status)
(CAVV)
(ECI)
</PARes>
<MerID> Identifier provided by your acquirer; used to log in to the ACS String (24)
URL.
<XID> XID value returned in the customer authentication response. This String (28)
element corresponds to the payerAuthEnrollReply_xid and
payerAuthValidateReply_xid API fields.
<Date> Date and time of request. DateTime (25)
Note Although the date and time should appear sequentially
during all stages of the processing of an order, they may not
because of differing time zones and synchronization between
servers.
<PARes>
<AcqBIN>123456</AcqBIN>
<MerID>4444444</MerID>
<XID>Xe5DcjrqEdyC37MOPfIzMwAHBwE=</XID>
<Date>2020-02-09T07:59:46-08:00</Date>
<PurchaseAmount>1002.00 USD</PurchaseAmount>
<PAN>0000000000000771</PAN>
<AuthDate>2020-02-09T07:59:46-08:00</AuthDate>
<Status>Y</Status>
<CAVV>AAAAAAAAAAAAAAAAAAAAAAAAAAA=</CAVV>
<ECI>5</ECI>
</PARes>
<AuthInfo>
The <AuthInfo> element contains address and card verification information.
<AuthInfo>
(AVSResult)
(CVVResult)
</AuthInfo>
<AuthInfo>
<AVSResult>Y</AVSResult>
<CVVResult/>
</AuthInfo>
Examples
These examples show a complete transaction: the failed enrollment check (enrolled card)
and the subsequent successful authentication.
Successful Authentication
Rules-based payer authentication enables you to specify rules that define how
transactions are authenticated by a 3D Secure card authentication program. For example,
you can decide to turn off active authentication for transactions that would otherwise
require customer interaction to avoid degrading the customer experience. However, you
may decide to authenticate customers from card-issuing banks that use risk-based
authentication because the authentication is performed without customer interaction.
To enable your account for rules-based payer authentication, contact your Cybersource
sales representative.
Available Rules
By default, when payer authentication is enabled on your account, authentication is
attempted on all transactions.
For transaction types that are not bypassed, you may be required to complete
authentication.
You can enable one or more of the following authentication transaction types. Any
transaction types that are set to bypass authentication return the reason code 100. If you
receive reason code 475 from the enrollment check, you must complete validation even if
no customer participation is needed.
API Responses
By default, API responses that are specifically associated with rules-based
payer authentication are turned off. Contact Cybersource Customer Support to
enable these API responses when rules are triggered.
payerAuthEnrollReply_authenticationPath
= RIBA
The card-issuing bank supports risk-based authentication, but whether the
cardholder is likely to be challenged cannot be determined.
= RIBA_PASS
The card-issuing bank supports risk-based authentication, and it is likely that the
cardholder will not be challenged to provide credentials; also known as silent
authentication.
Implementation Overview
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," page 22.
Use 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 Chapter 5, "Testing Payer Authentication Services," on page 64.
3 Call Cardinal.setup().
4 Run 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.
5 You request the Enrollment Check service, passing in transaction details and the
payerAuthEnrollService_referenceID request field.
6 If the issuing bank does not require authentication, you receive the following information in
the Enrollment Check response:
E-commerce indicator
CAVV (all card types except Mastercard)
AAV (Mastercard only)
Transaction ID
3D Secure version
Directory server transaction ID
7 If 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.
8 The JavaScript displays the authentication window, and the customer enters the
authentication information.
9 The bank validates the customer credentials, and a JWT is returned that the merchant is
required to validate server-side for security reasons.
10 You request the Validate Authentication service, extracting the processor transaction ID
value from the JWT and sending it in the payerAuthValidateService_
authenticationTransactionID 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," page 241.
Credentials/API Keys
API keys are required in order to create the JSON Web Token (JWT). For further
information, contact Cybersource Customer Support.
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 34 lists the standard claims that can be used in a JWT claim set.
Payload The JSON data object being sent. This object is usually an
order object.
Optional ReferenceId Merchant-supplied identifier that can be used to match up
data collected from the Hybrid integration API and
enrollment check service.
ObjectifyPayload Boolean flag that indicates how the API should consume
the payload claim. If set to true, the payload claim is an
object. If set to false, the payload claim is a stringified
object. Some JWT libraries do not support passing objects
as claims; this allows those who only allow strings to use
their libraries without customization.
JWT Examples
Example 45 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 46 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,
}
2 Listen for Events: subscribe to events with Cardinal.on() and set up callback functions
for:
3 Initialize it: call Cardinal.setup() to trigger and pass your JWT to the JavaScript for each
transaction.
BIN Detection
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.
billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_cardType
card_expirationMonth
card_expirationYear
merchantID
merchantReference Code
payerAuthEnrollService_referenceID
payerAuthEnrollService_run
purchaseTotals_currency
purchaseTotals_grandTotalAmount
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 Fields," page 149.
You can use the enrollment check and card authorization services in the same request or
in separate requests:
Same 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.
Separate requests: you must manually include the enrollment check result values
(Enrollment Check Response Fields) in the authorization service request (Card
Authorization Request Fields).
Enrolled Cards
You receive reason code 475 if the customer’s card is enrolled in a payer
authentication program. When you receive this response, you can proceed to validate
authentication.
When the account number is not enrolled in a payer authentication program. The
other services in your request are processed normally.
When payer authentication is not supported by the card type.
When you receive this response, you can proceed to card authorization.
Example 47 Cardinal.continue
Cardinal.continue('cca',
"AcsUrl":"https://testcustomer34.cardinalcommerce.com/
merchantacsfrontend/pareq.jsp?vaa=b&gold=AAAAAAAA...AAAAAAA",
"Payload":"eNpVUk1zgjAQvedXME7PJEFBVdKt1CECeDkVCk2PcfcnNjv8Kr+7tx4nlbGO
cz/se6G1uMENPTPeeIz1G37WGEUth7YnpO21TfTvF3wDCBqspQ=="
},
"OrderDetails":{
"TransactionId" :"123456abc"
);
{
"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"
}
}
Send the credit card information including the PAN, currency, and expiration date
(month and year).
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:
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:
For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo
include the CAVV (cardholder authentication verification value).
For Mastercard, include the UCAF (universal cardholder authentication field) and the
collection indicator.
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:
Success:
You receive the reason code 100, and other service requests, including authorization,
are processed normally.
Failure:
You receive reason code 476 indicating that the authentication failed, so the other
services in your request are not processed.
Error:
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.
Authentication Failed
Your card issuer cannot authenticate this card. Please select another card
or form of payment to complete your purchase.
Implementation Overview
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," page 22.
Use 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 Chapter 5, "Testing Payer Authentication Services," on page 64.
3 Call Cardinal.setup().
4 Run 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.
5 When the customer places an order on your website, you call the cardinal.start function to
pass in the transaction level data including the full PAN and order details.
6 The JavaScript verifies with the bank that the card is enrolled in a 3D Secure card
authentication program by using a server-to-server call.
7 If the issuing bank requires authentication, the JavaScript displays the authentication
window.
9 The bank validates the customer credentials, and a JWT is returned that the merchant is
required to validate server-side for security reasons.
10 You request the ICS Enrollment Check service, extracting the processor transaction ID
value from the JWT and sending it in the payerAuthEnrollService_
authenticationTransactionID request field. You receive this information:
E-commerce indicator
CAVV (all card types except Mastercard)
AAV (Mastercard only)
Transaction ID
3D Secure version
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 Check Enrollment Service
(Standard)," page 249.
Credentials/API Keys
API keys are required in order to create the JSON Web Token (JWT). For further
information, contact Cybersource Customer Support.
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 34 lists the standard claims that can be used in a JWT claim set.
Payload The JSON data object being sent. This object is usually an
order object.
Optional ReferenceId Merchant-supplied identifier that can be used to match up
data collected from the Standard integration API and
enrollment check service.
ObjectifyPayload Boolean flag that indicates how the API should consume
the payload claim. If set to true, the payload claim is an
object. If set to false, the payload claim is a stringified
object. Some JWT libraries do not support passing objects
as claims; this allows those who only allow strings to use
their libraries without customization.
JWT Examples
Example 45 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 46 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,
}
2 Listen for Events: subscribe to events with Cardinal.on() and set up callback functions
for:
3 Initialize it: call Cardinal.setup() to trigger and pass your JWT to the JavaScript for each
transaction.
BIN Detection
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.
Starting Authentication
The JavaScript handles the device data collection, initiates the transaction for
authentication, displays the authentication window if required, and returns the
authentication results.
You initiate this authentication process, usually when the customer clicks the Place Order
or Submit Order button, by triggering Cardinal.start(). Cardinal.start() invokes the
authentication and authenticates the customer.
Create an order object to pass to the Cardinal.start() event. The more fields you include,
the less likely the cardholder will be challenged to provide credentials.
Initiate Cardinal.start() before the authorization as shown in Example 51. The second
argument of data is a Request Order Object. You can construct this object ahead of time
or pass it directly as shown.
Cardinal.start("cca", {
OrderDetails: {
OrderNumber: "1234567890"
},
Consumer: {
Account: {
AccountNumber: "4000000000001000",
ExpirationMonth: "01",
ExpirationYear: "2099"
...
<Other 2.x required/optional fields>
}
}
...
});
Payments.validated returns the authentication results and response JWT along with the
processor transaction ID as shown in Example 52.
{
"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"
}
}
Authentication Failed
Your card issuer cannot authenticate this card. Please select another card
or form of payment to complete your purchase.
To request the Check Enrollment service, extract the processor transaction ID value
from the JWT and send it in the payerAuthEnrollService_authenticationTransactionID
request field. The following fields are also required:
billTo_city
billTo_country
billTo_email
billTo_firstName
billTo_lastName
billTo_postalCode
billTo_state
billTo_street1
card_accountNumber
card_cardType
card_expirationMonth
card_expirationYear
merchantID
merchantReference Code
payerAuthEnrollService_referenceID
payerAuthEnrollService_run
purchaseTotals_currency
purchaseTotals_grandTotalAmount
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 Fields," page 149.
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:
If you request the services separately, you must manually include the enrollment check
result values (Enrollment 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:
For Visa, American Express, JCB, Diners Club, Discover, China UnionPay, and Elo
include the CAVV (cardholder authentication verification value).
For Mastercard, include the UCAF (universal cardholder authentication field) and the
collection indicator.
In most cases, you request card authorization only once for each purchase. However, you
must send multiple authorization requests if the original authorization expires before it is
captured, which can occur when order fulfillment is split or delayed. In these cases, you
must include in subsequent authorization requests the same payer authentication data
contained in the original request so that your acquiring bank can track all related requests
if a dispute occurs. Authentication data can only be used for one authorization and cannot
be used multiple times or on subsequent authorizations.
This appendix describes alternate methods for device data collection. You can also use
the Payer Authentication Setup service described in Chapter 2, Implementing Cardinal
Cruise Direct Connection API Payer Authentication.
If you are using tokenization, use the Cardinal Cruise Direct Connection API integration
method and Payer Authentication Setup service.
The Cardinal Cruise Direct Connection API places the required Method URL on the
merchant's site within an iframe if the issuing bank chooses to use one. (According to
EMV 3D Secure requirements, a merchant must place and run the Method URL on their
website if the issuing bank uses one.)
The Method URL is a concept in the EMV 3D Secure protocol that allows an issuing bank
to obtain additional browser information prior to starting the authentication session to help
facilitate risk-based authentication. The implementation techniques for obtaining the
additional browser information are out of scope of the EMV 3D Secure protocol. This
process also occurred in 3D Secure 1.0 when the customer's browser was redirected to
the ACS URL. The Method URL step provides a better user experience.
Prerequisites
To support device data collection, you must complete one of the following:
Obtain access to the card BIN (first 8 digits or full card number of cardholder).
Create an iframe on your website and POST to the device data collection URL.
Endpoints
Staging: https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect
Production: https://centinelapi.cardinalcommerce.com/V1/Cruise/Collect
Card BIN in JWT: This option is the recommended approach and allows you to pass
the card BIN (first 8 digits or full card number) in the JWT.
Card BIN as a POST parameter plus JWT: This option allows you to pass the card
BIN directly from the web front end to the device data collection URL instead of the
JWT. However, a JWT is still required in order to authenticate the session.
Step 1 Add the card BIN (first 8 digits or full card number) to the transactional JWT.
Step 2 Create a POST request to send the transactional JWT to the device data collection URL.
Step 3 Handle the response from the device data collection URL on the return URL provided
within the transactional JWT.
Example 53 shows the return URL populated in the transactional JWT instead of a POST
parameter.
Step 1 Create a POST request to send the transactional JWT and the card BIN (first 8 digits or
full card number) to the device data collection URL.
Step 2 Handle the response from the device data collection URL on the return URL provided
within the transactional JWT.
Example 54 shows the return URL populated in the transactional JWT along with a POST
parameter.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Numerics
3D Secure Security protocol for online credit card and debit card transactions used by Visa
Secure, Mastercard Identity Check, American Express SafeKey, JCB J⁄Secure,
Diners Club ProtectBuy, Discover ProtectBuy, China UnionPay, and Elo.
acquirer The financial institution that accepts payments for products or services on behalf
of a merchant. Also referred to as “acquiring bank.” This bank accepts or acquires
transactions that involve a credit card issued by a bank other than itself.
acquirer BIN A 6-digit number that uniquely identifies the acquiring bank. There is a different
acquirer BIN for Mastercard (starts with 5) and Visa (starts with 4) for every
participating acquirer.
acquiring Processor that provides credit card processing, settlement, and services to
processor merchant banks.
ACS Access Control Server. The card-issuing bank’s host for the payer authentication
data.
ACS URL The URL of the Access Control Server of the card-issuing bank that is returned in
the response to the request to check enrollment. This is where you must send the
PAReq so that the customer can be authenticated.
ADS Activation During Shopping. The card issuer’s ability to ask the cardholder to
enroll in the card authentication service when the merchant posts to the ACS URL
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
A (Continued)
American Express A globally issued card type that starts with 3 and which is identified as card type
003 by Cybersource. These cards participate in a card authentication service
(SafeKey) provided by 3D Secure.
authentication Raw data sent by the card issuer that indicates the status of authentication. It is
result not required to pass this data into the authorization.
authorization A request sent to the card issuing bank that ensures a cardholder has the funds
available on their credit card for a specific purchase. A positive authorization
causes an authorization code to be generated and the funds to be held. Following
a payer authentication request, the authorization must contain payer
authentication-specific fields containing card enrollment details. If these fields are
not passed correctly to the bank, it can invalidate the liability shift provided by card
authentication. Systemic failure can result in payment card company fines.
Base64 Standard encoding method for data transfer over the Internet.
BIN Bank Identification Number. The 6-digit number at the beginning of the card that
identifies the card issuer.
CAVV algorithm A one-digit response passed back when the PARes status is a Y or an A. If your
processor is ATOS, this must be passed in the authorization, if available.
Compra Segura Trademarked name for the Elo card authentication service.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
C (Continued)
CVV Card Verification Value. Security feature for credit cards and debit cards. This
feature consists of two values or codes: one that is encoded in the magnetic strip
and one that is printed on the card. Usually the CVV is a three-digit number on the
back of the card. The CVV for American Express cards is a 4-digit number on the
front of the card. CVVs are used as an extra level of validation by issuing banks.
Diners Club A globally issued card type that starts with a 3 or a 5. Cybersource identifies
Diners Club cards with a card type of 005. These cards participate in a card
authentication service (ProtectBuy) provided by 3D Secure.
Directory Servers The Visa and Mastercard servers that are used to verify enrollment in a card
authentication service.
Discover Primarily, a U.S. card type that starts with a 6. Cybersource identifies Discover
cards with a card type of 004. These cards participate in a card authentication
service (ProtectBuy) provided by 3D Secure.
ECI (ECI Raw) The numeric commerce indicator that indicates to the bank the degree of liability
shift achieved during payer authentication processing.
E-Commerce Alpha character value that indicates the transaction type, such as MOTO or
Indicator INTERNET.
Elo A globally issued card type that starts with a 5. Cybersource identifies Elo cards
with a card type of 054. These cards participate in a card authentication service
(Compra Segura) provided by 3D Secure.
Enroll Cybersource transaction type used for verifying whether a card is enrolled in the
Mastercard Identity Check or Visa Secure service.
HTTP Hypertext Transfer Protocol. An application protocol used for data transfer on the
Internet.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
H (Continued)
HTTP POST POST is one of the request methods supported by the HTTP protocol. The POST
request request method is used when the client needs to send data to the server as part of
the request, such as when uploading a file or submitting a completed form.
HTTPS Hypertext Transfer Protocol combined with SSL/TLS (Secure Sockets Layer/
Transport Layer Security) to provide secure encryption of data transferred over
the Internet.
JCB Japan Credit Bureau. A globally issued card type that starts with a 3. Cybersource
identifies JCB cards with a card type of 007. These cards participate in a card
authentication service (J/Secure) provided by 3D Secure.
Maestro A card brand owned by Mastercard that includes several debit card BINs within
the U.K., where it was formerly known as Switch, and in Europe. Merchants who
accept Maestro cards online are required to use SecureCode, Mastercard’s card
authentication service. Cybersource identifies Maestro cards with the 024 and 042
card types.
Note that many international Maestro cards are not set up for online acceptance
and cannot be used even if they participate in a SecureCode card authentication
program.
Mastercard A globally issued card that includes credit and debit cards. These cards start with
a 5. Cybersource identifies these cards as card type 002 for both credit and debit
cards. These cards participate in a card authentication service (Mastercard
Identity Check) provided by 3D Secure.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
M (Continued)
MD Merchant-defined Data that is posted as a hidden field to the ACS URL. You can
use this data to identify the transaction on its return. This data is used to match
the response from the card-issuing bank to a customer’s specific order. Although
payment card companies recommend that you use the XID, you can also use data
such as an order number. This field is required, but including a value is optional.
The value has no meaning for the bank, and is returned to the merchant as is.
Merchant ID Data that must be uploaded for the Mastercard and Visa card authentication
process for each participating merchant. The Merchant ID is usually the bank
account number or it contains the bank account number. The data is stored on the
Directory Servers to identify the merchant during the enrollment check.
MPI Merchant Plug-In. The software used to connect to Directory Servers and to
decrypt the PARes.
PAN Primary Account Number. Another term for a credit card number.
PARes Status Payer Authentication Response status. One-character length status passed back
by Visa and Mastercard that is required data for Asia, Middle East, and Africa
Gateway authorizations.
processor Financial entity that processes payments. Also see acquiring processor.
ProofXML Cybersource field that contains the VEReq and VERes for merchant storage.
Merchants can use this data for future chargeback repudiation.
ProtectBuy Trademarked name for the Diners Club and Discover card authentication
services.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
request ID A 22- or 23-digit number that uniquely identifies each transaction sent to
Cybersource. Merchants should store this number for future reference.
SafeKey Trademarked name for the American Express card authentication service.
SCMP API Cybersource’s legacy name-value pair API that has been superseded by the
Simple Order API.
Simple Order API Cybersource’s current API, which provides three ways to access Cybersource
services: name-value pair (NVP), XML, and SOAP.
Solo A debit card type that was owned by Maestro. It was permanently discontinued
March 31, 2011.
TermURL Termination URL on a merchant’s website where the card-issuing bank posts the
payer authentication response (PARes) message.
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
UCAF collection Value of 1 or 2 that indicates whether a Mastercard cardholder has authenticated
indicator themselves or not.
validate Cybersource service for decoding and decrypting the PARes to determine
success. The validate service returns the needed values for authorization.
VEReq Verify Enrollment Request. Request sent to the Directory Servers to verify that a
card is enrolled in a card authentication service.
VERes Verify Enrollment Response. Response from the Directory Servers to the VEReq.
VERes enrolled Verify Enrollment Response enrolled. One-character length status passed back by
Visa and Mastercard that is required data for Asia, Middle East, and Africa
Gateway authorizations.
Visa A globally issued card that includes credit and debit cards. These cards start with
a 4. Cybersource identifies these cards as card type 001 for both credit and debit
cards. These cards participate in a card authentication service (Visa Secure)
provided by 3D Secure.
Visa Secure (VbV) Trademarked name for Visa’s card authentication service.
XID String used by both Visa and Mastercard which identifies a specific transaction on
the Directory Servers. This string value should remain consistent throughout a
transaction’s history.