ShieldConex WebSockets API

WebSockets API offers real-time market data updates. WebSockets is a bidirectional protocol offering fastest 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.

We recommend that you send a heartbeat message at least once every 5 seconds in order to keep the connection alive and ensure that the service is responding.

Connection Details

In order to utilize ShieldConex'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.shieldconex.com

Production Environment:

wss://secure-ws.shieldconex.com

Request Message Structure

Request JSON messages have the following properties:

Property	Required	Type	Length	Description
traceId	Yes	String	0-255	traceId is a unique id that is sent in the response message. The client can use this value to match outgoing messages with incoming messages. We recommend that the client use a guid to avoid collisions.
action	Yes	Enum	-	This property indicates the action that the client wants to perform. Options include: heartbeat partner-validate template-validate tokenization-tokenize tokenization-read tokenization-detokenize
payload	Yes	JSON	No Limit Specified	The message payload contains the body of the message for the specific action.

Response Message Structure

Response JSON messages have the following properties:

Property	Description
traceId	The unique traceId that was sent in the request message.
action	Indicates 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.
payload	An 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-f79cb30f6e49",
    "action": "tokenization-tokenize",
    "payload": {
        "templateRef": "8e1580b8-12ea-4804-acaa-f9c922d124e6",
        "omit": false,
        "reference": "09420c55af7b",
        "values": [{
            "name": "scx_token_card_number",
            "value": "4444333322221111"
        }]
    }
}

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

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e49",
    "action": "tokenization-tokenize",
    "messageId": "1201911201201321031626749",
    "success" : false,
    "payload": {
        "errorCode": 1202,
        "message": "Template not found"
    }
}

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 ShieldConex 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:

Property	Required	Type	Length	Description
reference	No	String	1-255	Request 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
}

Template Validate

This activity would be performed to validate that ShieldConex recognises a partner’s template. This can be used by the Partner to ensure the template being referenced is in the ShieldConex system and provisioned correctly. The payload object has the following field:

Property	Required	Type	Length	Description
reference	No	String	1-255	Request Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.
templateRef	Yes	String	1-255	The template ref is a unique ID that specifies the template to be validated

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e47",
    "action": "template-validate",
    "payload": {
        "reference": "myref",
        "templateRef": "152a4e3f7f31f0a746388adbae1b47f5"
    }
}

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

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

Tokenize

Provides the ability to tokenize data. The payload object has the following fields:

Property	Required	Type	Length	Description
templateRef	Yes	String	1-255	Short for Template Reference. This is the unique alphanumeric string that is used to identify a template. The templateRef is created within ShieldConex Manager and can be found within the template details page of any template within ShieldConex Manager.
omit	No defaults to false	Boolean		When set to true, the tokens aren't returned in the response and must be collected via a subsequent `tokenization-read` request.
reference	No	String	1-255	Request Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.
values	Yes			JSON array containing the field names (and desired values) matching the fields configured inside of the template being referenced with templateRef.

{
    "action": "tokenization-tokenize",
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e47",
    "payload": {
        "templateRef": "152a4e3f7f31f0a746388adbae1b47f5",
        "omit": false,
        "reference": "myref",
        "values": [{
            "name": "scx_token_card_number",
            "value": "4444333322221111"
        }]
    }
}

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

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e49",
    "action": "tokenization-tokenize",
    "messageId": "1201911201201321031626749",
    "success" : false,
    "payload": {
        "errorCode": 1202,
        "message": "Template not found"
    }
}

Tokenization Read

This action is intended to be used to read data that was entered into a ShieldConex iFrame element (this cannot be used for API only transactions). The BFID that is created during a tokenization request is used to recall the data that was used is that request's payload. The response values would be tokenized. This activity can only be performed once per BFID. The payload object has the following fields:

Property	Required	Type	Length	Description
bfid	Yes	String	30-150	The BFID, or Bluefin ID, is the value that is created when a tokenization request is made (i.e., it is the value retrieved from an iFrame transaction, or a /tokenization/tokenize request). The BFID refers to that specific tokenization request and is necessary for tokenization and detokenization.
reference	No	String	1-255	Request Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.

{
    "action": "tokenization-read",
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e46",
    "payload": {
        "reference": "my_ref",
        "bfid": "djE6MTIwMTkxMTIwMTIwMTMyMTAzMTYyNjc0OXwxYjIxNGU1MjQ4NDgxYjFlOTRmNjRhZTg5YWU0Njg3ZXx8"
    }
}

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

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

Detokenize

This action provides the ability to detokenize data. The payload object has the following fields:

Property	Required	Type	Length	Description
bfid	Yes	String	30-150	The BFID, or Bluefin ID, is the value that is created when a tokenization request is made (i.e., it is the value retrieved from an iFrame transaction, or a /tokenization/tokenize request). The BFID refers to that specific tokenization request and is necessary for tokenization and detokenization.
reference	No	String	1-255	Request Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.
values	Yes			JSON array containing the field names (and desired values) matching the fields configured inside of the template being referenced with templateRef

{
    "action": "tokenization-detokenize",
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e45",
    "payload": {
        "reference": "my_ref",
        "bfid": "djE6MTIwMTkxMTIwMTIwMTMyMTAzMTYyNjc0OXwxYjIxNGU1MjQ4NDgxYjFlOTRmNjRhZTg5YWU0Njg3ZXx8",
        "values": [
            {
                "name": "scx_token_card_number",
                "value": "4444336487341111"
            }
        ]
    }
}

{
    "traceId": "b12be111-51a3-4b2e-b0bd-f79cb30f6e45",
    "action": "tokenization-detokenize",
    "messageId": "1201911201201321031626749",
    "succes" : true,
    "payload": {
        "values": [{
            "name": "scx_token_card_number",
            "value": "4444333322221111"
        }]
    }
}

📘Note

Connection Details

Certification Environment:

Production Environment:

Request Message Structure

Response Message Structure

Sample Messages

Actions

Heartbeat

Partner Validate

Template Validate

Tokenize

Tokenization Read

Detokenize

📘
Note