ORCA Configuration JSON Schema Definitions

• proxy (object) (Required):

  The proxy object contains all the settings required by the third party endpoint and logSettings for the Orchestration Logs.

  • authorization (object) (Required):

    • type (enum) (Required) : "passthrough" | "basic" | "hmac"

      • see Further Information section below for description of authentication types

      • 🚧

        Note

        The difference between the proxy.authorization and authorization per action is that the proxy authorization is required of the target destination(payment processor) while an action requires a partner's credentials to tokenize/decrypt. In the case of ShieldConex®, a template reference that is under a certain partner. For Decryptx® action, it must use the separate authorization (P2PE Manager credentials).

        Alternatively, the developer can even pass additional headers as a way of custom authorization that is accepted by the target destination (in this case, the custom header must not be named authorization).

    • type: "passthrough":

      • The custom authorization header for the target destination.
      • With headerName provided, the authorization data (from it) is replaced for the Authorization header and passed through as such.
      • headerName (string) (Optional):
        • The key of the header that contains the authorization data for the passthrough.

    • type: "basic":

      • username (string) (Required):
        • partnerID - ID provided by Bluefin for access to the ShieldConex®/Decryptx® API
      • password(string) (Required):
        • partnerKey - API Key provided by Bluefin for access to the ShieldConex®/Decryptx® API. This value can be changed on request from the partner or by the partner via the Bluefin Manager

    • type: "hmac":

      • username (string) (Required):

        • partnerID - ID provided by Bluefin for access to the ShieldConex®/Decryptx® API

      • secret (string) (Required):

        • Hmac Secret - provided by Bluefin from ShieldConex®/Decryptx® Partner Account. It requires setting API Security to Hmac and Bluefin would give you the Hmac Secret and Base64 Decoded Key. It is the Base64 Decoded Key that is used by this field.

          

          Setting API Security to Hmac affects all the ORCA configurations under the specific Partner Account.

  • method (enum) (Required): "get" | "post" | "put" | "patch" | "delete"

    • Supported HTTP method for the Orchestration API

  • target (string) (Required):

    • The target URL or IP Address (the Payment Processor). May include the port.

  • logSettings (object) (Optional):

    • An object containing all the logging rules for this type of API call. This includes the request and response masks that go out to the proxy/target destination.

    • As mentioned above, these logSettings are specified for the Orchestration Logs.

    • requestMasks (array):

      • An array containing objects that specifiy the location of data within the incoming payload that should be masked. The object will also contain the masking pattern.

      • transformationSource (enum) (Required): "body | header | query"

        • The source of the data. The request or the response (responseMasks)

      • transformationType (enum) (Required): "jsonpath" | "xpath" | "key" | "regex"

        • Specifies the type of transformation, both masking and instructions support it
        • Using either "jsonpath" | "xpath" | "regex" requires transformationSource to be "body"
        • Using "key" requires transformationSource to be "header" | "query"

      • transformationPath (string) (Required):

        • The element within the payload to mask
        • jsonpath e.g. "$.Card.Track2"
        • xpath e.g. "//Card/Password/text()"
        • regex e.g. ".*" - the regular expression to the path to mask - this masks everything in the payload for example
        • key e.g. "track2"

        For more on xpath and jsonpath, refer to JSONPath and XPath.

      • pattern (enum) (Required):

        • See Further Information section below for Supported Masking Patterns.

    • responseMasks (array):

      • Based on the transformationPaths, responseMasks take the response of the target URL and masks it for the Orchestration Logs since the response data from the target URL is reinserted and proxied back to the source/client. These are configured in the same way as requestMasks. See requestMasks above.

