Cardinal (cmpi) Messages

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:


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> '


<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


Field Name



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

Possible Values:

  • SHA-256

  • SHA-512


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.


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.


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.


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



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:

Base64(Hash(Timestamp + ApiKey))

SHA-256 Example Values

Milliseconds Since Epoch

Demo API Key





SHA-512 Example Values

Milliseconds Since Epoch

Demo API Key





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


Field Name



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


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


The EncryptedCardNumberParameters field is made up of four required values.

  1. 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

  1. The alias of the key


  • 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)

  1. 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




Transformation Used for Encryption

Passed in first Parameter of the EncryptedCardNumber Field

Transformation Used for Encryption

Passed in first Parameter of the EncryptedCardNumber Field