PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

Decryptx WebSockets API

Suggest Edits

WebSockets API offers real-time market data updates. WebSockets is a bidirectional protocol offering fast real-time data, helping you build real-time applications. The public message types presented below do not require authentication. Private-data messages can be subscribed on a separate authenticated endpoint.

📘

Note

  • All messages sent and received via WebSockets are encoded in JSON format.
  • Our WebSockets endpoint is designed for server to server communications. It should never be used on a frontend client.

Connection Details

In order to utilize Decryptx's WebSocket interface you have to connect to one of the following URLs. You are required to send a Basic Authentication header in the initial connection to our WebSocket endpoint. Note the connection

Certification Environment:

wss://secure-cert-ws.decryptx.com

Production Environment:

wss://secure-prod-ws.decryptx.com

Request Message Structure

Request JSON messages have the following properties:

PropertyDescription
traceIdtraceId is a unique ID that is sent in the response message. The client can use this value to match outgoing message with incoming messages. We recommend that the client use a guid to avoid collisions.
actionThis property indicates the action that the client wants to perform. Options include:
  • heartbeat
  • partner-validate
  • device-validate
  • decrypt
  • decrypt-EXT
payloadThe message payload containing the body of the message for the specific action.

Response Message Structure

Response JSON messages have the following properties:

PropertyDescription
traceIdtraceId is a unique ID that is sent in the response message. The client can use this value to match outgoing message with incoming messages. We recommend that the client use a guid to avoid collisions.
actionIndicates the action that was performed.
messageId A unique value generated by the system for the transaction. This value can be used on the portal to track an individual message.
success Indicates if the system was able to process the message.
payloadAn object with the result of the action performed. For failure it will contain an errorCode and message property that maps to the same action on the REST endpoints.

Sample Messages

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e43",
    "action": "decrypt",
    "payload": {
        "reference": "myRef",
        "serial": "0135100005",
        "hasCcData": "true",
        "decryptionParameters": {
            "encoding": "hex",
            "sequenceNumber": "FFFF9876540015400014",
            "cbcVector": "0000000000000000"
        },
        "encrypted": [
            {
                "name": "track1",
                "value": "39333239363936383435323836333236363836333936363239"
            }
        ]
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e43",
    "action": "decrypt",
    "messageId": "1201911201201321031626749",
    "success" : true,
    "payload": {
        "decrypted": [{
            "name": "track1",
            "value": "32353034363934393933353537383532333439373130313739"
        }]
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e43",
    "action": "decrypt",
    "messageId": "1201911201201321031626749",
    "success" : false,
    "errMessage" : "All values failed to decrypt",
    "errCode"    : 1303,
    "payload": {
        "decrypted": {
          "name"    : "track1",
          "failed"  : true,
          "message" : "No CC found in decrypted result",
          "code"    : 1406
       }
    }
}

Actions

Our WebSocket interface supports the following actions:

Heartbeat

At any point after the initial WebSocket handshake, the client can choose to send a PING (heartbeat message) to the server. If the connection to the server is still active and the heartbeat message is received, the server returns a PONG. You can use this to make sure that the client is still connected to the WebSocket.

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e48",
    "action": "heartbeat"
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e48",
    "action": "heartbeat",
    "messageId": "1202203181024092211390455",
    "success": true,
    "payload": {
        "timestamp": 1647599049551
    }
}

Partner Validate

This API call can be used by the Partner to test connectivity to the Decryptx platform. Upon proper authentication, a success is returned. This can be used by the Partner as an application PING.

The payload object has the following field:

