Table of Contents
Additional Information
API Key Usage
Centinel has added support for submitting requests using an API Key. In the past, a request was submitted using a MerchantId, ProcessorId, and TransactionPwd value within the request. In order to provide more flexibility with submitting requests and rotating keys, functionality has been added to support using an API Key when submitting requests. In place of the MerchantId, ProcessorId, and TransactionPwd fields, a request will instead be submitted with identifier, OrgUnit, Algorithm, Timestamp, and Signature fields.
NOTE: A client wanting to authenticate with Centinel using API Keys will need to do so on both the cmpi_lookup and cmpi_authenticate requests.
Field Name | Description |
---|---|
Algorithm | The hash algorithm that was used to generate the Signature for the request. Possible Values:
|
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 |
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 |
---|---|
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.
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
decrypted value
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)
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 |
---|---|
RSA/ECB/OAEPWithSHA1AndMGF1Padding | RSAOAEP1 |
RSA/ECB/OAEPWITHSHA-256ANDMGF1PADDING | RSAOAEP256 |
RSA/ECB/OAEPWITHSHA-384ANDMGF1PADDING | RSAOAEP384 |
RSA/ECB/OAEPWITHSHA-512ANDMGF1PADDING | RSAOAEP512 |
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 | 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== |