Decrypt P2PE Data

Decrypt P2PE data from a device using the Decrypt P2PE Data API endpoint.

A single call can decrypt up to 100 values. A success response will only be returned once all values are decrypted and all values to decrypt must belong to a single device.

In JSON, the encrypted property contains an array of objects with name/value properties indicating the values that are to be decrypted. The response will contain an array with the same names in the same order they were submitted and their corresponding decrypted values or individual error information if the data could not be decrypted. If at least one of the values can be decrypted, the overall response will indicate success, but an error code and message will be provided indicating that there were some failures.

The only case that no decrypted values will be returned is if the failure prevents even attempting the decryption of any of the values. The REST endpoint for this call is http://secure-cert.decryptx.com/api/decrypt.

Request Path

POST /api/decrypt

Request Object

This API consumes a JSON object with the following properties.

Property Type Description
partnerId String ID provided by Bluefin for access to the Decryptx API.
partnerKey String API Key provided by Bluefin for access to the Decryptx API. This value can be changed on request from the partner or by the partner via the Decryptx portal.
reference (optional) String A string (of up to 50 characters) that helps partners identify individual API calls. If provided, the value will be logged to the P2PE Manager where it can be used to troubleshoot technical issues. It is highly recommended that a unique value be used on each Decryptx API call. The reference value will be returned in the response body, whether the API call is successful or not.
serial String The serial number of the device.
firmware String The firmware version of the device as captured from the read.
clientId String Identifier for the partner client this device belongs to. This value is configured by the partner when the device is provisioned and is optional. This parameter provides an additional level of uniqueness in case device serial numbers are not unique between manufacturers. It also provides a more detailed level of reporting as API usage can be reported to the client level. All devices provisioned for a partner must have a unique combination of serial number and client. If a partner does not wish to use a client identifier, all devices provisioned for that partner must have a unique serial number.
hasCcData Int Validation flag, that indicates if data should be checked for credit card numbers. If hasCcData is "1" and the inbound data contains a credit card number or if the outbound data doesn’t contain credit card number the decrypt operation will fail. If "0", no checks will be performed on inbound and outbound data. If no value for hasCcData flag provided, Decryptx defaults it to "1".
decryptionParameters Object
  • sequenceNumber - Sequence number obtained from device in base 64 or hex encoded format. This value is typically required for DUKPT encryption/decryption. This parameter is optional and not required if the device does not generate a key sequence number (KSN).
  • cbcVector - Base64 or hex encoded initial vector obtained from device. This parameter is optional. It’s used in devices that implement 3DES Cipher Block Chaining (CBC) encryption with non-zero initial vector.
  • encoding - Encoding used for encrypted values and the KSN. This defaults to base64 if not specified. The allowed values for this are "base64" and "hex". Hex encoded values should be an even number of characters from 0-F where each 2 characters represent one byte. Most devices provided the encrypted values and KSN in this format. The format specified here will be the return format of the decrypted data.
encrypted Array An array of encrypted values, each entry must have the following properties:
  • name (String) - String identifier for the value to be decrypted. This name will be returned in the response so that values can be matched up. Additionally, the response array of decrypted values will be returned in the same order they were provided.
  • value - Base64 or hex encoded encrypted data retrieved from device.

Response Object

A successful API call outputs a JSON object with the following properties.

Property Type Description
success Boolean Indicates if validation was successful or not.
reference String A string (of up to 50 characters) that helps partners identify individual API calls. If provided, the value will be logged to the P2PE Manager where it can be used to troubleshoot technical issues. It is highly recommended that a unique value be used on each Decryptx API call. The reference value will be returned in the response body, whether the API call is successful or not.
messageId String Bluefin assigned unique identifier for each response from the Decryptx API. This can and should be stored for troubleshooting purposes. This will be 25 numeric characters.
code Integer Pragmatic code for specific failure reasons. The list of possible values for this is provided later in this section.
message StringHuman readable error message indicating why the call failed.
decrypted Array An array of decrypted values:
  • name (String) - String identifier for the value to be decrypted. This name will be returned in the response so that values can be matched up. Additionally, the response array of decrypted values will be returned in the same order they were provided.
  • value (String) - Base64 or hex encoded encrypted data retrieved from device.
  • failed (Boolean) - Identifies if the decryption of this object failed.
  • code (String) - Failure code.
  • message (String) - Human readable reason for the failure.