• actions (array) (Required):

  📘

  Note

  The actions object contains a list of actions to be executed as part of the request. These actions can be driven by either ShieldConex® or Decryptx®. It is possible to have multiple actions in a row as long as your ORCA configuration transformationPaths don't conflict and are well-organized.

  • type (enum) (Required): "parser" | "shieldconex"

    • Specifies the type of action, which can be either "parser" or "shieldconex"

  • authorization (object) (Required):

    • type (enum) (Required) : "passthrough" | "basic" | "hmac"

    • passthrough:

      • Passes on the ShieldConex® partner credentials. For the exception of type: "parser", see Authentication Types.
      • headerName (string) (Optional):
        • The key of the header that contains the authorization data for the passthrough.

    • basic:

      • username (string) (Required):
        • partnerID - ID provided by Bluefin for access to the ShieldConex®/Decryptx® API
      • password(string) (Required):
        • partnerKey - API Key provided by Bluefin for access to the ShieldConex®/Decryptx® API. This value can be changed on request from the partner or by the partner via the ShieldConex® Manager

    • hmac:

      • username (string) (Required):

        • partnerID - ID provided by Bluefin for access to the ShieldConex®/Decryptx® API

      • secret (string) (Required):

        • Hmac Secret - provided by Bluefin from ShieldConex®/Decryptx® Partner Account. It would require setting API Security to Hmac and Bluefin would give you the Hmac Secret and Base64 Decoded Key. It is the Base64 Decoded Key that is used by this field.

          

          Setting API Security to Hmac affects all the ORCA configurations under the specific Partner Account.

  • logSettings (object) (Optional):

    • An object containing all the logging rules for the API call of an action. This includes the request and response masks that are used to mask ShieldConex® and Decryptx® operations.

    • As mentioned above, these logSettings are specified for the Orchestration Logs.

    • 🚧

      Warning

      For an action, this setting is optional and is intended for merchants/developers who already have a background in ShieldConex® and Decryptx® API services in order to properly set up the masking for maximum security according to their needs and the particular way they would like to adapt their logs. For that reason, by default an ORCA configuration masks all the sensitive data that is processed by these services.

      Before using this feature, we recommend consulting with our Bluefin Technical Team.

    • requestMasks (array):

      • An array containing objects that specifiy the location of data within the incoming payload that should be masked. The object will also contain the masking pattern.

      • transformationSource (enum) (Required): "body | header | query"

        • The source of the data. The request or the response (responseMasks)

      • transformationType (enum) (Required): "jsonpath" | "xpath" | "key" | "regex"

        • Specifies the type of transformation, both masking and instructions support it
        • Using either "jsonpath" | "xpath" | "regex" requires transformationSource to be "body"
        • Using "key" requires transformationSource to be "header" | "query"

      • transformationPath (string) (Required):

        • The element within the payload to mask
        • jsonpath e.g. "$.Card.Track2"
        • xpath e.g. "//Card/Password/text()"
        • regex e.g. ".*" - the regular expression to the path to mask - this masks everything in the payload for example
        • key e.g. "track2"

        For more on xpath and jsonpath, refer to JSONPath and XPath.

      • pattern (enum) (Required):

        • See Further Information section below for Supported Masking Patterns.

    • responseMasks (array):

      • Based on the transformationPaths, responseMasks take the response of the target URL and masks it for the Orchestration Logs since the response data from the target URL is reinserted and proxied back to the source/client. These are configured in the same way as requestMasks. See requestMasks above.

  • type: "shieldconex"

    • method (enum) (Required): "tokenize" | "detokenize"

      • This setting is required when the type of service is shieldconex

    • model (enum) (Required): "sync" (default: "substitution"):

      • The actions will be executed in order (linearly).

    • templateRef (string) (Required):

      • Template Reference. This is the unique alphanumeric string that is used to identify a template. The templateRef is created within the ShieldConex® Manager and can be found within the template details page of any template within the ShieldConex® Manager.

    • instructions (array) (Required):

      • An array of substitution configurations to apply to the incoming payload. Each entry will have a location for the substitution and the ShieldConex® token to use.

      • transformationSource (enum) (Required): "body | header | query"

        • The source of the data. The request or the response

      • transformationType (enum) (Required): "jsonpath" | "xpath" | "key" | "regex"

        • Specifies the type of transformation, both masking and instructions support it
        • Using either "jsonpath" | "xpath" | "regex" requires transformationSource to be "body"
        • Using "key" requires transformationSource to be "header" | "query"

      • transformationPath (string) (Required):

        • The element within the payload to replace with the tokenized/detokenized value. The pattern used is determined by the transformationType.
        • xpath e.g. "//Card/Password/text()"
        • jsonpath e.g. "$.Card.Track2"
        • regex e.g. ".*" - the regular expression to the path to mask - this masks everything in the payload for example
        • key e.g. "track2"

        For more on xpath and jsonpath, refer to JSONPath and XPath.

      • fieldName (string) (Required):

        • The system name of the ShieldConex® template field to which the value is mapped for tokenization/detokenization

          📘

          Note

          This field name is taken from the template created via the ShieldConex® Template Manager

          e.g. "scx_token_card_number"

      • instructionType (string) (Optional) (default: "substitution"):

        • substitution - tokenize or detokenize information and replace the source data in the payload, this is the default setting when the variable is not defined in the configuration
        • passthrough - tokenize without replacing any data in the payload and retrieve tokens asynchronously using the BFID returned in the response of the ORCA API request

  • type: "parser":

    • method (string) (Optional) (default: "decrypt"):

      • Decryptx® Parser type of action.

    • clientId (string) (Optional):

      • Identifier for partner client to which this device belongs. This value is configured by the partner when the device is provisioned and is optional. This parameter provides an additional level of uniqueness in case device serial numbers are not unique between manufacturers. It also provides a more detailed level of reporting as API usage can be reported to the Client level. All devices provisioned for a partner must have a unique combination of Serial Number and Client. If a partner does not wish to use a client identifier, all devices provisioned for that partner must have a unique Serial Number.

    • deviceType (string) (Optional):

      • The type of terminal that generated the payload to be decrypted. The value must be one of the following: generic, idtech, ingenico-ra1, ingenico-rba, miura, prima, verifone, wisepad, or wisepad2.

    • serialLocation (object) (Optional):

      • The serial number of the device that generated the payload. The serial number will be extracted, replaced, and forwarded to the target destination.

      • transformationSource (enum) (Required): "body | header | query"

        • The source of the data. The request or the response

      • transformationType (enum) (Required): "jsonpath" | "xpath" | "key" | "regex"

        • Specifies the type of transformation, both masking and instructions support it
        • Using either "jsonpath" | "xpath" | "regex" requires transformationSource to be "body"
        • Using "key" requires transformationSource to be "header" | "query"

      • transformationPath (string) (Required):

        • The element within the payload to replace with the decrypted serial value. The pattern used is determined by the transformationType.
        • xpath e.g. "//Card/Password/text()"
        • jsonpath e.g. "$.Card.Track2"
        • regex e.g. ".*" - the regular expression to the path to mask - this masks everything in the payload for example
        • key e.g. "track2"

        For more on xpath and jsonpath, refer to JSONPath and XPath.

    • instructions (array) (Required):

      • An array of polyfill configurations to apply to the incoming payload. Each entry should include:

        • Location: Location for the polyfill within the payload.
        • Format: See Further Information section below for format options.

      • transformationSource (enum) (Required): "body | header | query"

        • The source of the data. The request or the response

      • transformationType (enum) (Required): "jsonpath" | "xpath" | "key" | "regex"

        • Specifies the type of transformation, both masking and instructions support it
        • Using either "jsonpath" | "xpath" | "regex" requires transformationSource to be "body"
        • Using "key" requires transformationSource to be "header" | "query"

      • transformationPath (string) (Required):

        • The element within the payload to replace with the decrypted value. The pattern used is determined by the transformationType.
        • xpath e.g. "//Card/Password/text()"
        • jsonpath e.g. "$.Card.Track2"
        • regex e.g. ".*" - the regular expression to the path to mask - this masks everything in the payload for example
        • key e.g. "track2"

        For more on xpath and jsonpath, refer to JSONPath and XPath.

      • dataType (enum) (Required): "string" | "number" | "boolean"

        • The datatype to use when outputting the data.

      • default (string | null):

        • An optional value that can be set if a value is not present in the decrypted payload.

      • format (enum) (Required):

        • The format to use when substituting elements within the payload. This option also indicates the type of data that should be extracted from the Parser response for substitution.

          • Also see Decryptx® Parser API Reference.

        • See Supported PolyfillFormat Options below for format options.

      • instructionType (string) (Optional) (default: "substitution"):

        • substitution - decrypt information and replace the source data in the payload, this is the default setting when this option is not defined in the configuration

