PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

API Examples

Suggest Edits

📘

Please refer to the References page for Configuration help, explanations, and clarification

JSONPath and XPath

Before looking at the API Examples, it is essential to know how JSONPath and XPath parse data from the payload. The ShieldConex® Proxy supports these, which can be specified with transformationType and transformationPath in the Proxy 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"

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

NPM libraries:

Online Evaluators:

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",
      "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 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",
      "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. 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}"
      },
      "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 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",
      "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 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",
      "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. 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}"
      },
      "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 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}"
      },
      "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 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}"
      },
      "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 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.

API Security - HMAC

API Security - HMAC

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",
      "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 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 8 months ago

What’s Next

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