ORCA Request and Response Actions

Overview

The primary and most common use case for ShieldConex Orchestration is achieving PCI compliance by protecting sensitive data throughout the payment processing flow, up to the point where it reaches the payment processor.

In many cases, the payment processor returns a response that includes sensitive data. ShieldConex ORCA proxies this data back to the client in order to complete the final essential step across all ShieldConex ORCA Use Cases.

While ORCA securely proxies back the response data over TLS, the response of the payment processor remains unchanged and if not safeguarded - it can increase the client's PCI scope.

To ensure that the client's applications never handle sensitive data under any circumstances, ShieldConex Orchestration offers expanded transformation capabilities, enabling more complete end-to-end processing and greater flexibility in how requests and responses are handled through your orchestration workflows.

This enables response-side protection and normalization workflows that previously required custom middleware or downstream system changes.

Request Actions vs Response Actions

To showcase this in practice and break down the key difference between requestActions and responseActions, let's set up an ORCA config with no responseActions.

ORCA Configuration

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

Tokenization Request Configuration

In order to run this detokenization example, let's put together a sample card number request and tokenize it via ShieldConex API.

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

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

ORCA Request

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

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

📘

Note

The requestActions take care of the encrypted data as far as processing and forwarding it to the payment processor.

In other words, the requestActions apply the substitution of the data and send it to the processor over TLS for authorization.

The following is the request that the payment processor receives.

JSON

{
  "Card": {
    "Number": "4444333322221111"
  }
}

ORCA Response

📘

Note

On the other hand, the ORCA API response is the response of the payment processor and remains unchanged.

As the following showcases, this response poses a high security risk as it contains sensitive data entering the merchant's environment.

{
  "Result": {
    "Secret": "mysecretvalue"
  }
}

Configuring and Using Response Actions

Configuring responseActions involves setting up a ShieldConex Template, typically with custom fields and using that template reference for the tokenize action of an ORCA responseActions.

This way, we ensure that no sensitive data of the payment processor response ever reaches our application environment.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "logSettings": {
      "requestMasks": [
        {
          "pattern": "all",
          "transformationPath": "$.Card.Number",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ],
      "responseMasks": [
        {
          "pattern": "all",
          "transformationPath": "$.Result.Secret",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ]
    },
    "authorization": {
      "type": "passthrough"
    }
  },
  "requestActions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "method": "detokenize",
      "templateRef": "{templateRef}",
      "instructions": [
        {
          "fieldName": "card_number",
          "transformationPath": "$.Card.Number",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ]
    }
  ],
  "responseActions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "method": "tokenize",
      "templateRef": "{templateRef}",
      "instructions": [
        {
          "fieldName": "scx_secret",
          "transformationPath": "$.Result.Secret",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ]
    }
  ]
}

📘

Note

For convenience, we excluded the ORCA request and jumped straight to the now-encrypted ORCA response.

If you want to check out the ORCA request for this configuration, refer back to ORCA Request above.

ORCA Response

Finally, our payment processor response is fully secured and is ready to be used on demand via ShieldConex APIs.

{
  "Result": {
    "Secret": "CRRbraNiADlsi"
  }
}

Response Headers

{
  "x-request-id": "fd1cf000-751c-4d35-97f8-92f0957a7857",
  "scx-tokenize-message-id": "1202601281409281222005960",
  "scx-bfid": 'djI6MTIwMjY..."
}

The bfid (Bluefin Identifier) is echoed back in the response headers as scx-bfid and ready to be used.

🚧

Note

To capitalize on PCI-scope reduction, this tokenized data is usually reused in another ShieldConex ORCA detokenize action. To see this use case in action, refer to API Examples | ORCA Detokenization.

It is also possible to detokenize the values via ShieldConex /api/tokenization/detokenize. However, this is not advised as the client is significantly increasing their PCI scope so the optimal approach is API Examples | ORCA Detokenization as just stated.

Conclusion

We can conclude that the difference between requestActions and responseActions is requestActions is the data that the payment process receives (outbound request) whereas responseActions is what the client receives from the payment processor (downstream response).

Both of these are sensitive so it is crucial that the client/merchant identifies and tracks down all the critical spots where sensitive data may enter their application environment, reducing their PCI scope and eliminating all high risk security threads.