API Examples
Please refer to the References page for Configuration help, explanations, and clarification
JSON Tokenization
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, 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",
"substitutions": [
{
"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 should be the reference generated from creating the above Proxy Configuration via the ShieldConex® Manager.
POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}
{
method: "POST",
headers: {
"custom-header-test": "yes",
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: {
"Card" : {
"Name" : "John Smith",
"Password" : "supersecret",
"Track2" : "4444333322221111"
}
}
}
JSON Detokenization
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, 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",
"substitutions": [
{
"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. You can find this tokeniztion request configuration below.
POST https://secure{-*}.shieldconex.com/api/tokenization/tokenize
{
method: "POST",
headers: {
"dpx-device-serial": "{deviceSerial}",
"dpx-device-type": "{deviceType}",
"dpx-payload": "{devicePayload}",
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: {
"reference": "myref",
"templateRef": "{templateRef}",
"values": [
{ "name":"scx_token_card_number", "value":"4444333322221111" }
]
}
}
Detokenization Request Configuration
Below is the request configuration for your application, along with the POST URL. The {configReferenceID}
variable should be the reference generated from creating the above Proxy Configuration via the ShieldConex® Manager.
POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}
{
method: "POST",
headers: {
"custom-header-test": "yes",
"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}"
}
}
}
JSON Decryptx®
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, 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}"
},
"substitutions": [
{
"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 should be the reference generated from creating the above Proxy 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}",
"custom-header-test": "yes",
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: {
"Card" : {
"Name" : "John Smith",
"Password" : "supersecret",
"Track2" : "XXXXXXXXXXXXX"
}
}
}
XML Tokenization
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, 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",
"substitutions": [
{
"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 should be the reference generated from creating the above Proxy Configuration via the ShieldConex® Manager.
POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}
{
method: "POST",
headers: {
"custom-header-test": "yes",
"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>`
}
XML Detokenization
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, 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",
"substitutions": [
{
"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. You can find this tokeniztion request configuration below.
POST https://secure{-*}.shieldconex.com/api/tokenization/tokenize
{
method: "POST",
headers: {
"dpx-device-serial": "{deviceSerial}",
"dpx-device-type": "{deviceType}",
"dpx-payload": "{devicePayload}",
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: {
"reference": "myref",
"templateRef": "{templateRef}",
"values": [
{ "name":"scx_token_card_number", "value":"4444333322221111" }
]
}
}
Detokenization Request Configuration
Below is the request configuration for your application, along with the POST URL. The {configReferenceID}
variable should be the reference generated from creating the above Proxy Configuration via the ShieldConex® Manager.
POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}
{
method: "POST",
headers: {
"custom-header-test": "yes",
"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>`
}
XML Decryptx®
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, 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}"
},
"substitutions": [
{
"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 should be the reference generated from creating the above Proxy 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}",
"custom-header-test": "yes",
"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>`
}
XML Decryptx® with Headers
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, 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}"
},
"substitutions": [
{
"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 should be the reference generated from creating the above Proxy Configuration via the ShieldConex® Manager. As opposed to 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}",
"custom-header-test": "yes",
"Authorization": "{authKey}",
"Content-Type": "application/xml",
"password": "supersecret",
"track2": "XXXXXXXXXXXXX"
},
body: `<?xml version="1.0" encoding="UTF-8"?>`
}
JSON Tokenization with Queries
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, 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": "parser",
"authorization": {
"type": "basic",
"username": "{partnerID}",
"password": "{partnerKey}"
},
"substitutions": [
{
"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 should be the reference generated from creating the above Proxy Configuration via the ShieldConex® Manager. As opposed to the other examples, we now pass payload data into the query of the url. In other words, this is a Url form encoded payload.
POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}?password=supersecret&track2=4444333322221111
{
method: "POST",
headers: {
"custom-header-test": "yes",
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: `{ "reference": "myref" }`
}
HMAC Authentication
Proxy Configuration
Below is the configuration code required by the ShieldConex® Manager when creating a new Proxy Configuration. See the Quickstart Guide on how to use this, and the JSON Schema Definitions section for detailed explanations of each property.
First, you need to go to the Partner's Profile in ShieldConex® or Decryptx® and set API Security to HMAC as shown in the screenshot below.
Setting API Security to HMAC requires both all the proxy configurations and API calls under the specific Partner Account to use HMAC only.
For this HMAC Authentication example, we use JSON Tokenization to demonstrate how to put together the HMAC Authentication header and use it in the request configuration according to HMAC Authentication Guide. If you have trouble generating the HMAC Authentication header, check out the script.
It's important to note that this header needs to be carefully generated and put together. Otherwise, you will receive an authentication required error message.
{
"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": "hmac",
"username": "{partnerID}",
"secret": "{BASE64_DECODED_KEY_FROM_PARTNER_ACCOUNT}"
},
"templateRef": "{templateRef}",
"method": "tokenize",
"model": "sync",
"substitutions": [
{
"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 should be the reference generated from creating the above Proxy Configuration via the ShieldConex® Manager.
POST https://proxy{-*}.shieldconex.com/api/v1/partners/{partnerID}/configurations/{configReferenceID}
{
method: "POST",
headers: {
"custom-header-test": "yes",
"Authorization": "{HMAC_AUTH_HEADER}",
"Content-Type": "application/json",
},
body: {
"Card" : {
"Name" : "John Smith",
"Password" : "supersecret",
"Track2" : "4444333322221111"
}
}
}
NOTE: The HMAC_AUTH_HEADER generated can be used only once per API call
Updated 14 days ago
Check out the References page for clarification on any of the above values.