Message Format

The Cardinal CMPI messages are expected to be sent in XML format using the www-form-urlencoded Content-Type. Your request should consist of a single parameter, cmpi_msg including the full URL encoded message (cmpi_lookup, cmpi_authenticate, etc).

CMPI Message curl Example:

Request:

curl -v -H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode cmpi_msg='
<CardinalMPI>
    <MsgType>cmpi_lookup</MsgType>
    <Version>1.7</Version>
    <TransactionType>C</TransactionType>
    <TransactionMode></TransactionMode>
    <DFReferenceId></DFReferenceId>
    <Algorithm></Algorithm>
	<Identifier></Identifier>
	<OrgUnit></OrgUnit>
	<Signature></Signature>
	<Timestamp></Timestamp>
    <OrderNumber></OrderNumber>
    <Amount></Amount>
    <CurrencyCode></CurrencyCode>
    <CardNumber></CardNumber>
    <CardExpMonth></CardExpMonth>
    <CardExpYear></CardExpYear>
    <BillingAddress1></BillingAddress1>
    <BillingCity></BillingCity>
    <BillingCountryCode></BillingCountryCode>
    <BillingFirstName></BillingFirstName>
    <BillingLastName></BillingLastName>
    <BillingPhone></BillingPhone>
    <BillingPostalCode></BillingPostalCode>
    <BillingState></BillingState>
    <ShippingAddress1></ShippingAddress1>
    <ShippingCity></ShippingCity>
    <ShippingCountryCode></ShippingCountryCode>
    <ShippingFirstName></ShippingFirstName>
    <ShippingLastName></ShippingLastName>
    <ShippingMethodIndicator></ShippingMethodIndicator>
    <ShippingPostalCode></ShippingPostalCode>
    <ShippingState></ShippingState>
    <ShippingAmount></ShippingAmount>
    <MobilePhone></MobilePhone>
    <Email></Email>
</CardinalMPI>
' https://centineltest.cardinalcommerce.com/maps/txns.asp

Response:

<CardinalMPI>
    <ErrorDesc></ErrorDesc>
    <ErrorNo></ErrorNo>
    <TransactionId></TransactionId>
    <Payload></Payload>
    <Enrolled></Enrolled>
</CardinalMPI>

API Key Usage

Authentication for Centinel API requests is facilitated through a Signature value, generated using an API Key. In the past, a request was submitted using a MerchantId, ProcessorId, and TransactionPwd value within the request; this integration is now non-standard and all merchants should adopt the Signature authentication model. In place of the MerchantId, ProcessorId, and TransactionPwd fields, a request will instead be submitted with Identifier, OrgUnit, Algorithm, Timestamp, and Signature fields. Descriptions and examples of these fields are listed below, and documentation on how to generate the Signature value can be located here.

NOTE: A client authenticating using the API Key Signature will need to do so on all CMPI messages, including both the cmpi_lookup and cmpi_authenticate requests.

Field Name	Description

Field Name	Description
Algorithm	The hash algorithm that was used to generate the Signature for the request. Possible Values: SHA-256 SHA-512
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.
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.
Signature	The signature for the request being submitted. This value is generated by hashing the combination of the Timestamp and the API Key. For additional information, please see the specific section on generating signature values.
Timestamp	The unix epoch time in milliseconds for the point in time that the request is generated. Example: `1467122891960`

Generating a Signature Value

All cmpi messages must send a Signature value identifying the origin of the request and permission to the API. The Signature is generated by concatenating the Unix Epoch Time in Milliseconds with the API Key, hashing the result, and then Base64 encoding the final result.

Typical Logic Format:

SHA-256 Example Values
Milliseconds Since Epoch	Demo API Key	Signature
1485534293321	13f1fd1b-ab2d-4c1f-8e2c-ca61878f2a44	X5TupwjjpO9hg5qIHG2h9aMCekWiqbYkzPkXkPopFMw=
SHA-512 Example Values
Milliseconds Since Epoch	Demo API Key	Signature
1485534293321	13f1fd1b-ab2d-4c1f-8e2c-ca61878f2a44	21rO7Y+71hmSJSiJ2O4zo7xnaVg6ALwA0KaWtrQiOJBfOFgTqZaV0+6deiemF8sWzlfaUGnUF1pX21QCXpHdMA==

Field Level Encryption

Cardinal has added field level encryption support for the CardNumber field within our API. To encrypt the CardNumber, the merchant will use a public key provided by Cardinal and provide the alias of the key when sending in the request to Cardinal. There are no specific libraries or .jars required to encrypt the CardNumber (in Java).

The two new fields added to our API are EncryptedCardNumber and EncryptedCardNumberParameters.

NOTE: If you are utilizing Field Level Encryption to protect the Card Number, the field CardNumber will not be required on the Lookup Request message.

Field Name	Description

Field Name

Description

EncryptedCardNumber

The EncryptedCardNumber is the Base64 encoded value of the encrypted bytes of the CardNumber using a 2048bit RSA key

Example:

<EncryptedCardNumber>SL1SK9dUn1zzwW3UuB0JvBL938ho4qr+nyUQ0J9ipWmQciV/CD+FUP1NDzi7u4mBMRscQPoL YznPiy+6D0uR5prGsBNZ4z+IfihD6rm6Rn7MkgSjj/+olGrNLm4F+2jfObWOmF3/pq/jrDvx ObQqQMN/vBsryEE/H7TCnFDmzxgyzZ4iGlaYEuUaLSoL3CYHpOq9a5gBNG1opmOATyDDjw3K fBmCGJShiiwI60NEysyAnlLWdKQQ6iGHx8oHV8YpF5Ex62xWSUYQcknB7ov83oJ61eJoixRz LFXJ22oXHcdPFz/eEBdQCLHBfN0/c+8H8C5G+/6rj36LHN/ykrbrhQ==</EncryptedCardNumber>

EncryptedCardNumberParameters

The EncryptedCardNumberParameters field is made up of four required values.

The transformation used

a. Cardinal currently supports the following flavors of OAEP outlined in the table below and requires the merchant to pass in specific values representing each one

Tip: If different values are passed in, Cardinal will be unable to decrypt the CardNumber

The alias of the key

SUBSTRING

Used to indicate that certain information should be ignored from the

decrypted value

Cardinal has a feature that allows the Merchant to specify a certain number of characters that should be truncated off the front of the card number after decryption
This tool is useful in situations where a merchant may be using an HSM to handle the card. At times, extra data could be included on the front of the card number when it is encrypted

Tip: SUBSTRING should be included even if the merchant has no need for this feature. In such an instance a “0” is passed as the fourth parameter (see table below)

The number of digits to be ignored from the decrypted value

If there is no need to utilize this feature, the merchant should pass in a “0”

NOTE: These values should be separated by semicolons (;) or colons (:). All values are required and must be presented in this specific order

Example:

<EncryptedCardNumberParameters>RSAOAEP1:testkeyalias;SUBSTRING:0</EncryptedCardNumberParameters>

Transformation Used for Encryption	Passed in first Parameter of the EncryptedCardNumber Field

Transformation Used for Encryption	Passed in first Parameter of the EncryptedCardNumber Field
RSA/ECB/OAEPWithSHA1AndMGF1Padding	RSAOAEP1
RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING	RSAOAEP256
RSA/ECB/OAEPWITHSHA-384ANDMGF1PADDING	RSAOAEP384
RSA/ECB/OAEPWITHSHA-512ANDMGF1PADDING	RSAOAEP512

Cardinal Centinel

Cardinal (cmpi) Messages

Message Format

API Key Usage

Generating a Signature Value

Field Level Encryption