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:

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.

  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

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

  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

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