This documentation outlines all fully constructed response objects used with Cardinal Cruise. These objects will be used within the payments.validated event. These object definitions are comprehensive, and include all possible response fields. Some of these fields will be conditionally returned based on integration method and/or transaction context.

Badges indicate payment brand specific objects. For example, if you see an object with the badge APPLE PAY this indicates this object will only be present in an Apple Pay transaction.

Key

The Inclusion column indicates when the specific fields can be expected to be returned on the API. The following values can be be used to identify when the values will be included:

Y	Always returned
N	Not guaranteed to be returned; may return of data is available
C	Returned based on certain conditions

Object Definition

The response object will be the Payload field within the JWT response.

Field	Type	Description	Inclusion
ActionCode	AN(30)	The resulting state of the transaction. Possible values: SUCCESS - The transaction resulted in success for the payment type used. For example, with a CCA transaction this would indicate the user has successfully completed authentication. NOACTION - The API calls to Centinel API were completed and there is no further actionable items to complete. This can indicate that the card holder is not enrolled in 3-D Secure or it could indicate a validation error was encountered at Centinel Core. It is recommended that the rest of the response is reviewed to determine what has occurred. FAILURE - The transaction resulted in an error. For example, with a CCA transaction this would indicate that the user failed authentication or an error was encountered while processing the transaction. ERROR - A service level error was encountered. These are generally reserved for connectivity or API authentication issues. For example if your JWT was incorrectly signed, or Cardinal services are currently unreachable.	Y
Authorization	Authorization Object	Authorization object. Please see the specification below.	N
AuthorizationProcessor	AuthorizationProcessor Object		N
Consumer	Consumer Object	Consumer object containing BillingAddress, ShippingAddress, and Account	N
ErrorNumber	AN(255)	Application error number. A non-zero value represents the error encountered while attempting the process the message request.	Y
ErrorDescription	AN(255)	Application error description for the associated error number.	Y
Payment	Payment Object		C
Validated	boolean	This value represents whether transaction was successfully or not.	Y
Token	Token Object	The token details associated with this transaction	N

Authorization

An object to pass the merchants intent to have Cardinal Cruise automatically authorize a Payeezy tokenization request. This should be passed on the start request.

Field

Type

Description

Inclusion

AuthorizeAccount

Bool

A flag to indicate that an authorization should be automatically run.

This flag is currently only used for Payeezy tokenization.

N

AuthorizationProcessor

PROCESSOR MODULE

An object used to pass back transaction details from the Cardinal Cruise to the merchant.

Field	Type	Description	Inclusion
ProcessorOrderId	AN(50)	The OrderId returned back from the Processor	Y
ProcessorTransactionId	AN(50)	The Transaction Identifier returned back from the Processor.	Y
ReasonCode	AN(255)	Third party error number. A non-zero value represents the error encountered while attempting the process the message request.	N
ReasonDescription	AN(255)	The thrid party description for the associated ReasonCode	N

Payment

Field	Type	Description	Inclusion
BillingAddress	Address	Consumers billing address. This field may not be present in every payment brand.	N
ExtendedData	Payment Extension Object	This will contain an extension object that corresponds to the Payment Type of this transaction. Refer to the Payment object Type field for what extension type this field is.	N
ProcessorTransactionId	AN(255)	The Transaction Identifier returned back from the Processor.	N
OrderId	AN(255)	Centinel generated order identifier. Used to link multiple actions (authorize, capture, refund, etc) on a single order to a single identifier. Mod-10 compliant and unique BIN range to CardinalCommerce services.	Y
OrderNumber	AN(255)	Order Number or transaction identifier from the Merchant website.	Y
ShippingAddress	Address	Consumers shipping address. This field may not be present in every payment brand.	N
Type	AN(50)	The payment type of this transaction. Possible Values: CCA - Cardinal Consumer Authentication Paypal Wallet VisaCheckout ApplePay DiscoverWallet	Y
ReasonDescription	AN(255)	Third party error description for the associated ReasonCode.	N

ExtendedData Extensions

Extensions allow for the passing of additional information thats specific to a payment brand type. The order object extensions are specifically used in the ExtendedData field of the Payment Object. The ExtendedData object type can be determined by using the Payment.Type field above. For example if Payment.Type = 'CCA' then the ExtendedData object will be the CCA object. If Payment.Type = 'VisaCheckout' the ExtendedData object will be the Visa Checkout extension.

