Example Use Cases
iframe-Based Secure Tokenization/Detokenization Processing
Start by creating a Template via the ShieldConex® Manager, specifying the fields you'd like to tokenize. Below is a sample payment form. Instructions for creating a Template like this can be found in the Quickstart Guide of the Getting Started page.
Screenshot of Example Payment Form
Next, create a Proxy Configuration, again using the ShieldConex® Manager. This will extract, detokenize, and proxy the data securely. Instruction for creating a Proxy Configuration is also detailed in the Quickstart Guide.
Proxy Configuration
{
"proxy": {
"method": "post",
"target": "{The target URL/IP Address}",
"authorization": {
"type": "passthrough"
},
"logSettings": {
"requestMasks": [
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CCN",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.Expiry",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CVV",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.BAN",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.RTN",
"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": "detokenize",
"model": "sync",
"instructions": [
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CCN",
"fieldName": "scx_token_card_number"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.Expiry",
"fieldName": "scx_token_card_expiration"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CVV",
"fieldName": "scx_token_card_verification"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.BAN",
"fieldName": "scx_token_bank_account_number"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.RTN",
"fieldName": "scx_token_bank_routing_number"
}
]
}
]
}
The client can then tokenize and retrieve sensitive data through the onToken iframe event, an example of which can be seen in the source code supplied below, on line 96 of the file PaymentFormScript.js. The tokens can then be read via the ShieldConex® tokenization service, by way of the CURL command given in the token-read.sh shell script below.
From this point on, the client will include these tokens, along with other necessary payload elements, in the data sent to the ShieldConex® Proxy. ShieldConex® then performs detokenization - seen in the given proxy-detokenize.sh shell script - and forwards the payload to the designated endpoint.
Check out the links below for the sample source code. As well as an example of a Payment Form, we have included a sample User Form example.
API-Based Tokenization and Detokenization Processing
For this example use case, the Proxy Configuration is set up to extract, detokenize, and proxy the data securely. Instructions for creating a Proxy Configuration are also detailed in the Quickstart Guide. An example of Proxy Configuration can be seen below.
To demonstrate this, we will use Track2 data such as CCN, EXP, CVV.
Proxy Configuration
{
"proxy": {
"method": "post",
"target": "{The target URL/IP Address}",
"authorization": {
"type": "passthrough"
},
"logSettings": {
"requestMasks": [
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CCN",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.Expiry",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CVV",
"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": "detokenize",
"model": "sync",
"instructions": [
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CCN",
"fieldName": "card_number"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.Expiry",
"fieldName": "card_exp"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CVV",
"fieldName": "card_cvv"
}
]
}
]
}
This example uses a simple local server with Express and SQLite3 to emulate how this process would work in a real-world use case.
First, the sensitive card data from a file we then tokenize and re-insert into the database. This "devalues" the sensitive data stored; The token and a BFID are returned for storage.
The token and a BFID returned for storage
Tokens and BFIDs reinserted into the database
To emulate the billing cycle, we setup the Process Payments that retrieves the ShieldConex token and BFID from storage and sends it to the ShieldConex Proxy for detokenization. The response is proxied back to the Client.
EMV Transaction Orchestration Use Case
For this example use case, the Proxy Configuration specifies that Decryptx® will extract and decrypt PAN, CVV, and Expiry, so we can process the transaction.
We are going to add additional payload elements such as transaction identifier, transaction amount and transaction currency - ShieldConex® Proxy leaves these untouched.
Proxy Configuration
{
"proxy": {
"method": "post",
"target": "{The target URL/IP Address}",
"authorization": {
"type": "passthrough"
},
"logSettings": {
"requestMasks": [
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.Expiry",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.PAN",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CVV",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Transaction.Amount",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Transaction.transactionId",
"pattern": "all"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Transaction.Currency",
"pattern": "all"
}
],
"responseMasks": [
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Result.Secret",
"pattern": "all"
}
]
}
},
"actions": [
{
"type": "parser",
"authorization": {
"type": "basic",
"username": "{partnerID_FROM_P2PEManager}",
"password": "{partnerKey_FROM_P2PEManager}"
},
"instructions": [
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.PAN",
"format": "pan",
"dataType": "string",
"default": "mydefault"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.CVV",
"format": "cvv",
"dataType": "string",
"default": "mydefault"
},
{
"transformationSource": "body",
"transformationType": "jsonpath",
"transformationPath": "$.Card.Expiry",
"format": "expiry",
"dataType": "string",
"default": "mydefault"
}
]
}
]
}
Request Configuration
{
method: "POST",
headers: {
"dpx-device-serial": "{deviceSerial}",
"dpx-device-type": "{deviceType}",
"dpx-payload": "{devicePayload}",
"Authorization": "{authKey}",
"Content-Type": "application/json",
},
body: {
"Card" : {
"PAN" : "XXXXXXXXXXXXX",
"CVV" : "XXX",
"Expiry" : "XXXX"
},
"Transaction": {
"Amount": "100",
"transactionId": "23",
"Currency": "EU"
}
}
}
Updated 5 months ago