Further Information

Supported Payload Formats

• JSON
• XML
• Url form encoded

Authentication Types

• passthrough - The original incoming request contains the authorization either as a header or in the body. This option does not authenticate requests itself but forwards them to a back-end service that handles the authentication. Either way, if the authentication headers are invalid, the request will be rejected.

  • 🚧

    Note

    Using passthrough for a parser action will result in Authentication required in the Orchestration Logs since it passes ShieldConex® partner credentials from the request as opposed to the Decryptx® credentials. For the reason outlined, it is fine to use passthrough for a shieldconex action. However, it is possible to specify headerName as that header will be extracted for that action. For example,

    JSON

    {
      ...
      "actions": [
        {
          "type": "parser",
          "authorization": {
            "type": "passthrough",
            "headerName": "my-decryptx-header"
          },
        ...
      ],
      ...
    }
    

• basic - Add a basic auth header (config to be stored on server)

• hmac - add a hmac auth header (config to be stored on server)

Supported Masking Patterns

Masks affect Portal Orchestration Logs.

• all - The entire value will be masked.
• fourPlainFourMasked - Every four characters are masked.
• allButFirstSixLastFour - The middle is masked but the first six and last four characters are not.
• allButFirstOneLastFour - The middle is masked but the first character as well as the last four characters are not.

Supported PolyfillFormat Options

• rawTrack2 - The complete track2 payload containing the start and end sentinels. e.g. ;4124939999999990=2212101123456789?;

• track2 - Defined as PAN=EXP[CVV][serviceCode]?LRC, and is equal to rawTrack2 without the sentinels e.g. 4124939999999990=2212101123456789

• track2equivalentLower - Track2 equivalent with a lower case d e.g. 4124939999999990d2212101123456789

• track2equivalentUpper - Track2 equivalent with a lower case d e.g. 4124939999999990D2212101123456789

• rawTrack1 - Track1 with the sentinels e.g. %B4124939999999990^TEST/BLUEFIN^2212101123456789?

• track1 - Track1 without the sentinels e.g. B4124939999999990^TEST/BLUEFIN^2212101123456789

• pan - The card number e.g. 4124939999999990

• expiry - The expiry month and year e.g. 1222

• expiryMonth - The expiry month e.g. 12

• expiryYear - The expiry year e.g. 22

• cvv- The 3-character CVV (captured during keyed transactions on idtech).

• discretionary - The track's discretionary data e.g. 123456789

• firstName - The cardholder's first name e.g. Jane

• firstNameAndSurname - The cardholder's complete name. e.g. Jane Smith

• rawName - The cardholder's name as it appears on the track. e.g. TEST/BLUEFIN

Irreversible Tokenization and Time-Boxed Detokenization

These features can be turned on and off in the template configuration as shown below:

Irreversible Tokenization

This is turned on using a checkbox. If enabled, this allows the user to permanently prohibit the detokenization of any tokens created using this template. In tandem with our token idempotency, tokens can still be used to work with sensitive data by relying on parity.
For example, if a user enters a card number in a checkout and a token is generated, that token can be compared against other tokenized card numbers to find a match. If the tokens are identical, then we know that the card numbers were also identical. Technically, this type of tokenization can also be referred to as One-way encryption.

Time Token Activation and Deactivation

Token activation and deactivation offsets can be configured in the Detokenization Restrictions settings as well. There are two fields that enable this; the Active From and Active To dates. The Active From field controls the offset from tokenization until the token can be detokenized and the Active To field controls the time offset time from tokenization until the token can no longer be detokenized. Please note that these are not specific dates, but rather the amount of time that has passed since detokenization. The duration designated in the Active To field should always be greater than the Active From date.
These fields are set based on the format defined in ISO 8601. ISO 8601 Durations are expressed using the following format, where (n) is replaced by the value for each of the date and time elements that follow the (n):
P(n)Y(n)M(n)DT(n)H(n)M(n)S
Where:

• P is the duration designator (referred to as "period"), and is always placed at the beginning of the duration.
• Y is the year designator that follows the value for the number of years.
• M is the month designator that follows the value for the number of months.
• W is the week designator that follows the value for the number of weeks.
• D is the day designator that follows the value for the number of days.
• T is the time designator that precedes the time components.
• H is the hour designator that follows the value for the number of hours.
• M is the minute designator that follows the value for the number of minutes.
• S is the second designator that follows the value for the number of seconds.
  For example, P3Y6M4DT12H30M5S represents a duration of three years, six months, four days, twelve hours, thirty minutes, and five seconds.

In accordance with Active From and Active To, this feature also introduces new error messages and codes such as:

• 400 (Bad Request)
  • errMessage (string)
    • "Detokenization period start violated"
    • "Detokenization period end violated"
  • "errCode" (number)
    • 1403

Fundamental Request Configuration Header Detail

ORCA Decryptx® Request Configuration

headers: {
  "dpx-device-serial": "<deviceSerial>",
  "dpx-device-type": "<deviceType>",
  "dpx-payload": "<devicePayload>",
  "Authorization": "<authKey>",
  "Content-Type": "application/json"
},
body: "{ ... }"

Header Parameters

ORCA ShieldConex® Detokenization Request Configuration

headers: {
  "Authorization": "<authKey>",
  "scx-bfid": "<bfid>",
  "Content-Type": "application/json"
},
body: "{ ... }"

Header Parameters

Passing Additional Headers

If there are additional headers that you would like to pass onto the target destination (payment processor), the ShieldConex® Orchestration API makes it available so since additional headers are ignored as long as they are not part of the ORCA configuration. See ORCA Configuration with Headers.

For example, this custom-header-test is passed onto the target destination.

headers: {
  "Authorization": "<authKey>",
  "scx-bfid": "<bfid>",
  "custom-header-test": "yes",
  "Content-Type": "application/json"
},
body: "{ ... }"

Responses and Errors

Below is the error response in JSON format.

{
    "success": false,
    "code"   : 8001,
    "message": "Server error."
}

HTTP Responses

• 200 (Success)

  • Result (object)

  • a place to capture all the response data

    The body of the success response is usually dictated by the target URL.

• 400 (Bad Request)

  • success (boolean) (Required)

    • True for successful API calls, false for failed

  • message (string) (Required)

    • A human readable error message

  • code (int32) (Required)

    • Pragmatic code for specific failure reason.

• 500 (Internal Server Error)

  For a more detailed response, we recommend checking out the Orchestration Logs in the ShieldConex® Manager.

  • success (boolean) (Required)

    • True for successful API calls, false for failed

  • message (string) (Required)

    • A human readable error message

  • code (int32) (Required)

    • Pragmatic code for specific failure reason.

Error Codes

Below are the possible error codes returned by a call to the ShieldConex® Orchestration API.