Managing Templates

Overview

Templates are base configurations for safeguarding sensitive data online when it comes to CNP processing. These are defined in a form of field templates where we have a specific built-in template field type or a custom field that we want to tokenize. These templates are then referenced for tokenization via either IFrame SDK or ShieldConex API. Besides built-in template field types such as FieldTemplateCardDetails or FieldTemplateBankDetails, there are also the whole pre-built templates that we provide such as templatePayConexTokenization, templateMyChartAchTransaction, etc.

The ShieldConex Management API allows managing template entities via API requests whereas this was only possible via the ShieldConex Portal UI. If this is your first time working with the ShieldConex Templates, we recommend brushing up on Templates before diving into this section.

Make sure to check out the permissions for managing templates displayed in the hierarchy of User Roles in the Introduction.

As with the other sections, consult the API Reference for the comprehensive reference on various schemas, requests, and responses.

Creating Template

To create a template, both client and partner need to be specified. In some cases, even though the Client User Role can't view the partner, the correct partner of the client is required.

For reference, we recommend using uuid4 for a unique reference.

For example, in Python we have:

import uuid
templateRef = uuid.uuid4().hex

In the following example, we create a simple card template with a cvv and expirationDate fields enabled. In total, we have three fields in our template: Card Number, Card Expiration Date, and Security Code (CVV).

Request

POST /api/v1/templates

{
  "name": "templatetest02",
  "reference": "53b9334f9a8e44e2bd41193fd6265185",
  "active": false,
  "version": 0,
  "partner": {
    "id": 792,
    "name": "PartnerName"
  },
  "client": {
    "id": 744,
    "name": "Test Client"
  },
  "accessMode": "unrestricted",
  "type": "userDefined",
  "fieldTemplates": [
    {
      "key": "41b8f35e3d104c548f8fe839e7b26583",
      "templateType": "card",
      "method": "FPT",
      "width": "100",
      "sortOrder": 1,
      "required": true,
      "cardNumberFormat": "LAST_FOUR",
      "cardNumberName": "card_number",
      "cvvEnabled": true,
      "cvvName": "card_cvv",
      "expirationEnabled": true,
      "expirationName": "card_exp",
      "cardholderEnabled": false,
      "nonIdempotentTokens": false,
      "cardholderName": "card_holder",
      "cvvLabel": "label",
      "label": "Card Number",
      "cardNumberEnabled": true,
      "cardNumberLabel": "label",
      "expirationLabel": "label"
    }
  ]
}

Tokenization Field Names

cardNumberName, cvvName, and expirationName values are the names that are used in a tokenization/detokenization request so as to correctly process these fields and return Bluefin ID/detokenized data.

For example,

POST https://secure.shieldconex.com/api/tokenization/tokenize?omit=1

{
  "reference":"myref",
  "templateRef":"53b9334f9a8e44e2bd41193fd6265185",
  "values":[
    {"name":"card_number","value":"4444333322221111"},
    {"name":"card_exp","value":"1225"},
    {"name":"card_cvv","value":"1234"}
  ]
}

For the full API Tokenization Guide, refer to API Tokenization.

Request Parameters

Parameter	Type	Description
`reference`	`string`	A unique uuid4 value as the template reference
`accessMode`	`string`	The Template's access mode. TODO - provide description
`type`	`string`	The Template's type. These include `[ userDefined, templatePayConexTokenPayments, templatePayConexTokenization, templateMyChartCardTransaction, templateMyChartAchTransaction ]`. The `userDefined` option is when you need to create our own custom template from scratch. Other templates are Pre-Built Templates. See Create or Select a Template.
`fieldTemplates`	`array`	A single `fieldTemplate` varies based on your needs. For example, these include `FieldTemplateFieldDetails` (custom field), `FieldTemplateDateDetails`, `FieldTemplatePhoneDetails`, `FieldTemplateCardDetails`, `FieldTemplateAddressDetails`, `FieldTemplateEmailDetails`, `FieldTemplateBankDetails`, etc. For more, refer to API Reference.

`FieldTemplateCardDetails`

In the example above, we used this built-in template field type to demonstrate creating a basic card field.

Parameter	Type	Description
`key`	`string`	A unique uuid4 value as the field key
`templateType`	`string`	This parameter dictates what instance of `fieldTemplate` is used as listed above in `fieldTemplates`. In the case of `"card"`, the `FieldTemplateCardDetails` schema is applied.
`method`	`string`	enum: `[ FPE, FPT ]`. Format Preserving Encryption (FPE) & Format Preserving Tokenization (FPT). See Data Protection Method.
`width`	`string`	Iframe Setting: Field template's width in percents relativly to the whole parent area size.
`sortOrder`	`integer`	Field template's sort order. The integer value presents descending or ascending.
`required`	`boolean`	Field template's required.
`cardNumberFormat`	`string`	Specifies which part of the card number to display in the tokenized format. Options include: `[ NONE, LAST_FOUR, FIRST_SIX, FIRST_SIX_LAST_FOUR, FIRST_TWO_LAST_FOUR ]`.
`nonIdempotentTokens`	`boolean`	This parameter determines if different token values are generated for the same input value.
`label`	`string`	Iframe setting: the label displayed in the iframe field. Same goes for `cvvLabel`, `cardNumberLabel`, and `expirationLabel`.

