API Reference

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

Development vs Production

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

Bluefin protects our REST endpoints with an 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. It 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, e.g., 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, e.g., 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, e.g., PAN, CVV.
*tlv (optional)*	Object	*decrypted* (String) - String that represents the decrypted TLV.
*track2equivalent (optional)*	Object	*decrypted* (String) - String that represents the decrypted Track 2 equivalent value extracted from the device payload. *ascii* (String) - The decrypted Track 2 equivalent 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 Track 2 equivalent data in plain ASCII with the important information masked, e.g., 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 device payload. *EXPY* (String) - The expiration date extracted from the device payload in MMYY format. *CVV (optional)* (String) - The card verification value extracted from the device payload. *street (optional)* (String) - The house number extracted from the device payload if applicable from certain devices (e.g., IDTECH SREDKey device). *ZIP (optional)* (String) - The zip number extracted from the device payload if applicable from certain devices (e.g., IDTECH SREDKey device). *FirstName (optional)* (String) - The first name extracted from the device payload. *Surname (optional)* (String) - The surname (last name) extracted from the device payload. *ServiceCode (optional)* (String) - The service code extracted from the Track 1 or Track 2 data. *Discretionary (optional)* (String) - The discretionary data extracted from the Track 1 or Track 2 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"
}