cURL Example

Below are an example request and example responses for successful decryption and partially successful decryption. You will receive a partially successful response if at least one of your decryptions succeeded, but others failed.

curl 'https://secure-cert.decryptx.com/api/decrypt' \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json'
    -d '{
         "partnerId"  : "?????????",
        "partnerKey" : "ef1ad938150fb15a1384b883a104ce70",
        "reference"  : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
        "serial"     : "541T112708",
        "clientId"   : "bobs_burgers",
        "hasCcData"  : "1",
        "decryptionParameters" : {
            "sequenceNumber" : "629949960E001D200037",
            "encoding"       : "hex"
        },
        "encrypted" : [
            {
                "name"  : "track1",
                "value" : "EF77ABC20DE782C48A88FBF25C59A6C7E21FD7E42D9A1C091F5FC8BBC1BF7DA89E2D8DB1AEB58A7318A79DDE4E59A5E7BD682FCAE9F6BBFD"
            },
            {
                "name"  : "track2",
                "value" : "7EF02FC12FD9864672B4DDAE562F4D6EDAB53D91A85A83964A3E4EA545AD7D6CAFBB9D6BB51016E4"
            }
          ]
        }'
//You will get a response object like the following if the decryption was a success
{
  "success"   : true,
 "reference"  : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
 "messageId"  : "1201607010051161022432609",
  "decrypted" : [
    {
      "name"  : "track1",
      "value" : "25423337303030303939393939393939305e544553542f424c554546494e5e323231323130313132333435363738393f2800000000000000"
    },
    {
      "name"  : "track2",
      "value" : "3b3337303030303939393939393939303d323231323130313132333435363738393f3f0000000000"
    }
  ]
}
{
  "success"   : true,
  "message"   : "One or more values were unable to decrypt, see items for details",
  "code"      : 1302,
  "reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
  "messageId" : "1201607010100381011190531",
  "decrypted" : [
    {
      "name"    : "track1",
      "failed"  : true,
      "message" : "Invalid hex string"
    },
    {
      "name"  : "track2",
      "value" : "3b3337303030303939393939393939303d323231323130313132333435363738393f3f0000000000"
    }
  ]
}

Support for hasCcData Validation

The hasCcData validation flag triggers Decryptx to check incoming and outgoing data for credit card numbers. If hasCcData is set to "1" and the inbound data contains a credit card number, or if the outbound data doesn’t contain credit card number, the decrypt operation will fail. If hasCcData is set to "0", no checks will be performed on inbound and outbound data. The default value is "1".

Some payment terminal manufacturers do not include a complete PAN in their P2PE data, instead they want you to combine a partial decrypted PAN with non-P2PE data in the payload to construct the complete PAN. It is not possible to set hasCcData to "1" when decrypting payloads from these devices. The following table outline device support for hasCcData:

MANUFACTURER DEVICE Cryptography MSR KEYED EMV NFC
ID Tech SecuRED 3DES/CBC 1 1 N/A N/A
ID Tech SREDKey 3DES/CBC 1 1 N/A N/A
Infinite Peripherals Prima M 3DES/CBC 1 N/A N/A N/A
Ingenico iPP310 BPS 0 0 0 0
Ingenico iPP320 BPS 0 0 0 0
Ingenico iPP350 BPS 0 0 0 0
Ingenico iSC250 BPS 0 0 0 0
Ingenico iSC Touch 250 BPS 0 0 0 0
Ingenico iSC Touch 480 BPS 0 0 0 0
Anywhere Commerce Nomad 2.0 3DES/CBC 1 N/A N/A N/A
BBPOS WisePad 3DES/CBC 1 N/A N/A N/A
Verifione MX915 3DES/CBC 1 1 0 0
Verifione MX925 3DES/CBC 1 1 0 0

Did this page help you?