Response

{
  "id": 7461
}

The API responds with the id of the newly created template.

Getting Templates

To get a summarized list of all templates including their ids, reference, version, accessMode , type, etc. This list doesn't include fieldTemplates as all of the meta-data is included by getting a single template.

Request

GET /api/v1/templates?partner=792&client=744

Response

{
  "total": 5,
  "data": [
    {
      "id": 6677,
      "name": "EMV Transaction Tokenization",
      "reference": "3de72d69906a4fe68700d68c73595f47",
      "active": false,
      "version": 5,
      "partner": {
        "id": 792,
        "name": "partnerName"
      },
      "client": {
        "id": 744,
        "name": "Test Client"
      },
      "accessMode": "unrestricted",
      "type": "userDefined"
    },
    {
      "id": 7873,
      "name": "PayConex Tokenization Template",
      "reference": "2f5a12c189c84fe7a037ac44a6f8c922",
      "active": false,
      "version": 1,
      "partner": {
        "id": 792,
        "name": "partnerName"
      },
      "client": {
        "id": 744,
        "name": "Test Client"
      },
      "accessMode": "unrestricted",
      "type": "templatePayConexTokenization"
    },
    {
      "id": 6536,
      "name": "Detokenize Example",
      "reference": "916519bd6c244f98a2d22bacd2112fcf",
      "active": false,
      "version": 12,
      "partner": {
        "id": 792,
        "name": "partnerName"
      },
      "client": {
        "id": 744,
        "name": "Test Client"
      },
      "accessMode": "unrestricted",
      "type": "templatePayConexTokenization"
    },
    {
      "id": 6549,
      "name": "Detokenize Example 2",
      "reference": "5788168a4d9f4695b8d7372da1afd9cd",
      "active": false,
      "version": 5,
      "partner": {
        "id": 792,
        "name": "partnerName"
      },
      "client": {
        "id": 744,
        "name": "Test Client"
      },
      "accessMode": "unrestricted",
      "type": "userDefined"
    },
    {
      "id": 7461,
      "name": "templatetest02",
      "reference": "53b9334f9a8e44e2bd41193fd6265185",
      "active": false,
      "version": 0,
      "partner": {
        "id": 792,
        "name": "partnerName"
      },
      "client": {
        "id": 744,
        "name": "Test Client"
      },
      "accessMode": "unrestricted",
      "type": "userDefined"
    }
  ]
}

Query Parameters

Parameter	Type	Required	Description
`partner`	`string/integer`	Yes	Filter the list by Partner. The parameter value can be either a Partner ID or Name.
`client`	`string/integer`	No	Filter by the Client. This helps narrow down the search of templates but it is not required.
`take`	`integer`	No ( Default: `10`)	The number of entries to include in the list. It starts from `skip`.
`skip`	`integer`	No ( Default: `0` )	The number of results to skip before listing entries.

Getting Template

To get all the meta-data of a template, the id must be included in the path.

Request

GET /api/v1/templates/{id}

📘
Note
In the following example, we replace {id} with 6677.

Response

{
  "id": 6677,
  "name": "EMV Transaction Tokenization",
  "reference": "3de72d69906a4fe68700d68c73595f47",
  "active": false,
  "version": 5,
  "partner": {
    "id": 792,
    "name": "partnerName"
  },
  "client": {
    "id": 744,
    "name": "Test Client"
  },
  "accessMode": "unrestricted",
  "type": "userDefined",
  "created": "2024-04-29T13:46:07.000Z",
  "modified": "2024-04-29T14:11:53.000Z",
  "fieldTemplates": [
    {
      "key": "bb864c05b62e4f7eb98b9e76a6f162bf",
      "templateType": "card",
      "method": "FPT",
      "width": "100",
      "sortOrder": 1,
      "required": true,
      "cardNumberFormat": "NONE",
      "cardNumberName": "card_number",
      "cvvEnabled": true,
      "cvvName": "card_cvv",
      "expirationEnabled": true,
      "expirationName": "card_exp",
      "cardholderEnabled": false,
      "cardholderName": "card_holder"
    },
    {
      "key": "736069df55c34ab1beaf0369b3205e31",
      "templateType": "field",
      "method": "FPT",
      "width": "100",
      "sortOrder": 2,
      "required": true,
      "name": "amount",
      "format": "NONE",
      "alphabet": "CARD10",
      "label": "Amount",
      "nonIdempotentTokens": false,
      "inputType": "input",
      "minLength": 2,
      "maxLength": 128,
      "pattern": "[0-9-@_:%/+! ().;,']+",
      "patternMessage": "Invalid format"
    },
    {
      "key": "6ab0c185acef4dcca6fd3f635aa2780f",
      "templateType": "field",
      "method": "FPT",
      "width": "100",
      "sortOrder": 3,
      "required": true,
      "name": "transaction_id",
      "format": "NONE",
      "alphabet": "CARD10",
      "label": "Client Transaction Id",
      "nonIdempotentTokens": false,
      "inputType": "input",
      "minLength": 2,
      "maxLength": 128,
      "pattern": "[0-9-@_:%/+! ().;,']+",
      "patternMessage": "Invalid format"
    },
    {
      "key": "9ecf27c78da64769870846061f2f09cc",
      "templateType": "field",
      "method": "FPT",
      "width": "100",
      "sortOrder": 4,
      "required": true,
      "name": "currency",
      "format": "NONE",
      "alphabet": "CARD26",
      "label": "Currency",
      "nonIdempotentTokens": false,
      "inputType": "input",
      "minLength": 2,
      "maxLength": 128,
      "pattern": "[[email protected]_:%/+! ();,']+",
      "patternMessage": "Invalid format"
    }
  ],
  "options": {
    "domains": []
  }
}

