PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

API Examples

Suggest Edits

📘

See the References page for configuration help, explanations and clarification.

Overview

This section introduces various ORCA configurations showcasing ShieldConex® and Decryptx® actions in practice. These actions are essential to understanding how ShieldConex® and Decryptx® work in combination with ShieldConex® Orchestration, offering maximum security and reducing PCI scope. For more guides, we suggest referring back to the ORCA Configuration Essentials and Introduction.

📘

Note

For simplicity, we use passthrough for proxy.authorization in all of the following examples.

JSONPath and XPath

Before looking at some API examples, it is essential to know how JSONPath and XPath parse data from the payload. ShieldConex® Orchestration supports these, and they are specified with transformationType and transformationPath in the ORCA configuration.

JSONPath is a tool for navigating and extracting data from JSON structures. It provides a concise and flexible syntax to access specific elements within JSON objects.

For example:

{
    "Card": {
        "Track2": "4444333322221111",
        "Password": "supersecret"
    }
}
  • $.Card.Track2 - where $ is the root object and . the child member operator
  • $.Card.Password - selects the value of the path - evaluates to "supersecret"

XPath, often used in conjunction with XML, is a query language for selecting nodes from an XML document. It is similar to JSONPath but only used in the context of XML.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<Card>
  <Name>John Smith</Name>
  <Password>supersecret</Password>
  <Track2>4444333322221111</Track2>
</Card>
  • //Card/Track2/text() - where // is the root of XML document, / the child member operator and text() the text content of the element - evaluates to "4444333322221111"

Below are some libraries that you can use as a tool or to sharpen up your understanding of JSONPath and XPath.

NPM libraries:

Online evaluators:

JSON Tokeniztion

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Password",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Result.Secret",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "templateRef": "{templateRef}",
      "method": "tokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above ORCA configuration via the ShieldConex® Manager.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID} 

{
  method: "POST",
  headers: {
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "4444333322221111"
    }
  }
}

📘

Note

If we look at our target destination, or the webhook - after the ShieldConex API tokenizes the data, this is the tokenized data that the target destination has accepted.

{
  "Card": {
    "Name": "John Smith",
    "Password": "supersecret",
    "Track2": "5850459886792406"
  }
}

In the response headers proxied back to us, we get the scx-tokenize-bfid that is later used for detokenization.

JSON Detokenization

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Password",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Result.Secret",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "templateRef": "{templateRef}",
      "method": "detokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

Tokenization Request Configuration

In order to run this detokenization example, something must first be tokenized. See the tokenization request configuration below.

POST https://secure{-*}.shieldconex.com/api/tokenization/tokenize

{
  method: "POST",
  headers: {
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "reference": "myref",
    "templateRef": "{templateRef}",
    "values": [
      { "name":"scx_token_card_number", "value":"4444333322221111" }
    ]
  }
}

🚧

Omit Flag

The tokenization API endpoint can also take the omit flag in the query parameters. For example,

POST https://secure{-*}.shieldconex.com/api/tokenization/tokenize?omit=1

The omit flag used in the tokenization API has had 2 options in the past - when set to 0, the tokens are returned in the response to the request, and when set to 1, the tokens would be cached by Bluefin to be retrieved asynchronously. The default value is 0 or false. We have added an additional option to set this value to 2, which will result in the tokens being returned in the response and cached by Bluefin for up to 1 hour.

Detokenization Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}

{
  method: "POST",
  headers: {
    "Authorization": "{authKey}",
    "scx-bfid": "{BFID}", // BLUEFIN ID RETURNED BY ABOVE TOKENIZATION CALL
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "{TOKENIZED_VALUE_FROM_ABOVE}"
    }
  }
}

📘

Note

If we look at our target destination, or the webhook - after the ShieldConex API detokenizes the data, the target destination accepts the detokenized data.

{
  "Card": {
    "Name": "John Smith",
    "Password": "supersecret",
    "Track2": "4444333322221111"
  }
}

JSON Decryptx®

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Password",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Result.Secret",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "parser",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "format": "pan",
          "dataType": "string",
          "default": "mydefault"
        }
      ]
    }
  ]
}

Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}

{
  method: "POST",
  headers: {
    "dpx-device-serial": "{deviceSerial}",
    "dpx-device-type": "{deviceType}",
    "dpx-payload": "{devicePayload}",
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "XXXXXXXXXXXXX"
    }
  }
}

📘

Note

As defined in the ORCA configuration instructions above, Track2 is replaced with the PAN data that Decryptx® extracts and decrypts from the device payload, which is then forwarded to the designated endpoint; that is, the payment processor. The decrypted payload accepted by the target destination looks something like the following:

{
  "Card": {
    "Name": "John Smith",
    "Password": "supersecret",
    "Track2": "4444333322221111"
  }
}

XML Tokenization

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Password/text()",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Track2/text()",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Result/Secret/text()",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "templateRef": "{templateRef}",
      "method": "tokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Track2/text()",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}

{
  method: "POST",
  headers: {
    "Authorization": "{authKey}",
    "Content-Type": "application/xml",
  },
  body: `<?xml version="1.0" encoding="UTF-8"?>
    <Card>
      <Name>John Smith</Name>
      <Password>supersecret</Password>
      <Track2>4444333322221111</Track2>
    </Card>`
}

📘

Note

After ShieldConex® tokenizes the payload data, the target destination receives the securely tokenized data in the following format.

<Card>
  <Name>John Smith</Name>
  <Password>supersecret</Password>
  <Track2>5850459886792406</Track2>
</Card>