Field	Description	Type
ACSTransactionId	Unique transaction identifier assigned by the ACS to identify a single transaction.	AN(36)
CardHolderInfo	Text provided by the ACS/Issuer to Cardholder during a Frictionless EMV 3DS transaction. The Issuer can provide information to Cardholder. For example, “Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.”. The Issuing Bank can optionally support this value. The merchant is required to display this within their Checkout when present. NOTE: Supports 3RI Device Channel in version 2.2.0. Decoupled authentication is not supported at this time.	AN(128)
DSTransactionId	Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction. NOTE: Required for Mastercard Identity Check transaction in Authorization	AN(36)
Enrolled	Status of Authentication eligibility. Possible Values: Y = Yes- Bank is participating in 3D Secure protocol and will return the ACSUrl N = No - Bank is not participating in 3D Secure protocol U = Unavailable - The DS or ACS is not available for authentication at the time of the request B = Bypass- Merchant authentication rule is triggered to bypass authentication in this use case NOTE: If the Enrolled value is NOT Y, then the Consumer is NOT eligible for Authentication.	AN(1)
ThreeDSServerTransactionId	Unique transaction identifier assigned by the 3DS Server to identify a single transaction.	AN(36)

Apple Pay

APPLE PAY

Field	Type	Description	Inclusion
CAVV	AN(40)	Cardholder Authentication Verification Value (CAVV) Authentication Verification Value (AVV) Universal Cardholder Authentication Field (UCAF). This value should be appended to the authorization message signifying that the transaction has been successfully authenticated. This value will be encoded according to the merchants configuration in either Base64 encoding or Hex encoding. A Base64 encoding merchant configuration will produce values of 28 or 32 characters. A Hex encoding merchant configuration will produce values of 40 or 48 characters. The value when decoded will either be 20 bytes for CAVV or 20 or 24 bytes if the value is AAV (MasterCard UCAF).	N
ECIFlag	AN(40)	Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the gateway/processor.	N
DeviceManufacturerIdentifier	AN	Hex-encoded device manufacturer identifier.	N
PaymentDataType	AN	Either `3DSecure` or, if using Apple Pay in China, `EMV`.	N

CCA

Field

Type

Description

Required

Enrolled

AN(1)

Status of Authentication eligibility.

Possible Values:

Y = Yes- Bank is participating in 3D Secure protocol and will return the ACSUrl
N = No - Bank is not participating in 3D Secure protocol
U = Unavailable - The DS or ACS is not available for authentication at the time of the request
B = Bypass- Merchant authentication rule is triggered to bypass authentication in this use case

NOTE: If the Enrolled value is NOT Y, then the Consumer is NOT eligible for Authentication.

C

Returned only in Cruise Standard integrations.

CAVV

AN(40)

Cardholder Authentication Verification Value (CAVV)
Authentication Verification Value (AVV)
Universal Cardholder Authentication Field (UCAF).

This value should be appended to the authorization message signifying that the transaction has been successfully authenticated. This value will be encoded according to the merchants configuration in either Base64 encoding or Hex encoding. A Base64 encoding merchant configuration will produce values of 28 or 32 characters. A Hex encoding merchant configuration will produce values of 40 or 48 characters. The value when decoded will either be 20 bytes for CAVV or 20 or 24 bytes if the value is AAV (MasterCard UCAF).

N

ECIFlag

AN(40)

Electronic Commerce Indicator (ECI). The ECI value is part of the 2 data elements that indicate the transaction was processed electronically. This should be passed on the authorization transaction to the gateway/processor.

MasterCard	Visa	Amex	JCB	Diners Club	Elo	CB (Visa)	CB (Mastercard)
02	05	05	05	05	05	05	02
01	06	06	06	06	06	06	01
00	07	07	07	07	07	07	00

N

PAResStatus

AN(1)

Transaction status result identifier.

Possible Values:

Y – Successful Authentication
N – Failed Authentication
U – Unable to Complete Authentication
A – Successful Attempts Transaction

N

SignatureVerification

AN(1)

Transaction Signature status identifier.

Possible Values:

Y - Indicates that the signature of the PARes has been validated successfully and the message contents can be trusted.
N - Indicates that the PARes could not be validated. This result could be for a variety of reasons; tampering, certificate expiration, etc., and the result should not be trusted.

N

XID

AN(40)

Transaction identifier resulting from authentication processing.

NOTE: Gateway/Processor API specification may require this value to be appended to the authorization message. This value will be encoded according to the merchants configuration in either Base64 encoding or Hex encoding. A Base64 encoding merchant configuration will produce values of 28 characters. A Hex encoding merchant configuration will produce values of 40 characters.

