AuthBridge

cmpi_ab_lookup

Request Message

Field Name

Description

Required

MsgType

cmpi_ab_lookup

Y

Version

Application message version identifier.

Current Version - 1.7

Y

Algorithm

The hash algorithm that was used to generate the Signature for the request.

Possible Values:

  • SHA-256

  • SHA-512

Y

Identifier

The unique identifier representing the API Key being used to generate the Signature that is specified on the request. This value will be provided by Cardinal at the time the API Key is generated.

Y

OrgUnit

The unique organizational unit for which the request is being processed for. Each merchant within the system will be assigned a unique OrgUnit value by Cardinal.

Y

Signature

The signature for the request being submitted. This value is generated by hashing the combination of the Timestamp and your API Key. For more information on this, please refer to Cardinal (cmpi) Messages | Generating a Signature Value

Y

Timestamp

The unix epoch time in milliseconds for the point in time that the request is generated.

Example:

1467122891960

Y

TransactionType

Identifies the transaction type used for processing.

Possible Values:

C - Credit Card/Debit Card Authentication 

Y

TransactionId

The Centinel-generated TransactionId value from the original Lookup/Authenticate message pair. This value specifies the exact transaction that is being requested by the request message. 

N

IPAddress

The IP address of the Consumer.

NOTE:   IPv4 and IPv6 are supported.

Example:

IPv4 address:  <IPAddress>1.12.123.255</IPAddress>

Pv6 address: <IPAddress>2011:0db8:85 a3:0101:0101:8a2e:03 70:7334</IPAddress>

N

Amount

Value represents the transaction amount without any decimalization or punctuation.

Example:

$123.67 = 12367, $1,500.00 = 150000

N

CurrencyCode

3 digit numeric, ISO 4217 currency code for the sale amount. Complete list of ISO 4217 values is included in the Appendix. 

N

CardNumber

Credit Card number used for the transaction.

N

FromDt

Beginning of period to search for payer authentication, formatted MM/dd/yyyy HH:mm:ss. Only the date portion is required. If the time isn't specified, the beginning of the date is used. Not required if TransactionId is provided. 

N

ToDt

End of period to search for payer authentication, formatted MM/dd/yyyy HH:mm:ss. Only the date portion is required. If the time isn't specified, the beginning of the date is used. Not required if TransactionId is provided.

N

Sample Message

<CardinalMPI> <MsgType>cmpi_ab_lookup</MsgType> <Version>1.7</Version> <Algorithm>SHA-512</Algorithm> <Identifier>{{API_KEY_IDENTIFIER}}</Identifier> <OrgUnit>{{ORG_UNIT_ID}}</OrgUnit> <Signature>{{GENERATED_SIGNATURE_VALUE}}</Signature> <Timestamp>{{TIMESTAMP}}</Timestamp> <TransactionType>C</TransactionType> <Amount>34920</Amount> <CurrencyCode>840</CurrencyCode> <CardNumber>4012001011000770</CardNumber> <FromDt>01/01/2005 00:00:00</FromDt> <ToDt>01/02/2005 00:00:00</ToDt> </CardinalMPI>

Response Message

This message is generated as a response to the cmpi_ab_lookup message.

Field Name

Description

Required

ErrorDesc

Application error description for the associated error number.

Y

ErrorNo

Application error number. A non-zero value represents the error encountered while attempting to process the message request.

Y

Cavv

Cardholder Authentication Verification Value (Cavv), Authentication Verification Value (AVV) or Universal Cardholder Authentication Field (UCAF - Mastercard Only).

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 merchant's 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 it is an AAV (UCAF Mastercard Only).

Y

Xid

Transaction Xid from 3-D Secure Authentication. Gateway/Processor API specification may require this value to be appended to the authorization message.

This value will be encoded according to the merchant's 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. 

Note: This is a required field for all card transactions for 1.0 but only AMEX for 2.x transactions. 

Y

EciFlag

Electronic Commerce Indicator (ECI). Based on the Transaction Status, the corresponding ECI value needs to be appended to the authorization message.

Possible Values - 01, 02, 05, 06, 07

Mastercard

01 - Indicates Merchant Liability 

02 - Indicates Card Issuer Liability 

Visa

05 - Indicates Card Issuer Liability 

06 - Indicates Card Issuer Liability 

07 - Indicates Merchant Liability 

JCB

05 - Indicates Card Issuer Liability 

06 - Indicates Card Issuer Liability 

07 - Indicates Merchant Liability 

Y

Enrolled

