API Reference

This page describes the Bluefin Parser's REST API Endpoint.

Development vs Production

These examples use the Decryptx's certification environment. To evaluate your requests against the production environment replace the host cert-parser.decryptx.com with secure-parser.decryptx.com.

At Bluefin, we protect our REST endpoints with a IP address whitelist. If you would like to try the examples below please contact us to request access.

Headers

All API Endpoints support the following header.

Property Required Description
Authorization no Our APIs support a number of authentication methods, including: Transparent, Basic, Digest, HMAC, and RSA auth. Transparent authentication requires that a partner embeds their credentials (partnerId and partnerKey) in the body of the request. Basic, Digest, HMAC and RSA authentication require that partner's place an authorization header in the request. For more information on each authentication method check out our documentation

All API Endpoints consume and produce JSON data (Content-Type: application/json).

Process Payload

The Process Payload endpoint extracts parameters from a device payload and decrypts track data with the Decryptx service. Also parses the decrypted data and attaches the extracted data to the response object.

Request Path

POST /api/decrypt/parser

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.
deviceType enum The type of terminal that generated the payload to be decrypted. The value must be one of the following: generic, idtech, ingenico-ra1, ingenico-rba, miura, prima, verifone, wisepad, or wisepad2
devicePayload String The payment terminal's payload to be decrypted.
deviceSerial (optional) String The serial number of the device that generated the payload. This parameter is not required when decrypting IDTech payloads as they have the device serial number embedded.
ksn (optional) String The key sequence number (KSN) used to encrypt the payload. This parameter is not required when decrypting payloads from the IDTech or Ingenico devices as they embed the KSN in their payloads.
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.
clientId String Identifier for partner client that 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.

Response Object

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

Property Type Description
success Boolean Indicates if the decryption 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.
meta Object
  • device (String) - The manufacturer of the device that generated the payload.
  • serial (String) - The device serial number.
  • mode (String) - The payload's input mode, either keyed, swiped, or emv.
track1 (optional) Object
  • decrypted (String) - String that represents the decrypted track value which is extracted from the device payload.
  • ascii (String) - The decrypted track value converted to an ASCII string.
  • encoding (String) - The encoding of decrypted track data; either 'hex' or 'base64'.
  • length (Integer) - The length of the decrypted track after it is converted to ASCII.
  • masked (String) - The track data in plain ASCII with the important information masked. i.e. PAN, CVV.
track2 (optional) Object
  • decrypted (String) - String that represents the decrypted track value which is extracted from the device payload.
  • ascii (String) - The decrypted track value converted to an ASCII string. For swiped payloads this value will be (;5415244444444444=2212101123456789?).
  • encoding (String) - The encoding of decrypted track data; either 'hex' or 'base64'.
  • length (Integer) - The length of the decrypted track after it is converted to ASCII.
  • masked (String) - The track data in plain ASCII with the important information masked. i.e. PAN, CVV.
track3 (optional) Object
  • decrypted (String) - String that represents the decrypted track value which is extracted from the device payload.
  • ascii (String) - The decrypted track value converted to an ASCII string.
  • encoding (String) - The encoding of decrypted track data; either 'hex' or 'base64'.
  • length (Integer) - The length of the decrypted track after it is converted to ASCII.
  • masked (String) - The track data in plain ASCII with the important information masked. i.e. PAN, CVV.
tlv (optional) Object
  • decrypted (String) - String that represents the decrypted tlv.
track2equivalent (optional) Object
  • decrypted (String) - String that represents the decrypted track2equivalent value extracted from the device payload.
  • ascii (String) - The decrypted track2equivalent value converted to ASCII.
  • encoding (String) - The encoding of decrypted track data; either 'hex' or 'ascii'.
  • length (Integer) - The length of the decrypted track after it is converted to ASCII.
  • masked (String) - The track2equivalent data in plain ASCII with the important information masked. i.e. PAN, service code, discretionary.
keyed (optional) Object
  • decrypted (String) - String that represents the decrypted keyed value which is extracted from the device payload.
  • ascii (String) - The decrypted keyed value converted to an ASCII string. The format varies from device to device.
  • encoding (String) - The encoding of decrypted keyed data; either 'hex' or 'ascii'.
  • length (Integer) - The length of the decrypted track after it is converted to ASCII.
  • masked (String) - The track data in plain ASCII with some data masked.
extracted Object
  • PAN (String) - The Primary Account Number extracted from the devicePayload.
  • EXPY (String) - The Expiration Date extracted from the devicePayload in MMYY format.
  • CVV (optional) (String) - The Card Verification Value extracted from the devicePayload.
  • street (optional) (String) - The house number extracted from the devicePayload if applicable from certain devices (e.g., IDTECH SREDKey device).
  • ZIP (optional) (String) - The zip number extracted from the devicePayload if applicable from certain devices (e.g., IDTECH SREDKey device).
  • FirstName (optional) (String) - The First Name extracted from the devicePayload.
  • Surname (optional) (String) - The SurName (last name) extracted from the devicePayload.
  • ServiceCode (optional) (String) - The service code extracted from the track one or track two data.
  • Discretionary (optional) (String) - The discretionary data extracted from the track one or track two data.

cURL Example

curl 'https://cert-parser.decryptx.com/api/decrypt/parser' \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    -d '{ 
            "partnerId"     : "?????????",
            "partnerKey"    : "ef1ad938150fb15a1384b883a104ce70",
            "clientId"      : "bobs_burgers",
            "reference"     : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
            "deviceType"    : "ingenico-rba",
            "deviceSerial"  : "80612860",
            "devicePayload" : "54152444441612212101912TEST/BLUEFIN1B0B0229000000000000020114334787735642891651=726961371397062832AF86BB9DB92C98416AAB5BCA769D565A96C1E5C07F1D49A912C9919DBD3EA0661DF20CAC633BC330ECF753994278F50F56F7A2CE0C7212BAACFDED1632B98BE3EC8"
        }'

If your credentials are correct and you sent a valid payload you should see a response like the one below:

{
    "success"   : true,
    "messageId" : "1201703221545061032173045",
    "reference" : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
    "clientId" : "bobs_burgers",
    "meta": {
        "device" : "INGENICO",
        "serial" : "80612860",
        "mode"   : "swiped"
    },
    "track2": {
        "decrypted" : "34313532343434343434343434343432323132313031313233343536373839",
        "encoding"  : "hex",
        "length"    : 33,
        "ascii"     : ";5415244444444444=2212101123456789?",
        "masked"    : ";541524******4444=2212************?"
    },
    "extracted": {
        "PAN"       : "5415244444444444",
        "EXPY"      : "1222",
        "FirstName" : "BLUEFIN",
        "Surname"   : "TEST",
        "ServiceCode"   : "101",
        "Discretionary" : "123456789"
    }
}

Errors

{
  "success"    : false,
  "errMessage" : "Authentication Required.",
  "errCode"    : 3000,
  "reference"  : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
  "messageId"  : "1201607010104111033014010"
}

Did this page help you?