C

Returned only on AMEX transactions.

UCAFIndicator

AN(1)

Universal Cardholder Authentication Field (UCAF) Indicator value provided by the issuer.

Possible Values:
0 - Non-SecureCode transaction, bypassed by the Merchant
1 - Merchant-Only SecureCode transaction
2 - Fully authenticated SecureCode transaction

NOTE: This field is only returned for MasterCard transactions

N

ACSTransactionId

AN(36)

Unique transaction identifier assigned by the ACS to identify a single transaction.

C

Returned only in Cruise Standard integrations.

ThreeDSServerTransactionId

AN(36)

Unique transaction identifier assigned by the 3DS Server to identify a single transaction.

C

Returned only in Cruise Standard integrations.

DSTransactionId

AN(36)

Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.

NOTE: Required for Mastercard Identity Check transaction in Authorization

C

Returned only in Cruise Standard integrations.

CardHolderInfo

AN(128)

Text provided by the ACS/Issuer to Cardholder during a Frictionless EMV 3DS transaction.

The Issuer can provide information to Cardholder. For example, “Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx.”.

The Issuing Bank can optionally support this value. The merchant is required to display this within their Checkout when present.

NOTE: Supports 3RI Device Channel in version 2.2.0. Decoupled authentication is not supported at this time.

C

Returned only in Cruise Standard integrations.

AuthorizationPayload

Base64 encoded

The Base64 encoded JSON Payload of CB specific Authorization Values returned in the challenge Flow.

Example File: AuthorizationPayload-JSON File

C

Returned only when CardType is CB

CavvAlgorithm

CBN(1)

Identifies the algorithm used by the ACS to calculate the Authentication Value and is derived from the "CB-AVALGO"

C

Returned only when CardType is CB

ChallengeCancel

N(2)

An indicator as to why the transaction was canceled.

Possible Values:

01 - Cardholder selected 'Cancel'

02 - Reserved for future EMVCo use (values invalid until defined by EMVCo).

03 - Transaction Timed Out—Decoupled Authentication

04 - Transaction timed out at ACS—other timeouts

05 - Transaction Timed out at ACS - First CReq not received by ACS

06 - Transaction Error

07 - Unknown

08 = Transaction Timed Out at SDK

NOTE: Only present when the Consumer cancels the challenge. Decoupled Authentication is not supported at this time.

C

Paypal

PAYPAL EXPRESS CHECKOUT V.ZERO

Field	Type	Description	Inclusion
Enrolled	AN(1)	Status of Authentication eligibility. Possible Values: Y = Yes- Paypal is available and the response will contain the ACS url U = No - Paypal is unavailable.	N
PAResStatus	AN(1)	Transaction status result identifier. Possible Values: Y – Successful Authentication U – Unable to Complete Authentication	N
SignatureVerification	AN(1)	Transaction Signature status identifier. Possible Values: Y - Indicates that the signature of the data returned was verified and can be trusted. N - Indicates that the signature of the data returned could not be verified and cannot be trusted.	N
UserEmail	AN(255)	Email address of the Consumer used at PayPal.	N
BillingFullName	AN(128)	Name associated with the billing address.	N
ShippingFullName	AN(128)	Name associated with the shipping address.	N
UserFirstName	AN(64)	First name of the person associated with the PayPal account	N
UserLastName	AN(64)	Last name of the person associated with the PayPal account	N
BillingAddressStatus	AN(50)	PayPal Consumer Billing Address Status Possible Values: Confirmed - Customer provided a billing address that has been confirmed by PayPal. Unconfirmed - Customer provided an unconfirmed address. None - No status.	N
ShippingAddressStatus	AN(50)	PayPal Consumer Shipping Address Status Possible Values: Confirmed - Customer provided a shipping address that matches a billing address on record with PayPal and that billing address has been verified by AVS. Unconfirmed - Customer provided an unconfirmed address. None - No status.	N
UserStatus	AN(20)	PayPal Consumer Status Possible Values: Verified - Consumer has been verified by PayPal Unverified - Consumer has not been verified by PayPal	N
UserId	AN(130)	Payer Id assigned to the Consumer by PayPal.	N

Visa Checkout

VISA CHECKOUT

