ORCA Configuration JSON Schema Definitions

• proxy (object) (Required):

  The proxy object contains all the settings required by the third party endpoint

  • authorization (object) (Required):

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

      • see Further Information section below for description of authentication types

    • 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: "passthrough":

      • headerName (string) (Optional):
        • The key of the header that contains the authorization data

    • 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 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.

  • 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):

    • An object containing all the logging rules for this type of API call.

    • 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

      • 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):

      • See requestMasks above

• actions (array) (Required):

  The actions object contains a list of actions to be executed as part of the request

  • 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:

      • headerName (string) (Optional):
        • The key of the header that contains the authorization data

    • 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.

  • type: "shieldconex"

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

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

    • 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 SCX 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
        • 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 request

  • type: "parser":

    • 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
        • 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.
        • See further Information section 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 the variable 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 auth either as a header or in the body.
• 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).
• serviceCode - The track service code e.g. 101
• discretionary - The track's discretionary data e.g. 123456789
• firstName - The cardholder's first name e.g. Jane
• surname - The cardholder's surname e.g. Smith
• 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

Decryptx® Request Configuration

headers: {
  "dpx-device-serial": "<deviceSerial>",
  "dpx-device-type": "<deviceType>",
  "dpx-payload": "<devicePayload>",
  "custom-header-test": "yes",
  "Authorization": "<authKey>",
  "Content-Type": "..."
},
body: "{ ... }"

HEADER PARAMS

• deviceSerial
  • The serial number of the device used to process the transaction
  • This field is optional as the decryption is optional to begin with, and even if Decryptx® is used, the payload might contain the serial number
• deviceType
  • The type of device used to process the transaction
  • This field is optional as the decryption is optional
• devicePayload
  • The device payload to be decrypted
  • This field is optional as the decryption is optional
• authKey
  • Auth token
  • https://developers.bluefin.com/decryptx/docs/basic-auth-guide
• Content-Type
  • "application/json" | "application/xml"

ShieldConex® Detokenization Request Configuration

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

HEADER PARAMS

• Authorization
  • Auth token
  • https://developers.bluefin.com/decryptx/docs/basic-auth-guide
• scx-bfid
  • The ShieldConex® BFID for payloads that contain ShieldConex® tokens for detokenization
• Content-Type
  • "application/json" | "application/xml"

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.