Status of availability (Y, N, U).

Y - Cardholder Enrolled

N - Not Enrolled

U - Cardholder Enrolled but Authentication Unavailable 

Y

PAResStatus

Transaction status result identifier (Y, N, U, A).

Y - Successful Transaction

N - Failed Transaction

U - Unable to Complete Transaction

A - Successful Attempts Transaction

Y

Signature Verification

Transaction Signature status identifier (Y, N).

Y - Indicates that the signature of the PARes has been validated successfully and that the message contents can be trusted. 

N - Indicates that, for a variety of reasons; tampering, certificate expiration, etc., the PARes could not be validated, and the result should not be trusted.

Y

ThreeDSVersion

This field contains the 3DS version that was used to process the transaction. 

Possible Values:

1.0.2

2.1.0

2.2.0

Y

UCAFIndicator

Universal Cardholder Authentication Field (UCAF Mastercard Only) 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

CavvAlgorithm

Indicates the algorithm used to generate the CAVV value.

Possible Values:

2 - CVV with ATN

3 - Mastercard SPA algorithm 

N

MerchantReferenceNumber

Merchant specified data.

N

OrderId

Centinel generated order identifier. Used to link multiple actions on a single order to a single identifier. Mod-10 compliant and unique BIN range to CardinalCommerce services. 

Y

TransactionType

Identifies the transaction type used for processing. 

Possible Values:

C - Credit Card/Debit Card Authentication

Y

ThirdPartyToken

Third Party Token that is returned from the token provider after a card number is specified on the request. 

NOTE: This field is returned if Tokenization is enabled in the Merchant profile setting AND if the Merchant is using a third party token provider.

N

Token

Centinel generated order identifier. 

NOTE: This field is returned if Tokenization is enabled in the Merchant profile settings. 

N

CardBrand

Name of the card brand that we processed the transaction through. 

Possible Values:

AMEX
DISCOVER
JCB
MAESTRO
MC
VISA
UNKNOWN
DINERSCLUB

Y

CardBin

The first six digits of the card that was processed.

N

ThreeDSServerTransactionId

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

3DS 2.0

DSTransactionId

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

NOTE: Required for Mastercard Identity Check transaction in Authorization - Only available in EMV 3DS (3DS 2.0) transactions

3DS 2.0

ACSTransactionId

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

3DS 2.0

ACSSignedContent

Contains the JWS object created by the ACS for the ARes message which consists of the following data elements -

  • ACS URL

  • ACS Ephemeral Public Key (QT)

  • SDK Ephemeral Public Key (QC)

3DS 2.0

ACSRenderingType

Identifies the UI Type the ACS will use to complete the challenge. 

NOTE: Only available for App transactions using the Cardinal Mobile SDK.

3DS 2.0

ACSUrl

The fully qualified URL to redirect the Consumer to complete the Consumer Authentication transaction.

NOTE: Available if Enrolled = Y

Y

AuthenticationType

Indicates the type of authentication that will be used to challenge the card holder. 

Possible Values:

01 - Static

02 - Dynamic 

03 - OOB (Out of Band)

04 - Decoupled

NOTE:  EMV® 3-D Secure version 2.1.0 supports values 01-03.  Version 2.2.0 supports values 01-04.  Decoupled authentication is not supported at this time.

3DS 2.0

ChallengeRequired

Indicates whether a challenge is required to complete authentication. For example, regional mandates.

Possible Values:

Y - Challenge Required

N - Challenge Not Required

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

3DS 2.0

DecoupledIndicator

Indicates whether the 3DS Requestor requests the ACS to utilise Decoupled Authentication and agrees to utilise Decoupled Authentication if the ACS confirms its use.

Possible Values: 

Y - Decoupled Authentication is supported and preferred if challenge is necessary

N - Do not use Decoupled Authentication

Default Value: N

NOTE: If the element is not provided, the expected action is for the ACS to interpret as N, DO NOT use Decoupled Authentication.  Decoupled authentication is not supported at this time.

3DS 2.0

CardholderInfo

Data returned from issuer for display to consumer.

3DS 2.0

StatusReason

Provides additional information as to why the PAResStatus has the specific value. 

NOTE: Required for Payment (e.g. Authentication Indicator equals 01 on Lookup Request) transactions when PAResStatus is equal to N, U, or R in the Lookup Response.  Please refer to "EMV 3-D Secure Protocol and Core Functions Specification v2.2.0" for a list of Reason Codes.

3DS 2.0

WhiteListStatus