PropertyDescription
referenceRequest Reference. This is a reference value that developers can use to track API requests and responses. It is solely for tracking purposes.
{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e48",
    "action": "partner-validate",
    "payload": {
        "reference": "myref"
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e49",
    "action": "partner-validate",
    "messageId": "1201911201201321031626749",
    "success" : true
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e49",
    "action": "partner-validate",
    "messageId": "1201911201201321031626749",
    "success" : false
}

Device Validate

This activity would be performed to validate that Decryptx recognizes a device. This can be used by a Partner to ensure the device is in the Decryptx system and provisioned correctly.

The payload object has the following field:

PropertyDescriptioin
referenceRequest Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.
serial The serial number of the device
{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e48",
    "action": "device-validate",
    "payload": {
        "reference": "myref",
        "serial": "0135100005"
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e48",
    "action": "device-validate",
    "messageId": "1201911201201321031626749",
    "success" : true
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e48",
    "action": "device-validate",
    "messageId": "1201911201201321031626749",
    "success" : false
}

Decrypt

Provides the ability to decrypt data.

The payload object has the following fields:

PropertyDescription
referenceRequest Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.
serial The serial number of the device
decryptionParameters An array of decryption parameters with the following values:

  • encoding - Encoding used for Encrypted Values and the Key Sequence Number. 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 Key Sequence Number in this format. The format specified here will be the return format of the decrypted data.
  • 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.
encrypted 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.
hasCcData A 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 is provided for for hasCcData flag, Decryptx defaults it to "1".
{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e43",
    "action": "decrypt",
    "payload": {
        "reference": "myRef",
        "serial": "0135100005",
        "hasCcData": "true",
        "decryptionParameters": {
            "encoding": "hex",
            "sequenceNumber": "FFFF9876540015400014",
            "cbcVector": "0000000000000000"
        },
        "encrypted": [
            {
                "name": "track1",
                "value": "39333239363936383435323836333236363836333936363239"
            }
        ]
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e43",
    "action": "decrypt",
    "messageId": "1201911201201321031626749",
    "success" : true,
    "payload": {
        "decrypted": [{
            "name": "track1",
            "value": "32353034363934393933353537383532333439373130313739"
        }]
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e43",
    "action": "decrypt",
    "messageId": "1201911201201321031626749",
    "success" : false,
    "errMessage" : "All values failed to decrypt",
    "errCode"    : 1303,
    "payload": {
        "decrypted": {
          "name"    : "track1",
          "failed"  : true,
          "message" : "No CC found in decrypted result",
          "code"    : 1406
       }
    }
}

Decrypt-EXT

This API endpoint is utilized in what Bluefin calls “P2PE Manager Only” mode. Here, the Partner is using their own Validated P2PE Solution to decrypt data. In this mode, the P2PE Manager acts as the P2PE system of record. All aspects of the P2PE Manager operate the same – but rather than the data being acquired from Bluefin’s decryption system, it is “posted” to P2PE Manager from an external source.

The payload object has the following fields:

PropertyDescription
referenceRequest Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.
serial The serial number of the device
decryptionParameters An array of decryption parameters with the following values:

  • encoding - Encoding used for Encrypted Values and the Key Sequence Number. 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 Key Sequence Number in this format. The format specified here will be the return format of the decrypted data.
  • 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.
encrypted Number of encrypted items.
decryptedNumber of decrypted items.
{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e48",
    "action": "decrypt-ext",
    "payload": {
        "reference": "myRef",
        "serial": "0135100005",
        "decryptionParameters": {
            "encoding": "base64",
            "sequenceNumber": "YplJAQAABgAAGg==",
            "cbcVector": "0000000000000000"
        },
        "encrypted": 5,
        "decrypted": 5
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e46",
    "action": "decrypt-ext",
    "messageId": "1201911201201321031626749",
    "success" : true,  
    "payload": {
        "bfid": "djE6MTIwMTkxMTIwMTIwMTMyMTAzMTYyNjc0OXwxYjIxNGU1MjQ4NDgxYjFlOTRmNjRhZTg5YWU0Njg3ZXx8",
        "values": [{
            "name": "scx_token_card_number",
            "value": "4444336487341111"
        }]
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e46",
    "action": "decrypt-ext",
    "messageId": "1201911201201321031626749",
    "success" : false
    "payload": {
        "errorCode": 1203,
        "message": "Not found"
    }
}

Updated over 2 years ago