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.

You also can register and update Secure Tokens using the HP integration method directly, or also, during HP or XML payment transactions, to easy your implementation effort. If that interests you, go back those sections and take a look at how to do that with minimum effort, but remember: just the present features allow you to search for Secure Tokens.

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.


Registration

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

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

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
MERCHANTREF Y Unique Merchant Reference. Length is limited to 48 chars.
TERMINALID Y A Terminal ID provided by Nuvei.
CARDNUMBER Y The payment card number.
CARDEXPIRY Y A 4 digit expiry field (MMYY).
CARDTYPE Y Card Type used for the registration.
For more details on this, visit Special Fields and Parameters - Card Types.
CARDHOLDERNAME Y The name of the card holder. It should be as displayed on the front of the card.
CVV N The security code entered by the card holder. Take a look at ND003 - CVV Checking.
ISSUENO N The issue no. of the card (Solo).
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters. Limited to 3 custom fields in this request.
EMAIL N Cardholders e-mail address. If populated the cardholder will be sent an email receipt. This can be overridden by SelfCare Terminal Setup settings “Disable Cardholder Receipt”.
PHONE N Card Holder Phone Number stored against transaction. International format, numeric only.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
CREDENTIALONFILE N Component of the request that can be added in case Credential on File feature is in use for the Terminal processing the Payment. See ND004 - Credential on File


Notes and Details About the Request

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:

TERMINALID:MERCHANTREF:DATETIME:CARDNUMBER:CARDEXPIRY:CARDTYPE:CARDHOLDERNAME:SECRET


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).


Examples for a Request

  • 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> 

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


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.

Filter:

FIELD REQUIRED DESCRIPTION
STOREDCREDENTIALTXTYPE N Possible values: FIRST_TXN, SUBSEQUENT_MERCHANT_INITIATED_TXN or SUBSEQUENT_CARDHOLDER_INITIATED_TXN
STOREDCREDENTIALUSE N Possible values: UNSCHEDULED, INSTALLMENT or RECURRING


<?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>


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
MERCHANTREF Same as the one informed on request.
CARDREFERENCE This field represents the token generated for the Secure Token.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
BRANDTXIDENTIFIER The gateway returns the transaction identifier received for Acquirer to the merchant in the response if Credential on File is used.


Notes and Details on the 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:

TERMINALID:MERCHANTREF:CARDREFERENCE:DATETIME:SECRET


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

Error Code Description
E01 SYSTEM ERROR – TRY AGAIN
E03 OPERATION NOT ALLOWED
E04 INVALID REFERENCE DETAILS
E05 INVALID CARD TYPE
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E08 INVALID MERCHANTREF
E09 INVALID DATETIME
E10 INVALID CARDNUMBER
E11 INVALID CARDEXPIRY
E12 INVALID CARDHOLDERNAME
E13 INVALID HASH
E14 INVALID SECURITY FIELD


Examples for the Response

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


Update

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

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

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
MERCHANTREF Y Unique Merchant Reference. Length is limited to 48 chars.
TERMINALID Y A Terminal ID provided by Nuvei.
CARDNUMBER N The payment card number.
CARDEXPIRY N A 4 digit expiry field (MMYY).
CARDTYPE Y Card Type used for the registration.
For more details on this, visit Special Fields and Parameters - Card Types.
CARDHOLDERNAME N The name of the card holder. It should be as displayed on the front of the card.
CVV N The security code entered by the card holder. Take a look at ND003 - CVV Checking.
ISSUENO N The issue no. of the card (Solo).
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters. Limited to 3 custom fields in this request.
EMAIL N Cardholders e-mail address. If populated the cardholder will be sent an email receipt. This can be overridden by SelfCare Terminal Setup settings “Disable Cardholder Receipt”.
PHONE N Card Holder Phone Number stored against transaction. International format, numeric only.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
CREDENTIALONFILE N Component of the request that can be added in case Credential on File feature is in use for the terminal processing the payment. See ND004 - Credential on File.


Notes and Details About the Request

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:

TERMINALID:MERCHANTREF:DATETIME:CARDNUMBER:CARDEXPIRY:CARDTYPE:CARDHOLDERNAME:SECRET


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).


Examples for a Request

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


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)

Filter:

FIELD REQUIRED DESCRIPTION
STOREDCREDENTIALTXTYPE N Possible values: FIRST_TXN, SUBSEQUENT_MERCHANT_INITIATED_TXN or SUBSEQUENT_CARDHOLDER_INITIATED_TXN
STOREDCREDENTIALUSE N Possible values: UNSCHEDULED, INSTALLMENT or RECURRING

Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
MERCHANTREF Same as the one informed on request.
CARDREFERENCE This field represents the token generated for the Secure Token.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the 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:

TERMINALID:MERCHANTREF:CARDREFERENCE:DATETIME:SECRET


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

Error Code Description
E01 SYSTEM ERROR – TRY AGAIN
E03 OPERATION NOT ALLOWED
E04 INVALID REFERENCE DETAILS
E05 INVALID CARD TYPE
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E08 INVALID MERCHANTREF
E09 INVALID DATETIME
E10 INVALID CARDNUMBER
E11 INVALID CARDEXPIRY
E12 INVALID CARDHOLDERNAME
E13 INVALID HASH
E14 INVALID SECURITY FIELD


