PayConexDecryptxShieldConexTECS Platform
Guides
Request SandboxContact Us

API Authentication

Suggest Edits

Overview

This section provides information for generating and using authentication headers for the ShieldConex® Orchestration API requests.

Below is the configuration code required by the ShieldConex® Manager to create a new ORCA configuration. See the Quickstart Guide on how to set this up, and the JSON Schema Definitions section for detailed explanations of each property.

🚧

Note

You can only use one authentication method at a time for your ORCA configurations under the same partner.

Also see ORCA Configuration JSON Schema Definitions and Authentication Types.

Proxy Authorization

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 Bluefin 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).

Visa HMAC-based Proxy Authentication

For merchants integrating payment terminals with the Visa Platform Connect (VPC) gateway via the Cybersource REST API—used as the proxy endpoint for ORCA's decrypted payload—we've introduced the hmac-vpc property. This property is used to authorize requests to the Cybersource REST API (which connects to the VPC Gateway), enabling secure communication with Visa APIs.

ORCA Configuration

ShieldConex® ORCA allows for automating this authorization step by specifying the following in the ORCA configuration.

📘

Proxy Target

In the following example, as proxy.target we are using the authorization service URL for test transactions. For the full list, please check out Cybersource | Developer | Endpoints for the REST API.

Since Cybersource, a Visa solution, uses its own specific way of generating HMAC headers, the same fields are required as part of an ORCA configuration.

For a head start and more information, refer to Cybersource | Developer | Construct Messages Using HTTP Signature Security

{
  "proxy": {
    "method": "post",
    "target": "https://apitest.cybersource.com/pts/v2/payments",
    "authorization": {
      "type": "hmac-vpc",
      "keyId": "{rest_api_shared_key_id}",
      "secretKey": "{rest_api_shared_secret_key}",
      "signableHeaders": [
        "host",
        "date",
        "request-target",
        "digest",
        "v-c-merchant-id"
      ]
    },
    "logSettings": {
      "requestMasks": [],
      "responseMasks": []
    }
  },
  "actions": [
    {
      "type": "parser",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "method": "decrypt",
      "deviceType": "generic",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.paymentInformation.card.number",
          "dataType": "string",
          "format": "pan",
          "instructionType": "substitution"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.paymentInformation.card.expirationMonth",
          "dataType": "string",
          "format": "expiryMonth",
          "instructionType": "substitution"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.paymentInformation.card.expirationYear",
          "dataType": "string",
          "format": "fullYear",
          "instructionType": "substitution"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.pointOfSaleInformation.trackData",
          "dataType": "string",
          "format": "rawTrack2",
          "instructionType": "substitution"
        }
      ]
    }
  ],
  "detailedAuditEndDate": "2025-05-17T08:19:41.575Z"
}

📘

proxy.authorization parameters

The keyId and secretKey properties are a Shared Secret Key Pair created from the Cybersource Business Center. For comprehensive examples and guides, see Cybersource | Developer | Create a Shared Secret Key Pair.

The signableHeaders property contains all the header fields that must be included in the signature hash.

Request Configuration

Finally, the ORCA API request configuration is put together in accordance with Cybersource | Developer | Payments | Process a Payment where the ORCA Decryptx® action from above processes and re-inserts the sensitive data such as card.number, card.expirationMonth, card.expirationYear,trackData. For more examples and details, check out PointConex Example Use Case | EMV Transaction Orchestration and API Examples.

Here is an example of an API request payload made against the ORCA configuration.

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

{
  method: "POST",
  headers: {
    "v-c-merchant-id": "{v-c-merchant-id}",
    "dpx-device-serial": "{deviceSerial}",
    "dpx-device-type": "{deviceType}",
    "dpx-payload": "{devicePayload}",
    "Authorization": "{authKey}",
    "Content-Type": "application/json",
  },
  body: {
    "clientReferenceInformation": {
      "code": "AUTH_001"
    },
    "processingInformation": {
      "capture": false,
      "commerceIndicator": "retail"
    },
    "paymentInformation": {
      "paymentType": {
        "name": "CARD",
        "subTypeName": "DEBIT"
      }
    },
    "orderInformation": {
      "amountDetails": {
        "totalAmount": "100.00",
        "currency": "USD"
      },
      "billTo": {
        "firstName": "Jane",
        "lastName": "Doe",
        "address1": "1 Market St",
        "locality": "San Francisco",
        "administrativeArea": "CA",
        "postalCode": "94105",
        "country": "US",
        "email": "[email protected]",
        "phoneNumber": "4158880000"
      }
    },
    "pointOfSaleInformation": {
      "entryMode": "swiped",
      "terminalCapability": 2,
      "trackData": ";0000000000000000=00000000000000000000?",
      "terminalID": "12345678"
    }
  }
}

