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

Description

traceId

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

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

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

Description

reference

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

Description

reference

Request Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.

templateRef

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

Description

templateRef

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

when set to true the tokens aren't

reference

Request Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.

values

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

Description

bfid

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

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

Description

bfid

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

Request Reference. This is a reference value that Developers can use to track API requests and responses. It is solely for tracking purposes.

values

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"
        }]
    }
}

Did this page help you?