PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

API Examples

Suggest Edits

📘

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

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 or 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 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 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: {
    "custom-header-test": "yes",
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "4444333322221111"
    }
  }
}

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 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. See the tokenization 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 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: {
    "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®

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 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 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}",
    "custom-header-test": "yes",
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "XXXXXXXXXXXXX"
    }
  }
}

As defined in the ORCA Configuration 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.

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 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 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: {
    "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

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 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. See the tokenization 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 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: {
    "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®

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

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

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 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 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: {
    "custom-header-test": "yes",
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: `{ "reference": "myref" }`
}

HMAC Authentication

ORCA Configuration

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA Configuration. See the Quickstart Guide for instructions 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 determines that all the ORCA Configurations and API calls under this specific partner account 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 in accordance with the HMAC Authentication Guide. If you have trouble generating the HMAC authentication header, see 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 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: {
    "custom-header-test": "yes",
    "Authorization": "{HMAC_AUTH_HEADER}",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "4444333322221111"
    }
  }
}

NOTE: the generated HMAC_AUTH_HEADER can be used only once per API call.

Updated about 1 month ago

What’s Next

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