References
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 instructions support it
- Using either
"jsonpath" | "xpath" | "regex"
requirestransformationSource
to be"body"
- Using
"key"
requirestransformationSource
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 examplekey
e.g."track2"
For more on
xpath
andjsonpath
, refer to JSONPath and XPath -
pattern
(enum) (Required):- See Further Information section below for supported masking patterns
-
-
responseMasks
(array):
-
-
-
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"
- Specifies the type of action, which can be either
-
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 isshieldconex
- This setting is required when the
-
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"
requirestransformationSource
to be"body"
- Using
"key"
requirestransformationSource
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 examplekey
e.g."track2"
For more on
xpath
andjsonpath
, 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 configurationpassthrough
- 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"
requirestransformationSource
to be"body"
- Using
"key"
requirestransformationSource
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 examplekey
e.g."track2"
For more on
xpath
andjsonpath
, 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 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=2212101123456789track2equivalentLower
- Track2 equivalent with a lower case d e.g. 4124939999999990d2212101123456789track2equivalentUpper
- Track2 equivalent with a lower case d e.g. 4124939999999990D2212101123456789rawTrack1
- Track1 with the sentinels e.g. %B4124939999999990^TEST/BLUEFIN^2212101123456789?Track1
- Track1 without the sentinels e.g. B4124939999999990^TEST/BLUEFIN^2212101123456789pan
- The card number e.g. 4124939999999990expiry
- The expiry month and year e.g. 1222expiryMonth
- The expiry month e.g. 12expiryYear
- The expiry year e.g. 22cvv
- The 3-character CVV (captured during keyed transactions on idtech).serviceCode
- The track service code e.g. 101discretionary
- The track's discretionary data e.g. 123456789firstName
- The cardholder's first name e.g. Janesurname
- The cardholder's surname e.g. SmithfirstNameAndSurname
- The cardholder's complete name. e.g. Jane SmithrawName
- 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
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
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.
Error Code | HTTP Response | Description |
---|---|---|
8001 | 500 | Internal Server Error/Unexpected Error |
8003 | 401 | Authentication Error |
8004 | 403 | Permission Denied Error |
Updated 2 months ago