XML Secure Token Features

The features presented in this page will allow your integration to create and manage the lifecycle of a Secure Token. You can read more about the Secure Token feature in Products - Secure Card.

The following resources are the same for all the requests and responses you find in this page:

Use the Request URL and the Request Body Fields to perform a request for this feature, then prepare your integration to receive the response, as defined by the Response Body Fields.

This feature allows you to perform the registration of a Secure Token.

• Main Request body Tag: <SECURECARDREGISTRATION>
• Main Response body Tag: <SECURECARDREGISTRATIONRESPONSE>

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

ND003 - CVV Checking

If a Terminal is configured to perform secure token validation (CVV mandatory or not), the Payment Gateway performs an account verification before registering the Secure Token:

• If the CVV field is informed, the CVV response returned is verified and if it's positive the secure token is registered, if not, an error is generated.
• If the CVV field is not informed, the result of the transaction is verified and if it's successful the secure token is registered, if not, an error is generated.

Depending on the Payment Processor used by the Terminal, the account verification can be performed in two distinct ways:

• A 0.00 (zero) amount transaction or,
• A 1.00 (one) currency unit amount transaction followed, when successful, by its voiding (both transactions will appear in your batch).

• Scenario: Simple request to register a secure token.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?> 
<SECURECARDREGISTRATION>
    <MERCHANTREF>77001</MERCHANTREF>  
    <TERMINALID>6491002</TERMINALID>  
    <DATETIME>31-12-2008:23:59:59:001</DATETIME>
    <CARDNUMBER>4444333322221111</CARDNUMBER>  
    <CARDEXPIRY>1208</CARDEXPIRY>  
    <CARDTYPE>VISA</CARDTYPE>  
    <CARDHOLDERNAME>John Smith<CARDHOLDERNAME>
    <HASH>d04c3bab519095ecb046eff91722e8df</HASH>
</SECURECARDREGISTRATION> 

ND004 - Credential on File

This feature is currently available to TSYS Saratoga terminals. These fields will only be used on a payment if you have secure token storage enabled. The fields will have the following behavior: Hidden - the gateway accepts the fields, if sent, and adds them to the transaction, but doesn't not show it for the customer.

To provide a transaction with COF, your request needs to add the Credential on File component and its fields, as described below.

<?xml version="1.0" encoding="UTF-8"?> 
<SECURECARDREGISTRATION>
<MERCHANTREF>CSV_02338028</MERCHANTREF>
<TERMINALID>2366006</TERMINALID>
<DATETIME>11-09-2019:14:45:38:029</DATETIME>
<CARDNUMBER>4111111111111111</CARDNUMBER>
<CARDEXPIRY>1223</CARDEXPIRY>
<CARDTYPE>VISA</CARDTYPE>
<CARDHOLDERNAME>Jack Brown</CARDHOLDERNAME>
<HASH>f842282d0ee991dc84da957ee1697ce6</HASH>
<CVV>999</CVV>
<CREDENTIALONFILE>
<STOREDCREDENTIALTXTYPE>FIRST_TXN</STOREDCREDENTIALTXTYPE>
<STOREDCREDENTIALUSE>RECURRING</STOREDCREDENTIALUSE>
</CREDENTIALONFILE>
</SECURECARDREGISTRATION>

The response body fields will be:

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

• Scenario: Response to the initial simple request.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SECURECARDREGISTRATIONRESPONSE>  
    <MERCHANTREF>77001</MERCHANTREF>  
    <CARDREFERENCE>2999990000000001</CARDREFERENCE>  
    <DATETIME>31-12-2008:23:59:59:002</DATETIME>
    <HASH>d04c3bab519095ecb046eff91722e8df</HASH>       
</SECURECARDREGISTRATIONRESPONSE>

This feature allows you to perform the update of an existing Secure Token.

• Main Request body Tag: <SECURECARDUPDATE>
• Main Response body Tag: <SECURECARDUPDATERESPONSE>

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

ND003 - CVV Checking

If a Terminal is configured to perform secure token validation (CVV mandatory or not), the Payment Gateway performs an account verification before registering the Secure Token:

• If the CVV field is informed, the CVV response returned is verified and if it's positive the secure token is registered, if not, an error is generated.
• If the CVV field is not informed, the result of the transaction is verified and if it's successful the secure token is registered, if not, an error is generated.

Depending on the Payment Processor used by the Terminal, the account verification can be performed in two distinct ways:

• A 0.00 (zero) amount transaction or,
• A 1.00 (one) currency unit amount transaction followed, when successful, by its voiding (both transactions will appear in your batch).

• Scenario: Simple request to update a secure token.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SECURECARDUPDATE>
	<MERCHANTREF>77001</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<DATETIME>31-12-2008:23:59:59:001</DATETIME>
	<CARDEXPIRY>1208</CARDEXPIRY>
	<CARDTYPE>VISA</CARDTYPE>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
</SECURECARDUPDATE>

ND004 - Credential on File

This feature is currently available to TSYS Saratoga terminals. These fields will only be used on a payment if you have secure token storage enabled. The fields will have the following behavior: Hidden - the gateway accepts the fields, if sent, and adds them to the transaction, but does not show it for the customer.

To provide a transaction with COF, your request needs to add the Credential on File component and its fields, as described below.

(new table below note ND004)

The response body fields will be:

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

• Scenario: Response to the initial simple request.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SECURECARDREGISTRATIONRESPONSE>  
    <MERCHANTREF>77001</MERCHANTREF>  
    <CARDREFERENCE>2999990000000001</CARDREFERENCE>  
    <DATETIME>31-12-2008:23:59:59:002</DATETIME>
    <HASH>d04c3bab519095ecb046eff91722e8df</HASH>       
