Decryptx Payload Parser API
Version: 1.2.0
This page describes the Bluefin Parser's REST API Endpoints.
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).
Validate Partner
This endpoint allows a partner to validate their credentials to access the Decryptx API.
POST /api/v1/partner/validateThis 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 | Up to 50 character string that identifies this request for the partner. This is not required, but if provided, will allow detailed troubleshooting if there are any issues. It is highly recommended that this value be provided and unique for a partner for all requests ever made to the Decryptx API. This value will be returned in the response, whether successful or failed. |
If the API call was a success a JSON object is produced with the following properties.
| Property | Type | Description |
|---|---|---|
| success | Boolean | Signified if validation was successful or not. |
| reference | String | Up to 50 character string that identifies this request for the partner. This is not required, but if provided, will allow detailed troubleshooting if there are any issues. It is highly recommended that this value be provided and unique for a partner for all requests ever made to the Decryptx API. This value will be returned in the response, whether successful or failed. |
| 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. |
If the API call fails then an Decryptx Error object is sent in the response.
Validate Device
This endpoint allows a partner to validate that a device is correctly registered and is functioning correctly.
POST /api/v1/device/validateThis 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 | Up to 50 character string that identifies this request for the partner. This is not required, but if provided, will allow detailed troubleshooting if there are any issues. It is highly recommended that this value be provided and unique for a partner for all requests ever made to the Decryptx API. This value will be returned in the response, whether successful or failed. |
| serial | String | The serial number of the device. |
| firmware | String | The firmware version of the device as captured from the read. |
| clientId (optional) | 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. |
If the API call was a success a JSON object is produced with the following properties.
| Property | Type | Description |
|---|---|---|
| success | Boolean | Signified if validation was successful or not. |
| reference | String | Up to 50 character string that identifies this request for the partner. This is not required, but if provided, will allow detailed troubleshooting if there are any issues. It is highly recommended that this value be provided and unique for a partner for all requests ever made to the Decryptx API. This value will be returned in the response, whether successful or failed. |
| 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. |
If the API call fails then an Decryptx Error object is sent in the response.
Process Payload
Extracts parameters from a device payload and decrypts track data with the Decryptx service. Also extracts card data from the response and places it in a JSON object.
POST /api/v1/decrypt/parserThis 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, wisepad2 or phressiapad |
| 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. |
| iv (optional) | String | The initialisation vector (IV) that was used to encrypt the payload. Some devices may output an IV with the KSN and encrypted payload. |
| reference (optional) | String | Up to 50 character string that identifies this request for the partner. This is not required, but if provided, will allow detailed troubleshooting if there are any issues. It is highly recommended that this value be provided and unique for a partner for all requests ever made to the Decryptx API. This value will be returned in the response, whether successful or failed. |
| clientId (optional) | 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. |
If the API call was a success a JSON object is produced with the following properties.
| Property | Type | Description |
|---|---|---|
| success | Boolean | Signified if validation was successful or not. |
| reference | String | Up to 50 character string that identifies this request for the partner. This is not required, but if provided, will allow detailed troubleshooting if there are any issues. It is highly recommended that this value be provided and unique for a partner for all requests ever made to the Decryptx API. This value will be returned in the response, whether successful or failed. |
| 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. |
Decryptx Error Object
The following object is produced if any of the above API calls fail.
| Property | Type | Description |
|---|---|---|
| success | Boolean | The success value will always be false for failed API calls. |
| errCode | Integer | Pragmatic code for specific failure reason. |
| errMessage | String | A human readable error message. |
| messageId (optional) | String | A unique numeric identifier generated for each request. |
| reference (optional) | String | If a reference value was provided in the request, it will be returned in the response. |