Proxy 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 proxy configurations under the specific Partner Account.

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

  • Supported HTTP method for the Proxy 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 substitutions 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"
    • 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 proxy 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.

  • substitutions (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 substitutions 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"

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

• type: "parser":

  • substitutions (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 substitutions 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"
    • 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.

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 Proxy 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

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 Proxy 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® Proxy API.