Field	Type	Description	Inclusion
Enrolled	AN(1)	Status of Authentication eligibility. Possible Values: Y = Yes- Visa Checkout is available and the response will contain the ACS url U = No - Visa Checkout is unavailable.	N
PAResStatus	AN(1)	Transaction status result identifier. Possible Values: Y - Successful Authentication U - Unable to Complete Authentication	N
SignatureVerification	AN(1)	Transaction status result identifier. Possible Values: Y - Indicates that the signature of the data returned was verified and can be trusted. U - Indicates that the signature of the data returned could not be verified and cannot be trusted.	N
UserEmail	AN(255)	Email address of the Consumer used at Visa Checkout.	N
BillingFullName	AN(128)	Name associated with the billing address.	N
ShippingFullName	AN(128)	Name associated with the shipping address.	N
UserFirstName	AN(64)	First name of the person associated with the Visa Checkout account.	N
UserLastName	AN(64)	Last name of the person associated with the Visa Checkout account.	N
BillingAddressStatus	AN(50)	Visa Checkout Consumer Billing Address Status Possible Values: Confirmed - Customer provided a billing address that has been confirmed by Visa Checkout. Unconfirmed - Customer provided an unconfirmed address. None - No status.	C
ShippingAddressStatus	AN(50)	Visa Checkout Consumer Shipping Address Status Possible Values: Confirmed - Customer provided a shipping address that matches a billing address on record with Visa Checkout and that billing address has been verified by AVS. Unconfirmed - Customer provided an unconfirmed address. None - No status.	C
UserStatus	AN(20)	Visa Checkout Consumer Shipping Address Status Possible Values: Verified - Consumer has been verified by Visa Checkout Unverified - Consumer has not been verified by Visa Checkout	Y
UserId	AN(130)	Payer Id assigned to the consumer by Visa Checkout	N

Shared Objects

These objects are found in both the request and response objects.

Account

Field	Type	Description	Required
AccountNumber	N	Consumer's Account Number. This represents the Consumer's Credit Card Number.	N
ExpirationMonth	N	Account/Credit Card Expiration Month in MM format. Example: January = 01	N
ExpirationYear	N	Account/Credit Card Expiration Year in YYYY format. Example: 2016	N
NameOnAccount	AN	Name on the Consumer's Account/Credit Card.	N
CardCode	N(4)	This is the CVV Code present on the back (or on the front in the case of AMEX) of a Consumer's Credit Card . This is required on Credit Card transactions.
CardBin	N(6)	Represents the first six numbers of the CardNumber field
CardType	String	Type of cards used for purchase. Possible Values: VSA - Visa MSC - Mastercard VSD - Visa Delta/Debit (UK) VSE - Visa Electron MAE - Maestro (UK, Spain & Austria) AMX - American Express DSC - Discover DIN - Diners CBLA - Carte Blanche CB JCB - JCB ENR - EnRoute JAL - JAL CTB - Carte Bleue DNK - Dankort CSI - CartaSi EAN - Encoded Account Number UATP - UATP MAEI - Maestro (International) CB - Cartes Bancaires ELO - ELO UPI - UnionPay International EFTPOS - eftpos Australia
CardLastFour	N(4)	Represents the last four numbers of the CardNumber field

Address

Field	Type	Required
FullName	AN	N
FirstName	AN	N
MiddleName	AN	N
LastName	AN	N
Address1	AN	N
Address2	AN	N
Address3	AN	N
City	AN	N
State	AN	N
PostalCode	AN	N
CountryCode	AN	N
Phone1	AN	N
Phone2	AN	N

Consumer

Field	Type	Description	Required
Email1	AN(255)	Consumer's primary E-mail Address.	N
Email2	AN(255)	Consumer's alternate E-mail Address.	N
ShippingAddress	Address Object	Consumer's Shipping Address.	N
BillingAddress	Address Object	Consumer's Billing Address.	N
Account	Account Object	Consumer's Account Information.	N

Token

Field	Type	Description
Token	AN(20)	If the merchant account has tokenization enabled through Cardinal or another payment platform, the token will be returned in this field
CardCode	N(4)	The CVV2 on the back of the card that was the token represents. This field is required when using Processor Module.
ExpirationMonth	N(2)	Account/Credit Card Expiration Month in MM format. Example: January = 01
ExpirationYear	N(4)	Account/Credit Card Expiration Year in YYYY format. Example: 2016

Response Objects

Object Definition

Authorization

AuthorizationProcessor

Payment

ExtendedData Extensions

Apple Pay

CCA

Paypal

Visa Checkout

Shared Objects

Account

Address

Consumer

Token