API Authentication
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
parametersThe
keyId
andsecretKey
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
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 aparser
action will result inAuthentication 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 usepassthrough
for ashieldconex
action. However, it is possible to specifyheaderName
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
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