PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

API Reference

Suggest Edits

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.
luhnCheck Boolean A mathematical checksum used to validate standard card numbers once decrypted. Some specialised cards (e.g. EBT) don’t follow this rule, so the check can be toggled off when needed.

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.
  • ExpyRaw (optional) (String) - The expiry month and year (YYMM format) e.g. 2212. This enhances compatibility with specific ISO payment processors format
  • ExpiryMonth (optional) (String) - The expiry month e.g. 12
  • ExpiryYear (optional) (String) - The expiry year e.g. 22
  • ExpiryFullYear (optional) (String) - The full expiry year e.g. 2022
  • ServiceCode (optional) (String) - A 3-digit numeric code that tells how the card can be used.
  • FullName (optional) (String) - The full cardholder's name.
  • RawName (optional) (String) - The raw name extracted from the card payload.
  • Track1 (optional) (String) - The decrypted ASCII Track1 without the sentinels.
  • Track2 (optional) (String) - The decrypted ASCII Track2 data defined as PAN=EXP[CVV][serviceCode]?LRC.

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",
            "luhnCheck"     : false,
            "deviceType"    : "idtech",
            "deviceSerial"  : "541T112708",
            "devicePayload" : "029C01801F322400839B%*4124********9990^TEST/BLUEFIN^2212************?*;4124********9990=2212************?*6B8C6CAF90CA99315585BE485CFDAB1242477885E2BAE018FB3644140C1BEB5A4AE1731FFA5C2F37D186273BAC4B165EE7BA4F36E831945A9D7C5A9765F5E06933160B3A288670537EC6A37919555328E254D2033665F34BF5BD3BF0A1EAF1A40000000000000000000000000000000000000000000000000000000000000000000000000000000035343154313132373038629949960E001D200229629C03"
        }'

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" : "IDTECH",
        "serial" : "541T112708",
        "mode"   : "swiped"
    },
    "track1": {
        "decrypted": "2542343132343933393939393939393939305e544553542f424c554546494e5e323231323130313132333435363738393f3c000000000000",
    	"encoding": "hex",
    	"length": 50,
    	"ascii": "%B4124939999999990^TEST/BLUEFIN^2212101123456789?<",
    	"masked": "%*4124********9990^TEST/BLUEFIN^2212************?*"
    },
    "track2": {
        "decrypted": "3b343132343933393939393939393939303d323231323130313132333435363738393f3b00000000",
    	"encoding": "hex",
    	"length": 36,
    	"ascii": ";4124939999999990=2212101123456789?;",
    	"masked": ";4124********9990=2212************?*"
    },
    "extracted": {
        "PAN": "4124939999999990",
    	"EXPY": "1222",
    	"ExpyRaw": "2212",
    	"ExpiryMonth": "12",
    	"ExpiryYear": "22",
    	"ExpiryFullYear": "2022",
    	"ServiceCode": "101",
    	"Discretionary": "123456789",
    	"FirstName": "BLUEFIN",
    	"Surname": "TEST",
    	"FullName": "BLUEFIN TEST",
    	"RawName": "TEST/BLUEFIN",
    	"Track1": "B4124939999999990^TEST/BLUEFIN^2212101123456789",
    	"Track2": "4124939999999990=2212101123456789"
    }

}


Track 2 Equivalent Data

📘

Track 2 equivalent Data: Overview

A Track 2 equivalent is the data within an EMV chip card that replicates the information found on the magnetic stripe's Track 2, including the card number and expiration date, formatted as Tag 57 in the EMV transaction data. This data is included in online authorization requests and contactless transactions to allow for legacy system compatibility while maintaining security, as the equivalent data, especially the iCVV (chip card verification value), is chip-specific and not easily counterfeited.


There is an example of the device that parses and extracts the track2equivalent field, using a wisepad device model.

Request