In this response example, the templateType of "field" is shown, representing a custom field we defined for an EMV transaction where additional data needs tokenization. There are also more fields such as minLength, maxLength, pattern, patternMessage. For more, refer to Creating Template and API Reference.

Cloning Template

As documented in the Templates section, Cloning a Template is the exact copy of the template except for the following:

The TemplateRef will be different
The name will change based on what you specified in the dialog
The template will be unpublished

This functionality simplifies the process when you need most fields and settings to match your newly created instance, allowing for safe updates or faster creation of new templates based on existing ones. It's useful for both testing and production purposes.

Request

POST /api/v1/templates/{id}/clone

📘
Note
Where id is the id of a template to clone.

{
  "name": "ClonedTemplateName"
}

Response

{
  "id": 22
}

In response, we receive the id of the newly created "cloned" template.

For the response codes and bodies, check out API Reference.

Deleting Template

Request

DELETE /api/v1/templates/{id}

📘
Note
Where id is the id of a template to delete.

Responses

HTTP Response	Description
200	Template has been deleted successfully.
403	Permission denied.
404	Requested resource cannot be found.

Updating Template

Updating a template can involve changing partner or client, the existing fieldTemplates, adding new fieldTemplates, adding or changing domains to the while list of Domains for an Iframe.

Request

PATCH /api/v1/templates/{id}

📘
Note
Where id is the id of a template to update.

{
  "name": "templatetest02",
  "reference": "53b9334f9a8e44e2bd41193fd6265185",
  "active": false,
  "version": 0,
  "partner": {
    "id": 792,
    "name": "PartnerName"
  },
  "client": {
    "id": 744,
    "name": "Test Client"
  },
  "accessMode": "unrestricted",
  "type": "userDefined",
  "fieldTemplates": [
    {
      "key": "41b8f35e3d104c548f8fe839e7b26583",
      "templateType": "card",
      "method": "FPT",
      "width": "100",
      "sortOrder": 1,
      "required": true,
      "cardNumberFormat": "LAST_FOUR",
      "cardNumberName": "card_number",
      "cvvEnabled": true,
      "cvvName": "card_cvv",
      "expirationEnabled": true,
      "expirationName": "card_exp",
      "cardholderEnabled": false,
      "nonIdempotentTokens": false,
      "cardholderName": "card_holder",
      "cvvLabel": "label",
      "label": "Card Number",
      "cardNumberEnabled": true,
      "cardNumberLabel": "label",
      "expirationLabel": "label"
    },
    {
      "key": "ef6c3dc6d91c4d0ea57d1bf88251e425",
      "method": "FPE",
      "sortOrder": 0,
      "required": true,
      "width": "25",
      "templateType": "routing",
      "name": "string",
      "format": "NONE",
      "placeholder": "string",
      "label": "string"
    },
    {
      "key": "ea8456a1c57d4697aa54781caa4362c7",
      "method": "FPE",
      "sortOrder": 0,
      "required": true,
      "width": "25",
      "templateType": "bank",
      "name": "string",
      "format": "NONE",
      "placeholder": "string",
      "label": "string"
    }
  ],
  "options": {
    "customStyles": "string",
    "customStyleFile": "string",
    "domains": [
      "string"
    ]
  }
}

Response

{
  "id": 7461
}

In response, we get the id of the updated template.

See also

Tokenization Explained

Data Retrieval

Sharing Tokens

Creation Of Template

Managing Templates

Overview

Creating Template

Request

Tokenization Field Names

Request Parameters

`FieldTemplateCardDetails`

Response

Getting Templates

Request

Response

Query Parameters

Getting Template

Request

📘
Note

Response

Cloning Template

Request

📘
Note

Response

Deleting Template

Request

📘
Note

Responses

Updating Template

Request

📘
Note

Response

See also

Overview

Creating Template

Request

Tokenization Field Names

Request Parameters

FieldTemplateCardDetails

Response

Getting Templates

Request

Response

Query Parameters

Getting Template

Request

📘Note

Response

Cloning Template

Request

📘Note

Response

Deleting Template

Request

📘Note

Responses

Updating Template

Request

📘Note

Response

See also

`FieldTemplateCardDetails`

📘
Note

📘
Note

📘
Note

📘
Note