Response Objects

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:

YAlways returned
NNot guaranteed to be returned; may return of data is available
CReturned based on certain conditions




Object Definition

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

FieldTypeDescriptionInclusion
ActionCodeAN(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
AuthorizationAuthorization ObjectAuthorization object. Please see the specification below.N
AuthorizationProcessorAuthorizationProcessor Object
N
ConsumerConsumer ObjectConsumer object containing BillingAddress, ShippingAddress, and AccountN
ErrorNumberAN(255)Application error number. A non-zero value represents the error encountered while attempting the process the message request.Y
ErrorDescriptionAN(255)Application error description for the associated error number.Y
PaymentPayment Object
C
ValidatedbooleanThis value represents whether transaction was successfully or not.Y
TokenToken ObjectThe token details associated with this transactionN

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.

FieldTypeDescriptionInclusion
AuthorizeAccountBool

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

TypeDescriptionInclusion
ProcessorOrderIdAN(50)

The OrderId returned back from the Processor


Y
ProcessorTransactionIdAN(50)The Transaction Identifier returned back from the Processor.Y
ReasonCodeAN(255)Third party error number. A non-zero value represents the error encountered while attempting the process the message request.N
ReasonDescriptionAN(255)The thrid party description for the associated ReasonCodeN

Payment

FieldTypeDescriptionInclusion
BillingAddressAddressConsumers billing address. This field may not be present in every payment brand.N
ExtendedDataPayment Extension ObjectThis 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
ProcessorTransactionIdAN(255)The Transaction Identifier returned back from the Processor.N
OrderIdAN(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
OrderNumberAN(255)Order Number or transaction identifier from the Merchant website.Y
ShippingAddressAddressConsumers shipping address. This field may not be present in every payment brand.N
TypeAN(50)The payment type of this transaction. 
Possible Values:
  • CCA - Cardinal Consumer Authentication
  • Paypal
  • Wallet
  • VisaCheckout
  • ApplePay
  • DiscoverWallet
Y
ReasonDescriptionAN(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
ACSTransactionIdUnique 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)
ThreeDSServerTransactionIdUnique transaction identifier assigned by the 3DS Server to identify a single transaction.AN(36)

Apple Pay

APPLE PAY

FieldTypeDescriptionInclusion
CAVVAN(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
ECIFlagAN(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
DeviceManufacturerIdentifierANHex-encoded device manufacturer identifier.N
PaymentDataTypeANEither 3DSecure or, if using Apple Pay in China, EMV.N

CCA

CCA

FieldTypeDescriptionRequired
EnrolledAN(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.

CAVVAN(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
ECIFlagAN(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. 

MasterCardVisaAmexJCBDiners ClubEloCB (Visa)CB (Mastercard)
0205050505050502
0106060606060601
0007070707070700
N
PAResStatusAN(1)Transaction status result identifier. 

Possible Values:
  • Y – Successful Authentication
  • N – Failed Authentication
  • U – Unable to Complete Authentication
  • A – Successful Attempts Transaction
N
SignatureVerificationAN(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
XIDAN(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.

UCAFIndicatorAN(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
ACSTransactionIdAN(36)Unique transaction identifier assigned by the ACS to identify a single transaction.

C

Returned only in Cruise Standard integrations.

ThreeDSServerTransactionIdAN(36)Unique transaction identifier assigned by the 3DS Server to identify a single transaction.

C

Returned only in Cruise Standard integrations.

DSTransactionIdAN(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.

CardHolderInfoAN(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

ChallengeCancelN(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

FieldTypeDescriptionInclusion
EnrolledAN(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
PAResStatusAN(1)Transaction status result identifier. 

Possible Values:
  • Y – Successful Authentication
  • U – Unable to Complete Authentication
N
SignatureVerificationAN(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
UserEmailAN(255)Email address of the Consumer used at PayPal.N
BillingFullNameAN(128)Name associated with the billing address.N
ShippingFullNameAN(128)Name associated with the shipping address.N
UserFirstNameAN(64)First name of the person associated with the PayPal accountN
UserLastNameAN(64)Last name of the person associated with the PayPal accountN
BillingAddressStatusAN(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
ShippingAddressStatusAN(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
UserStatusAN(20)

PayPal Consumer Status

Possible Values:

  • Verified - Consumer has been verified by PayPal
  • Unverified - Consumer has not been verified by PayPal
N
UserIdAN(130)Payer Id assigned to the Consumer by PayPal.N


Visa Checkout

VISA CHECKOUT

FieldTypeDescriptionInclusion
EnrolledAN(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
PAResStatusAN(1)

Transaction status result identifier.

Possible Values:
  • Y - Successful Authentication
  • U - Unable to Complete Authentication
N
SignatureVerificationAN(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
UserEmailAN(255)Email address of the Consumer used at Visa Checkout.N
BillingFullNameAN(128)Name associated with the billing address.N
ShippingFullNameAN(128)Name associated with the shipping address.N
UserFirstNameAN(64)First name of the person associated with the Visa Checkout account.N
UserLastNameAN(64)Last name of the person associated with the Visa Checkout account.N
BillingAddressStatusAN(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
ShippingAddressStatusAN(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
UserStatusAN(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
UserIdAN(130)Payer Id assigned to the consumer by Visa CheckoutN

Shared Objects

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

Account

FieldTypeDescriptionRequired
AccountNumberNConsumer's Account Number. This represents the Consumer's Credit Card Number.N
ExpirationMonthNAccount/Credit Card Expiration Month in MM format.
Example: January = 01
N
ExpirationYearNAccount/Credit Card Expiration Year in YYYY format.
Example: 2016
N
NameOnAccountANName on the Consumer's Account/Credit Card.N
CardCodeN(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.
CardBinN(6)

Represents the first six numbers of the CardNumber field


CardTypeString

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


CardLastFourN(4)

Represents the last four numbers of the CardNumber field


Address

FieldTypeRequired
FullNameANN
FirstNameANN
MiddleNameANN
LastNameANN
Address1ANN
Address2ANN
Address3ANN
CityANN
StateANN
PostalCodeANN
CountryCodeANN
Phone1ANN
Phone2ANN

Consumer

FieldTypeDescriptionRequired
Email1AN(255)Consumer's primary E-mail Address.N
Email2AN(255)Consumer's alternate E-mail Address.N
ShippingAddressAddress ObjectConsumer's Shipping Address.N
BillingAddressAddress ObjectConsumer's Billing Address.N
AccountAccount ObjectConsumer's Account Information.N

Token

FieldTypeDescriptionRequired
TokenAN(20)If the merchant account has tokenization enabled through Cardinal or another payment platform, the token will be returned in this field
CardCodeN(4)

The CVV2 on the back of the card that was the token represents.

This field is required when using Processor Module.


ExpirationMonthN(2)Account/Credit Card Expiration Month in MM format.
Example: January = 01

ExpirationYearN(4)Account/Credit Card Expiration Year in YYYY format.
Example: 2016