Examples for the Response

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


Removal

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

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

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
MERCHANTREF Y Unique Merchant Reference. Length is limited to 48 chars. See ND003 - Not Reusable Merchant Ref.
TERMINALID Y A Terminal ID provided by Nuvei.
CARDREFERENCE Y The reference of the Secure Token you want to remove.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Request

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:

TERMINALID:MERCHANTREF:DATETIME:CARDREFERENCE:SECRET


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.

Examples for a Request

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
MERCHANTREF Same as the one informed on request.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the 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:

TERMINALID:MERCHANTREF:CARDREFERENCE:DATETIME:SECRET


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

Error Code Description
E01 SYSTEM ERROR – TRY AGAIN
E03 OPERATION NOT ALLOWED
E04 INVALID REFERENCE DETAILS
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E08 INVALID MERCHANTREF
E13 INVALID HASH


Examples for the Response

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


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

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

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
MERCHANTREF Y Unique Merchant Reference. Length is limited to 48 chars.
TERMINALID Y A Terminal ID provided by Nuvei.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
CREDENTIALONFILE YN Component of the request that can be added in case Credential on File feature is in use for the terminal. See ND003 - Credential on File.


Notes and Details About the Request

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:

TERMINALID:MERCHANTREF:DATETIME:SECRET


ND002 - Data Encoding for Requests

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

Examples for a Request

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


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>

Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
MERCHANTREF Same as the one informed on request.
CARDREFERENCE This field represents the token generated for the Secure Token.
CARDTYPE Card Type used for the registration.
CARDEXPIRY Card Expiry used for registration. A 4 digit expiry field (MMYY).
CARDHOLDERNAME The name of the card holder used for registration.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
BRANDTXIDENTIFIER The gateway returns the transaction identifier received from Acquirer to the merchant if Credential on File is sent in request.
STOREDCREDENTIALUSE Possible vales: UNSCHEDULED, INSTALLMENT or RECURRING. Returned if Credential on File sent in request.


Notes and Details on the 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:

TERMINALID:MERCHANTREF:CARDREFERENCE:CARDTYPE:CARDEXPIRY:CARDHOLDERNAME:DATETIME:SECRET


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

Error Code Description
E01 SYSTEM ERROR – TRY AGAIN
E03 OPERATION NOT ALLOWED
E04 INVALID REFERENCE DETAILS
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E08 INVALID MERCHANTREF
E13 INVALID HASH
E34 SECURE TOKEN WAS NOT FOUND
E35 SECURE TOKEN WAS DELETED


Examples for the Response

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


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>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
MERCHANTREF Y Unique Merchant Reference. Length is limited to 48 chars.
TERMINALID Y A Terminal ID provided by Nuvei.
NAME N Card holder’s name used for the Secure Token registration.
EMAIL N Card holder’s email used for the Secure Token registration.
PHONE N Card holder’s phone used for the Secure Token registration.
CREATIONDATE N Creation date of the Secure Token. Format: DD-MM-YYYY.
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. To understand more visit the section regarding Special Fields and Parameters. Limited to 3 custom fields in this request.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
CREDENTIALONFILE N Component of the request that can be added in case Credential on File feature is in use for the terminal. See ND003 - Credential on File.


Notes and Details About the Request

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:

TERMINALID:MERCHANTREF:NAME:EMAIL:PHONE:CREATIONDATE:DATETIME:SECRET


ND002 - Data Encoding for Requests

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

Examples for a Request

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


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.

Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
SECURETOKEN List of Secure Tokens registered, which matched the search criteria. Each secure token contains a set of subelements as defined in ND002 - Secure Token Elements.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
BRANDTXIDENTIFIER The gateway returns the transaction identifier received from Acquirer to the merchant if Credential on File is sent in request.
STOREDCREDENTIALUSE Possible values: UNSCHEDULED, INSTALLMENT or RECURRING returned if Credential on File sent in request.


Notes and Details on the 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:

TERMINALID:MERCHANTREF[1]:CARDREFERENCE[1]:CARDHOLDERNAME[1]:DATETIME:SECRET

  • [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:

FIELD DESCRIPTION
MERCHANTREF Same as the one informed on request.
CARDREFERENCE This field represents the token generated for the Secure Token.
CARDTYPE Card Type used for the registration.
CARDEXPIRY Card Expiry used for registration. A 4 digit expiry field (MMYY).
CARDHOLDERNAME The name of the card holder used for registration.


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

Error Code Description
E01 SYSTEM ERROR – TRY AGAIN
E03 OPERATION NOT ALLOWED
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E08 INVALID MERCHANTREF
E13 INVALID HASH
E34 SECURE TOKEN WAS NOT FOUND
E35 SECURE TOKEN WAS DELETED


Examples for the Response

  • 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>

REMEMBER to change the Terminal Id and Terminal Secret for valid values. Verify the Integration Docs for viable examples or contact our support team.


Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International