curl 'https://cert-parser.decryptx.com/api/decrypt/parser' \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    -d '{ 
            "partnerId"     : "?????????",
            "partnerKey"    : "ef1ad938150fb15a1384b883a104ce70",
            "reference"     : "723f57e1-e9c8-48cb-81d9-547ad2b76435",
            "ksn"           : "02400810160051000027",
            "deviceSerial"  : "WPC204633000051",
            "deviceType"    : "wisepad2",
            "devicePayload" : "5EAC71D98947BD5AB362169B0394F122A22B6F6AF0401CF5F870AFCED8390172B526C6296B9DA7C1"

  }'

While it contains sensitive cardholder data, the iCVV (chip card verification value) makes the Track 2 equivalent data different from the magnetic stripe data, preventing its use for counterfeiting.

Response

{
  "success": true,
  "messageId": "1202509081307161222906335",
  "reference": "723f57e1-e9c8-48cb-81d9-547ad2b76435",
  "meta": {
    "device": "bbpos",
    "serial": "WPC204633000051",
    "mode": "swiped"
  },
  "track2equivalent": {
    "decrypted": "b5415244444444444d2212101123456789f800000000000000000000000000000000000000000000",
    "encoding": "ascii",
    "length": 36,
    "ascii": "b5415244444444444d2212101123456789f8",
    "masked": "b541524******4444d2212************f*"
  },
  "track2": {
    "decrypted": ";5415244444444444=2212101123456789?8",
    "encoding": "ascii",
    "length": 36,
    "ascii": ";5415244444444444=2212101123456789?8",
    "masked": ";541524******4444=2212************?*"
  },
  "extracted": {
    "PAN": "5415244444444444",
    "EXPY": "1222",
    "ExpyRaw": "2212",
    "ExpiryMonth": "12",
    "ExpiryYear": "22",
    "ExpiryFullYear": "2022",
    "ServiceCode": "101",
    "Discretionary": "123456789",
    "Track2": "5415244444444444=2212101123456789?8",
    "Track2Equivalent": "5415244444444444D2212101123456789"
  }
}


Security: Logging Best Practices

Our API responses include decrypted CHD, which must never be logged in plaintext. Logging these values can result in PCI DSS violations, data breaches, and legal consequences.

Key PCI DSS Requirements

RequirementSummary
3.3PAN must be masked when displayed (first 6 / last 4 digits).
3.4CHD must be rendered unreadable if stored or logged.
3.5.xCryptographic keys must be protected from misuse.

Below is a portion of an API response. It contains decrypted track data, PAN, expiry, and full cardholder name — all of which are considered CHD:

"track1": {
  "ascii": "%B4124939999999990^TEST/BLUEFIN^2212101123456789?",
  "masked": "%*4124********9990^TEST/BLUEFIN^2212************?*"
},
"extracted": {
  "PAN": "4124939999999990",
  "FullName": "BLUEFIN TEST",
  "Track1": "B4124939999999990^TEST/BLUEFIN^2212101123456789",
  "Track2": "4124939999999990=2212101123456789"
}

Do Not Log These Fields

FieldReasonAction
PANFull card number (CHD)Mask or exclude
Track1, Track2, Track2EquivalentDecrypted track data (CHD)Exclude
ExpiryMonth, ExpiryYear, ExpyRaw, EXPYCHDMask or exclude
ServiceCodeCHD componentMask or exclude
FullName, FirstName, Surname, RawNamePIIMask or exclude
devicePayloadEncrypted CHDExclude
partnerKeyAPI credentialExclude
ksnMay aid decryptionMask or exclude

🚧

Important

The combination of devicePayload, ksn, and partnerKey could be used to decrypt CHD. Logging these enables attack vectors if logs are leaked.

Recommendations

  • Disable request/response logging in production where not explicitly needed.
  • If logging is required for debugging, ensure redaction is applied to all sensitive fields.
  • Apply strict log access controls and retention policies.

Errors

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

Updated 8 days ago