Enables the communication of trusted beneficiary/trustlist status between the ACS, the DS and the 3DS Requestor.

Possible Values: 

Y - 3DS Requestor is trustlisted by cardholder

N - 3DS Requestor is not trustlisted by cardholder

E - Not eligible as determined by issuer

P - Pending confirmation by cardholder

R - Cardholder rejected

U - Trustlist status unknown, unavailable, or does not apply

Note: This field may be returned for 2.1.0 if the MasterCard PSD2 extensions are passed and issuer supports them.

3DS 2.0

WhiteListStatusSource

This data element will be populated by the system setting WhiteListStatus.

Possible Values:

01 - 3DS Server

02 - DS

03 - ACS

3DS 2.0

ChallengeCancel

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.

3DS 2.0

InteractionCounter

Indicates the number of authentication cycles attempted by the cardholder and is tracked by the Issuing Banks ACS.  

3DS 2.0

SdkTransId

SDK unique transaction identifier that is generated on each new transaction.

Y

Sample Messages

1.0 cmpi_ab_lookup Response
<CardinalMPI> <Xid>6276495256496D586F39416236744A6644513230</Xid> <EciFlag>05</EciFlag> <PAResStatus>Y</PAResStatus> <Enrolled>Y</Enrolled> <ThreeDSVersion>1.0.2</ThreeDSVersion> <TransactionId>bvIRVImXo9Ab6tJfDQ20</TransactionId> <OrderId>8000567084002790</OrderId> <SignatureVerification>Y</SignatureVerification> <TransactionType>C</TransactionType> <ACSWindowSuppression>false</ACSWindowSuppression> <CardBin>400000</CardBin> <ErrorDesc/> <ErrorNo>0</ErrorNo> <CardBrand>VISA</CardBrand> <Cavv>000001016165990000000063456599104160173F</Cavv> </CardinalMPI>
2.1 cmpi_ab_lookup Response
<CardinalMPI> <TransactionType>C</TransactionType> <CardBrand>VISA</CardBrand> <CardBin>400000</CardBin> <Xid/> <AuthenticationType/> <CardholderInformationText/> <ChallengeRequired/> <TransactionId>mL13BbUCQrAI4kMd14f0</TransactionId> <Enrolled>Y</Enrolled> <SignatureVerification>Y</SignatureVerification> <ErrorNo>0</ErrorNo> <ErrorDesc/> <EciFlag>05</EciFlag> <ACSTransactionId>3d6d6095-72a6-4b03-b8e1-0d241dad23b0</ACSTransactionId> <PAResStatus>Y</PAResStatus> <OrderId>8000175679100928</OrderId> <ThreeDSVersion>2.1.0</ThreeDSVersion> <ACSWindowSuppression>false</ACSWindowSuppression> <DSTransactionId>2b1efc38-e883-43d4-850c-cd6c42e10ec7</DSTransactionId> <Cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</Cavv> <ThreeDSServerTransactionId>acd90c3b-52c7-4493-8c6a-57ddaf66e789</ThreeDSServerTransactionId> <ACSUrl/> </CardinalMPI>
2.2 cmpi_ab_lookup Response
<CardinalMPI> <TransactionType>C</TransactionType> <CardBrand>VISA</CardBrand> <WhiteListStatus>Y</WhiteListStatus> <CardBin>400000</CardBin> <Xid/> <WhiteListStatusSource>03</WhiteListStatusSource> <AuthenticationType/> <CardholderInformationText/> <ChallengeRequired/> <TransactionId>E4CJ7PniRTgYVwTUokn0</TransactionId> <Enrolled>Y</Enrolled> <SignatureVerification>Y</SignatureVerification> <ErrorNo>0</ErrorNo> <ErrorDesc/> <EciFlag>05</EciFlag> <ACSTransactionId>4e182d88-e407-4254-9b4c-e332012ecf90</ACSTransactionId> <PAResStatus>Y</PAResStatus> <OrderId>8000230101721245</OrderId> <ThreeDSVersion>2.2.0</ThreeDSVersion> <ACSWindowSuppression>false</ACSWindowSuppression> <DSTransactionId>fb4aaf48-7988-484d-a0c2-d217a617e1df</DSTransactionId> <Cavv>Y2FyZGluYWxjb21tZXJjZWF1dGg=</Cavv> <ThreeDSServerTransactionId>32c7be77-564f-4cdf-9ff2-2162fbd52807</ThreeDSServerTransactionId> <ACSUrl/> <DecoupledIndicator/> </CardinalMPI>