ORCA Format Expressions

Overview

ORCA Format Expressions were introduced to provide a flexible, universal way to handle payment processor-specific message formatting requirements.

Many payment processors require messages to be delivered in a precise, proprietary format. To meet these requirements without limiting flexibility, ORCA includes a lightweight scripting language (called Format Expressions) that lets you dynamically transform and structure data - at runtime - exactly as your chosen payment processor expects.

As with all operations in ShieldConex® Orchestration, all transformations of sensitive data performed by ORCA Format Expressions take place and are executed entirely within Bluefin's PCI DSS compliant environment.

This feature effectively makes a wide range of polyfill formatting options available on demand, giving you powerful control over the final message payload while keeping your integration clean and maintainable.

📘

Note

Before checking out this page, make sure you are familiar with the following documentation in order to fully understand the purpose and target use case of Format Expressions:

• Introduction | PointConex Use Case
• Getting Started | Decryptx® Action
• PointConex Example Use Case | EMV Transaction Orchestration
• API Examples | JSON Decryptx®

Why ORCA Format Expressions?

While ShieldConex® tokenization and detokenization are already highly flexible, Format Expressions are specifically designed for Decryptx® actions.

This scripting language is most valuable when you need to:

• Extract a PCI-validated P2PE-encrypted payload from a terminal
• Parse, transform, and format the decrypted data based on the required criteria
• Forward the data to the payment processor in the exact format they require

This combination allows you to securely decrypt sensitive card data on the fly and deliver it in a processor-compliant message — all within a single orchestrated call.

Key Benefits

• Supports nested function calls with the standard string operations such as substring, concat, etc.
• Reduces custom code on your side
• Ensures compatibility with a wide variety of payment processors
• Maintains strong security by keeping sensitive operations within the ShieldConex / Decryptx environment

Using ORCA Format Expressions

The main use case of Format Expressions is in the ORCA configuration setup where the merchant can securely manipulate with the P2PE decrypted pieces of data.

These fields include the following supported polyfill references:

From an ORCA configuration, it is the formatExpression where the developer can securely reference and manipulate with this card data by referencing them as a function argument by field name.

Last Four Digits of the Card Number

ORCA Configuration

For example, here is how we can simply extract the last four digits of the pan, which is Primary Account Number/Card Number of the P2PE payload.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "logSettings": {
      "requestMasks": [
        {
          "pattern": "all",
          "transformationPath": "$.Card.PAN",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ],
      "responseMasks": [
        {
          "pattern": "all",
          "transformationPath": "$.Result.Secret",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ]
    },
    "authorization": {
      "type": "passthrough"
    }
  },
  "requestActions": [
    {
      "type": "parser",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "instructions": [
        {
          "format": "expression",
          "formatExpression": "substring(pan, 11, 4)",
          "dataType": "string",
          "instructionType": "substitution",
          "transformationPath": "$.Card.PAN",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ]
    }
  ]
}

📘

substring(...) Function Usage

If you are seeing the usage of the substring function for the first time, refer to substring(...) Function Usage below.

Request Configuration

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

{
  method: "POST",
  headers: {
    "dpx-device-serial": "{deviceSerial}",
    "dpx-device-type": "{deviceType}",
    "dpx-payload": "{devicePayload}",
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "PAN" : "XXXXXXXXXXXXX"
    }
  }
}

📘

Note

After Decryptx® extracts and decrypts the P2PE data from the device payload, the Format Expressions of the ORCA config are applied at runtime.

Then, ShieldConex® Orchestration reinserts and forwards the transformed data, securely over the TLS protocol, to the designated endpoint; that is, the payment processor. For the detailed workflow, make sure to examine the PointConex Use Case.

The decrypted payload accepted by the target destination is the following:

JSON

{
 "Card": {
   "PAN": "9999"
 }
}

Common Use Case: Formatting Expiration Date

One of the most frequent uses of ORCA Format Expressions is formatting the card expiration date to match the exact requirements of a specific payment processor.

Many processors expect the expiration date in a precise format (e.g., MMYY, MM/YY, YYYY-MM, or MMYYYY).

Using Format Expressions, you can easily transform the raw expiration data (typically provided as month and year) into the required string format without writing custom code on your side.