</SECURECARDREGISTRATIONRESPONSE>

This feature allows you to perform the removal of an existing Secure Token.

• Main Request body Tag: <SECURECARDREMOVAL>
• Main Response body Tag: <SECURECARDREMOVALRESPONSE>

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

ND003 - Not Reusable Merchant Ref

The Merchant Reference is unique, so once a Secure Token is removed, its MerchantRef can't be resused. This is because they are tied to existing transactions in our system and are retained internally for data integrity and future refund functionality.

• Scenario: Simple request to remove a secure token.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?> 
<SECURECARDREMOVAL>  
      <MERCHANTREF>77001</MERCHANTREF>  
      <CARDREFERENCE>2967534771694736</CARDREFERENCE>  
      <TERMINALID>6491002</TERMINALID>  
      <DATETIME>31-12-2008:23:59:59:001</DATETIME>
      <HASH>d04c3bab519095ecb046eff91722e8df</HASH>        
</SECURECARDREMOVAL>

The response body fields will be:

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

• Scenario: Response to the initial simple request.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SECURECARDREMOVALRESPONSE>  
      <MERCHANTREF>77001</MERCHANTREF>  
      <DATETIME>31-12-2008:23:59:59:002</DATETIME>
      <HASH>d04c3bab519095ecb046eff91722e8df</HASH>      
</SECURECARDREMOVALRESPONSE>

This feature allows you to retrieve a specific Secure Token and its details.

• Main Request body Tag: <SECURECARDSEARCH>
• Main Response body Tag: <SECURECARDSEARCHRESPONSE>

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

• Scenario: Simple request to search a secure token.
• Merchant Reference: 77001.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SECURECARDSEARCH>
	<MERCHANTREF>77001</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<DATETIME>31-12-2008:23:59:59:001</DATETIME>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
</SECURECARDSEARCH>

ND003 - Credential on File

This feature is currently available to TSYS Saratoga terminals. The Credential on File details will be included in the response if an empty CREDENTIALONFILE tag is sent in request.

Quick example:

<?xml version="1.0" encoding="UTF-8"?>
<SECURECARDSEARCH>
<MERCHANTREF>CSV_84828896</MERCHANTREF>
<TERMINALID>2366006</TERMINALID>
<CREDENTIALONFILE/>
<DATETIME>19-09-2019:12:21:52:441</DATETIME>
<HASH>054d6301a9d78d703772e7f44bca256f</HASH>
</SECURECARDSEARCH>

The response body fields will be:

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

• Scenario: Response to the initial simple request.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SECURECARDSEARCHRESPONSE>
	<MERCHANTREF>77001</MERCHANTREF>
	<CARDREFERENCE>2967532702149716</CARDREFERENCE>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>1208</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Smith<CARDHOLDERNAME>
	<DATETIME>31-12-2008:23:59:59:001</DATETIME>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
</SECURECARDSEARCHRESPONSE>

This feature allows you to retrieve a list of Secure Tokens and their details. With this feature, you are going to be able to add criteria for a search, like: name, date, e-mail, phone and even custom fields (up to 3), as needed.

• Main Request body Tag: <SECURE_CARD_ADVANCED_SEARCH>
• Main Response body Tag: <SECURE_CARD_ADVANCED_SEARCH_RESPONSE>

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

• Scenario: Simple request to retrieve a list of secure token.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SECURE_CARD_ADVANCED_SEARCH>
	<MERCHANTREF>77001</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<NAME>John Smith</NAME>
	<EMAIL>john@selfdomain.com</EMAIL>
	<PHONE>11856452420</PHONE>
	<CREATIONDATE>31-12-2008</CREATIONDATE>
	<DATETIME>11-6-2017:11:23:55:134 </DATETIME>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
</SECURE_CARD_ADVANCED_SEARCH>

ND003 - Credential on File

This feature is currently available on TSYS Saratoga terminals. The Credential on File details will be included in the response if an empty CREDENTIALONFILE tag is sent in request.

The response body fields will be:

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

• [1] - MERCHANTREF/CARDREFERENCE/CARDHOLDERNAME: The HASH should contain the concatenation of all the strings representing each secure token returned, in the sequence they were returned. The string of each secure token should be formed by the concatenation of these tree elements.

ND002 - Secure Token Elements

Each secure token returned by the search has a set of nested elements, as defined below:

ND003 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND004 - Response Codes - Errors

• Scenario: Response to the initial simple request.
• Terminal: 6491002.
• Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SECURE_CARD_ADVANCED_SEARCH_RESPONSE>
	<SECURECARD>
		<MERCHANTREF>77001</MERCHANTREF>
		<CARDREFERENCE>72357598079</CARDREFERENCE>
		<CARDTYPE>DISCOVERY</CARDTYPE>
		<CARDEXPIRY>1019</CARDEXPIRY>
		<CARDHOLDERNAME>Joan Simons</CARDHOLDERNAME>
	</SECURECARD>
	<SECURECARD>
		<MERCHANTREF>77001</MERCHANTREF>
		<CARDREFERENCE>12465693334</CARDREFERENCE>
		<CARDTYPE>VISA</CARDTYPE>
		<CARDEXPIRY>1217</CARDEXPIRY>
		<CARDHOLDERNAME>Phelippo Henry Sibouer</CARDHOLDERNAME>
	</SECURECARD>
	<!-- Until 10 Secure Token registries are returned -->
	<DATETIME>29-06-2017:09:52:12:650</DATETIME>
	<HASH>a978a30afd8303cd24035d8bad6692d7]</HASH>
</SECURE_CARD_ADVANCED_SEARCH_RESPONSE>