In the response headers proxied back to us, we get the scx-tokenize-bfid that is later used for detokenization.

XML Detokenization

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Password/text()",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Track2/text()",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Result/Secret/text()",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "templateRef": "{templateRef}",
      "method": "detokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Track2/text()",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

Tokenization Request Configuration

In order to run this detokenization example, something must first be tokenized. See the tokenization request configuration below.

POST https://secure{-*}.shieldconex.com/api/tokenization/tokenize

{
  method: "POST",
  headers: {
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "reference": "myref",
    "templateRef": "{templateRef}",
    "values": [
      { "name":"scx_token_card_number", "value":"4444333322221111" }
    ]
  }
}

🚧

Omit Flag

The tokenization API endpoint can also take the omit flag in the query parameters. For example,

POST https://secure{-*}.shieldconex.com/api/tokenization/tokenize?omit=1

The omit flag used in the tokenization API has had 2 options in the past - when set to 0, the tokens are returned in the response to the request, and when set to 1, the tokens would be cached by Bluefin to be retrieved asynchronously. The default value is 0 or false. We have added an additional option to set this value to 2, which will result in the tokens being returned in the response and cached by Bluefin for up to 1 hour.

Detokenization Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}

{
  method: "POST",
  headers: {
    "Authorization": "{authKey}",
    "scx-bfid": "{BFID}", // BLUEFIN ID RETURNED BY ABOVE TOKENIZATION CALL
    "Content-Type": "application/xml",
  },
  body: `<?xml version="1.0" encoding="UTF-8"?>
    <Card>
      <Name>John Smith</Name>
      <Password>supersecret</Password>
      <Track2> {TOKENIZED_VALUE_FROM_ABOVE} </Track2>
    </Card>`

}

📘

Note

After ShieldConex® extracts and detokenizes the payload data, the target destination receives the detokenized data.

<Card>
  <Name>John Smith</Name>
  <Password>supersecret</Password>
  <Track2>4444333322221111</Track2>
</Card>

XML Decryptx®

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Password/text()",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Track2/text()",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Result/Secret/text()",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "parser",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Card/Track2/text()",
          "format": "pan",
          "dataType": "string",
          "default": "mydefault"
        }
      ]
    }
  ]
}

Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}

{
  method: "POST",
  headers: {
    "dpx-device-serial": "{deviceSerial}",
    "dpx-device-type": "{deviceType}",
    "dpx-payload": "{devicePayload}",
    "Authorization": "{authKey}",
    "Content-Type": "application/xml",
  },
  body: `
    <?xml version="1.0" encoding="UTF-8"?>
      <Card>
        <Name>John Smith</Name>
        <Password>supersecret</Password>
        <Track2>XXXXXXXXXXXXX</Track2>
      </Card>`
}

📘

Note

As defined in the ORCA configuration instructions above, Track2 is replaced with the PAN data that Decryptx® extracts and decrypts from the device payload, which is then forwarded to the designated endpoint; that is, the payment processor. The decrypted payload accepted by the target destination looks something like the following:

<Card>
  <Name>John Smith</Name>
  <Password>supersecret</Password>
  <Track2>4444333322221111</Track2>
</Card>

XML Decryptx® with Headers

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "header",
          "transformationType": "key",
          "transformationPath": "password",
          "pattern": "all"
        },
        {
          "transformationSource": "header",
          "transformationType": "key",
          "transformationPath": "track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "xpath",
          "transformationPath": "//Result/Secret/text()",
          "pattern": "all"
        },
        {
          "transformationSource": "header",
          "transformationType": "key",
          "transformationPath": "password",
          "pattern": "all"
        },
        {
          "transformationSource": "header",
          "transformationType": "key",
          "transformationPath": "track2",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "parser",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "instructions": [
        {
          "transformationSource": "header",
          "transformationType": "key",
          "transformationPath": "track2",
          "format": "pan",
          "dataType": "string",
          "default": "mydefault"
        }
      ]
    }
  ]
}

Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager. Unlike the other examples, we now pass payload data into headers.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}

{
  method: "POST",
  headers: {
    "dpx-device-serial": "{deviceSerial}",
    "dpx-device-type": "{deviceType}",
    "dpx-payload": "{devicePayload}",
    "Authorization": "{authKey}",
    "Content-Type": "application/xml",
    "password": "supersecret",
    "track2": "XXXXXXXXXXXXX"
  },
  body: `<?xml version="1.0" encoding="UTF-8"?>`
}

🚧

Note

Unlike the examples above, this time the target destination receives the decrypted data in the request headers.

JSON Tokenization with Queries

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager when creating a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "query",
          "transformationType": "key",
          "transformationPath": "password",
          "pattern": "all"
        },
        {
          "transformationSource": "query",
          "transformationType": "key",
          "transformationPath": "track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Result.Secret",
          "pattern": "all"
        },
        {
          "transformationSource": "query",
          "transformationType": "key",
          "transformationPath": "track2",
          "pattern": "all"
        },
        {
          "transformationSource": "query",
          "transformationType": "key",
          "transformationPath": "password",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "templateRef": "{templateRef}",
      "method": "tokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "query",
          "transformationType": "key",
          "transformationPath": "track2",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager. Unlike the other examples, we now pass payload data into the query of the URL. In other words, this is a URL from encoded payload.

POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}?password=supersecret&track2=4444333322221111

{
  method: "POST",
  headers: {
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: `{ "reference": "myref" }`
}

🚧

Note

Unlike the examples above, this time the target destination receives the tokenized data in the request query.

Updated 3 days ago

What’s Next

Check out the References page for clarification on any of the above values.