Basic Authentication

📘

Note

Basic Authentication is recommended for testing purposes while in the staging or certification environment. The guide for generating this header for your ShieldConex® or Decryptx® partner can be found here.

First, you need to go to the partner's profile in ShieldConex® or Decryptx® and set API Security to Basic, as shown in the screenshot below.

API Security - Basic

API Security - Basic

Setting API Security to Basic determines that all the ORCA configurations and API calls under this specific partner account use Basic only.

ORCA Configuration

As we have set the authentication method to Basic, we must keep it consistent with the actions since we must authenticate against that ShieldConex® or Decryptx® partner. So the next step is to specify the type of authorization basic for your ORCA configuration actions.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Password",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Result.Secret",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "templateRef": "{templateRef}",
      "method": "tokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

In the case of Decryptx® Parser action, the username and password are the partnerId and partnerKey to the Decryptx® API. P2PE Manager must check Basic as the authentication method.

For example,

  "actions": [
    {
      "type": "parser",
      "authorization": {
        "type": "basic",
        "username": "{partnerID}",
        "password": "{partnerKey}"
      },
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "format": "pan",
          "dataType": "string",
          "default": "mydefault"
        }
      ]
    }
  ],

🚧

Note

Using passthrough for a parser action will result in Authentication required in the Orchestration Logs since it passes ShieldConex® partner credentials from the API request (that's required to use the ORCA) 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,

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

Request Configuration

For simplicity, we use the basic authentication header throughout all of the API Examples.

{
  method: "POST",
  headers: {
    "Authorization": "Basic dXNlcm5hbWUxMjM6cGFzc3dvcmQxMjIzMzQ0",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "4444333322221111"
    }
  }
}

📘

Added Sub-Partner Level API Authentication

In the ShieldConex v1.18.3 release, we extended API authentication capabilities allowing sub-partners to authenticate individually, providing improved flexibility and granular access control. This can be managed by a Partner Supervisor of the sub-partner's parent.

For more information, see ShieldConex Manager API | Hierarchy of Organizations.

HMAC Authentication

📘

Note

HMAC Authentication is recommended for the production environment.

ORCA Configuration

First, you need to go to the partner's profile in ShieldConex® or Decryptx® and set API Security to HMAC, as shown in the screenshot below.

API Security - HMAC

API Security - HMAC

Setting API Security to HMAC determines that all the ORCA configurations and API calls under this specific partner account use HMAC only.

For this HMAC authentication example, we use JSON tokenization to demonstrate how to put together the HMAC authentication header and use it in the request configuration in accordance with the HMAC Authentication Guide. If you have trouble generating the HMAC authentication header, see the script.

It's important to note that this header needs to be carefully generated and put together. Otherwise, you will receive an Authentication Required error message.

{
  "proxy": {
    "method": "post",
    "target": "{The target URL/IP Address}",
    "authorization": {
      "type": "passthrough"
    },
    "logSettings": {
      "requestMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Password",
          "pattern": "all"
        },
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "pattern": "all"
        }
      ],
      "responseMasks": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Result.Secret",
          "pattern": "all"
        }
      ]
    }
  },
  "actions": [
    {
      "type": "shieldconex",
      "authorization": {
        "type": "hmac",
        "username": "{partnerID}",
        "secret": "{BASE64_DECODED_KEY_FROM_PARTNER_ACCOUNT}"
      },
      "templateRef": "{templateRef}",
      "method": "tokenize",
      "model": "sync",
      "instructions": [
        {
          "transformationSource": "body",
          "transformationType": "jsonpath",
          "transformationPath": "$.Card.Track2",
          "fieldName": "scx_token_card_number"
        }
      ]
    }
  ]
}

Request Configuration

Below is the request configuration for your application, along with the POST URL. The {configReferenceID} variable is the reference generated from creating the above configuration via the ShieldConex® Manager.

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

{
  method: "POST",
  headers: {
    "Authorization": "Hmac username=\"WATERFORD\", nonce=\"1l5daa1ju1b7lmljc5p4nev0ve\",  timestamp=1489574949, response=\"7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac\"
",
    "Content-Type": "application/json",
  },
  body: {
    "Card" : {
      "Name" : "John Smith",
      "Password" : "supersecret",
      "Track2" : "4444333322221111"
    }
  }
}

🚧

Note

The generated HMAC_AUTH_HEADER can be used only once per API call.

Updated 10 days ago