ORCA Configuration

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "logSettings": {
      "requestMasks": [
        {
          "pattern": "all",
          "transformationPath": "$.Card.PAN",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ],
      "responseMasks": [
        {
          "pattern": "all",
          "transformationPath": "$.Result.Secret",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ]
    },
    "authorization": {
      "type": "passthrough"
    }
  },
  "requestActions": [
    {
      "type": "parser",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "instructions": [
        {
          "format": "pan",
          "default": "mydefault",
          "dataType": "string",
          "instructionType": "substitution",
          "transformationPath": "$.Card.PAN",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        },
        {
          "format": "expression",
          "formatExpression": "concat(substring(expiryMonth, 0, 2), substring(fullYear, 2, 2))",
          "dataType": "string",
          "instructionType": "substitution",
          "transformationPath": "$.Card.Expiry",
          "transformationType": "jsonpath",
          "transformationSource": "body"
        }
      ]
    }
  ]
}

Request Configuration

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

{
  method: "POST",
  headers: {
    "dpx-device-serial": "{deviceSerial}",
    "dpx-device-type": "{deviceType}",
    "dpx-payload": "{devicePayload}",
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "PAN" : "XXXXXXXXXXXXX",
      "Expiry": "XXXX"
    }
  }
}

📘

Note

After Decryptx® extracts and decrypts the P2PE data from the device payload, the Format Expressions of the ORCA config are applied at runtime.

Then, ShieldConex® Orchestration reinserts and forwards the transformed data, securely over the TLS protocol, to the designated endpoint; that is, the payment processor. For the detailed workflow, make sure to examine the PointConex Use Case.

The decrypted payload accepted by the target destination is the following:

JSON

{
 "Card": {
   "PAN": "9999",
   "Expiry": "1222"
 }
}

You can easily adjust the expression to support other formats such as:

• MM/YY → "12/27"

  • JSON

    {
      "format": "expression",
      "formatExpression": "concat(expiryMonth, concat('/', expiryYear))"
    }

• MM-YYYY → "12-2027"

  • JSON

    {
      "format": "expression",
      "formatExpression": "concat(expiryMonth, concat('-', fullYear))"
    }

• YYYYMM →"202712"

  • JSON

    {
      "format": "expression",
      "formatExpression": "concat(fullYear, expiryMonth)"
    }

🚧

Note

If you are having trouble coming up with your desired formatExpression, please contact the Bluefin Integrations Team at [email protected].

substring(...) Function Usage

Signature

substring(string, start, length)

The substring() function extracts a portion of a string starting at a specified position and returns a string of the requested length.

Usage

The substring() function is available only when the JSON field has "format": "expression".

Parameters

Examples

Basic Usage

{
  "format": "expression",
  "value": "substring(pan, 0, 6)"
}

Nested Example | Used in Combination with concat

{
  "format": "expression",
  "formatExpression": "concat(substring(pan, 0, 6), concat('******', substring(pan, 12, 4)))"
}

Usage Notes

• The function is only evaluated when the field has "format": "expression". If used in a normal string field, it will be treated as literal text
• Negative start values are not supported.
• If start is beyond the length of the string, an empty string is returned
• If length exceeds the remaining characters, the function returns all characters from start to the end of the string
• String literals must be enclosed in single (') quotes
• Arguments can be field references, string literals, or nested function calls

concat() Function Usage

Signature

concat(value1, value2)

The concat() function joins exactly two strings into a single string.

If you have more than two strings to concatenate, you can capitalize on the nested expressions functionality as demonstrated in the examples below.

Availability

Just like the substring() function, the concat() function can only be used when the JSON field has "format": "expression". The actual expression must be provided in the sibling field "formatExpression".

Correct Structure:

{
  "fieldName": {
    "format": "expression",
    "formatExpression": "concat(...)"
  }
}

Examples

1. Basic concatenation | Formatting expiration date

{
  "format": "expression",
  "formatExpression": "concat(expiryMonth, concat('/', fullYear))"
}

2. Masking a PAN (common use case)

{
  "format": "expression",
  "formatExpression": "concat(substring(pan, 0, 6), concat('******', substring(pan, 12, 4)))"
}

Usage Notes

• concat() accepts exactly two arguments only
• To concatenate more than two values, you must nest multiple concat() functions
• String literals must be enclosed in single (') quotes
• Arguments can be field references, string literals, or nested function calls