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:
|
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"
}]
}
}
Updated 3 months ago