PayConexDecryptxShieldConex
Request SandboxContact Us

API Examples

Suggest Edits

📘

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.

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",
      "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 12 days ago

What’s Next

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