Invoke Functions

Function Notation – The function region is defined as the area between four sets of curly brackets (i.e. {{{{FUNCTION_SPACE}}}}) including the curly brakcets.

To invoke a function, pass the required parameters as key value pairs within the function space. Once processed, the resulting data will completely replace the function space.

Encrypt

The encrypt function will detokenize the payload, encrypt the data within the “Data” parameter in the function space, and replace the function space with the resulting, encoded ciphertext, before forwarding the request to the specified URL. Currently, RSA encryption is supported.

Parameter Name	Value
FUNCTION	Encrypt
TYPE	RSA (only value supported currently)
KEY	Provide the public (RSA) key to be used for encryption
ENCODING	BASE64 or HEX (encodes ciphertext)
DATA	Data to be encrypted. This may include tokens located by token notation. If a token and/or a function is contained in the data parameter, the token will be detokenized prior to encryption.

Encrypt Example:

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: application/json
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey

{
    "card": {
        "type": "MC",
        "encryptedCardNumber":"{{{{FUNCTION:Encrypt,TYPE:RSA,KEY:-----BEGIN PUBLIC KEY-----MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAl+N3+1jgULXAtXdHCOGr0MQdgwP3NfDmyftD75nbjV44pHUeYA1LOrP7Pqaxnqdo2/rwa5IoWpaKchmILkSgZITkVuCgIUOx165axRuYId8WZFMrREtYw4wvs9f1uGqXhC8crS2/bLOBtB/qR5PneLRQhEobRG5YVkkUyorWHXmRKbvsiB/3G44AFcII3ifoE3y+L5wbAjbrra0H8qCKqsF88nS0JJcb7DKfFNCPjsdrcHq0Bv9fE8IvZ7H3zDS/GVqR4OLlNOxibAWkkd0IGNK2S2RObeP1OamXk6hRkoO5nEw5wuCcx711Tt3x7WaLgEly+Wgm26dxV4cEEwbaCwIDAQAB-----END PUBLIC KEY-----,ENCODING:HEX,DATA:{{{545454tEc3Hk5454}}}}}}}",
        "expDate": "1122",
        "cardValidationNum": "123"
    }
}

CVV

To utilize the CVV function, a CVV must have been previously associated to a PAN during the tokenization process and the CVV must not have been removed. If the CVV has been purged, this function will fail. In accordance with the PCI DSS, TokenEx will store the CVV for only a short period. After tokenization, the CVV will be available for up to 7 days, or until it is consumed by the CVV function in the Transparent Gateway API. If the TX_CacheCvv header is set to true, the CVV will be available for unlimited uses for five minutes starting after the first successful invocation of the CVV function.

Parameter Name	Value
FUNCTION	CVV
TOKEN	Token in which this CVV is associated

CVV Example

Content-Type: application/json
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey

{
	"card": {
		"type": "MC",
		"number": "{{{545454tEc3Hk5454}}}",
		"expDate": "1126",
		"cardValidationNum": "{{{{FUNCTION:CVV, TOKEN:545454tEc3Hk5454}}}}"
	}
}

Decrypt

The decrypt function can be used to pass encrypted data (as opposed to tokenized data) through Transparent Detokenization. If data has previously been RSA encrypted using TokenEx’s public RSA key, the ciphertext can be decrypted using this function before it is passed on to the destination endpoint.

Parameter Name	Value
FUNCTION	Decrypt
TYPE	RSA or AES*
ENCODING	BASE64 or HEX (ciphertext encoding)
DATA	The ciphertext data to be decrypted
IV	Initialization Vector (Required only for AES Type) - This value should be Base64 encoded.

*AES-256-CBC is supported. As a prerequisite for this functionality, the symmetric key used for encryption will need to be shared with TokenEx and loaded.

RSA Decrypt Example:

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: application/json
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey

{
    "paymentCard": {
        "type": "credit",
        "cardNumber": "{{{{FUNCTION:Decrypt,TYPE:RSA,ENCODING:BASE64,DATA:h7gQItIu8Ge5cSRRG4oN41uNPmunlp3gM3ONSrmzj4wx0AaMbRbwmI4C0YUWw2f8dKWOnAKszuwaYG4dpXrUnYAufX/ZiS8SHNnfFQsTTEYwupuWdgymYsqiRKw4nmwzUoXdTxTIx03em61e0knd3bwRayWxOc4PHgQ9A46IWz3UmBW75VMf5OfdhwX7QfdTSH2UKKdjwzNgXOTjb7spHzbzT6QYC4I+SLin1XCfFsEWcCJGha6v2m3eyu5Nu/K62XMeaie8vj3KB/Fx+t5bx9lyWr2txMuDtaU1hYXeZYt78dI4DptV6ZvoUIOjGE8/tg3RZ9xTGKwlXtKG8TQzig==}}}}",
        "expDate": "1112",
        "securityCode": "{{{{FUNCTION:Decrypt,TYPE:RSA,ENCODING:BASE64,DATA:Ab/CCGcIdcVx+70l3vWBn8pRZ91wOm5EkvXYjAoFcW5B2qwTxLzFuCVA6LJg6gnSq2dci1uEvHmuJSdJiNGt+Z4J2ilT2t3EIi7m2ymRlS0KxbH+DaW6QrpSPvjcTiMkGPXkBqcOmVqVuZNrQWwyY/P2rfCZ+HLdJ47IAdjjaIF959xv2Xz8Hhq310qIxWsVYHbA/pXf1Qw5iB4REJXJNx0tdC00WnyjuYLGrFX+qHT5Ju54HLwFxeK1khywzzVcuVs4ZQfPEwNtJVir57HJr/JbXuAc3zugK8XcvW1MCNve2keoW1Elx1NAa2lX2YJr+Jo54MCMPNt0zZWCrwczKQ==}}}}"
    }
}

AES Decrypt Example

POST https://test-tgapi.tokenex.com/detokenize HTTP/1.1
Content-Type: application/json
TX-URL: https://www.example.com
TX-TokenEx-ID: YourTokenExID
TX-APIKey: YourAPIKey

{
    "paymentCard": {
        "type": "credit",
        "cardNumber": "{{{{FUNCTION:DECRYPT,TYPE:AES,IV:pIgb1waGIoxxjj60VRoB4g==,ENCODING:Base64,DATA:iM1vdSnHAMiJQtizceARU6TLBb5vlhcXUElKmOevijE=}}}}",
        "expDate": "1112"
    }
}