--- developer:api_specification:xml_secure_card_features [2019/12/13 09:57]
robinc [Request Body Fields] Added CREDENTIALONFILE
+++ developer:api_specification:xml_secure_card_features [2022/03/04 10:22]
lezlieh replaced secure token with secure card
@@ Line 1: / Line 1: @@
-====== XML Secure Card Features ======
+====== XML Secure Token Features ======
 ~~TOC~~
 \\
-The features presented in this page will allow your integration to create and manage the lifecycle of a Secure Card. You can read more about the Secure Card feature in **[[merchant:new_merchant:products#secure_card| Products - Secure Card]]**.
+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 **[[merchant:new_merchant:products#secure_card| Products - Secure Card]]**.
 <WRAP center info 100%>
-You also can register and update Secure Cards 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 Cards.
+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.
 </WRAP>
@@ Line 22: / Line 22: @@
 ===== Registration =====
-This feature allows you to perform the registration of a Secure Card.
+This feature allows you to perform the registration of a Secure Token.
   * **Main Request body Tag**: <SECURECARDREGISTRATION>
@@ Line 67: / Line 67: @@
 **ND003 - CVV Checking**
-If a Terminal is configured to perform secure card validation (CVV mandatory or not), the Payment Gateway performs an account verification before registering the Secure Card:
+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 card is registered, if not, an error is generated.
+  * 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 card 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:
@@ Line 80: / Line 80: @@
 ==== Examples for a Request ====
-  * **Scenario**: Simple request to register a secure card.
+  * **Scenario**: Simple request to register a secure token.
   * **Terminal**: 6491002.
   * **Terminal Secret**: x4n35c32RT.
@@ Line 104: / Line 104: @@
 \\
+**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.
+<searchtable>
+^ **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 |
+</searchtable>
+\\
+<code xml>
+<?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>
+</code>
+\\
 ==== Response Body Fields ====
@@ Line 111: / Line 143: @@
 ^ **FIELD** ^ **DESCRIPTION** ^
 | MERCHANTREF | Same as the one informed on request. |
-| CARDREFERENCE | This field represents the token generated for the Secure Card. |
+| 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. |
 </searchtable>
 \\
@@ Line 182: / Line 215: @@
 ===== Update =====
-This feature allows you to perform the update of an existing Secure Card.
+This feature allows you to perform the update of an existing Secure Token.
   * **Main Request body Tag**: <SECURECARDUPDATE>
@@ Line 204: / Line 237: @@
 | 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**.|
 </searchtable>
 \\
@@ Line 226: / Line 260: @@
 **ND003 - CVV Checking**
-If a Terminal is configured to perform secure card validation (CVV mandatory or not), the Payment Gateway performs an account verification before registering the Secure Card:
+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 card is registered, if not, an error is generated.
+  * 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 card 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:
@@ Line 239: / Line 273: @@
 ==== Examples for a Request ====
-  * **Scenario**: Simple request to update a secure card.
+  * **Scenario**: Simple request to update a secure token.
   * **Terminal**: 6491002.
   * **Terminal Secret**: x4n35c32RT.
@@ Line 261: / Line 295: @@
 \\
+**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)
+<searchtable>
+^ **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|
+</searchtable>
 ==== Response Body Fields ====
@@ Line 269: / Line 317: @@
 ^ **FIELD** ^ **DESCRIPTION** ^
 | MERCHANTREF | Same as the one informed on request. |
-| CARDREFERENCE | This field represents the token generated for the Secure Card. |
+| 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. |
@@ Line 339: / Line 387: @@
 ===== Removal =====
-This feature allows you to perform the removal of an existing Secure Card.
+This feature allows you to perform the removal of an existing Secure Token.
   * **Main Request body Tag**: <SECURECARDREMOVAL>
@@ Line 350: / Line 398: @@
 | 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 Card you want to remove. |
+| 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. |
@@ Line 375: / Line 423: @@
 **ND003 - Not Reusable Merchant Ref**
-The Merchant Reference is unique, so once a Secure Card 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.
+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 card.
+  * **Scenario**: Simple request to remove a secure token.
   * **Terminal**: 6491002.
   * **Terminal Secret**: x4n35c32RT.
@@ Line 472: / Line 520: @@
 ===== Search =====
-This feature allows you to retrieve a specific Secure Card and its details.
+This feature allows you to retrieve a specific Secure Token and its details.
   * **Main Request body Tag**: <SECURECARDSEARCH>
@@ Line 485: / Line 533: @@
 | 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**. |
 </searchtable>
 \\
@@ Line 506: / Line 555: @@
 ==== Examples for a Request ====
-  * **Scenario**: Simple request to search a secure card.
+  * **Scenario**: Simple request to search a secure token.
   * **Merchant Reference**: 77001.
   * **Terminal**: 6491002.
@@ Line 527: / Line 576: @@
 \\
+**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:
+<code xml>
+<?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>
+</code>
 ==== Response Body Fields ====
@@ Line 535: / Line 601: @@
 ^ **FIELD** ^ **DESCRIPTION** ^
 | MERCHANTREF | Same as the one informed on request. |
-| CARDREFERENCE | This field represents the token generated for the Secure Card. |
+| 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).|
@@ Line 541: / Line 607: @@
 | 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. |
 </searchtable>
 \\
@@ Line 576: / Line 644: @@
 | E08 | INVALID MERCHANTREF |
 | E13 | INVALID HASH |
-| E34 | SECURE CARD WAS NOT FOUND |
+| E34 | SECURE TOKEN WAS NOT FOUND |
-| E35 | SECURE CARD WAS DELETED |
+| E35 | SECURE TOKEN WAS DELETED |
 \\
@@ Line 608: / Line 676: @@
 ===== Advanced Search =====
-This feature allows you to retrieve a list of Secure Cards 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 neede
+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>
@@ Line 619: / Line 687: @@
 | 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 Card registration. |
+| NAME |	N	| Card holder’s name used for the Secure Token registration. |
-| EMAIL |	N	| Card holder’s email used for the Secure Card registration. |
+| EMAIL |	N	| Card holder’s email used for the Secure Token registration. |
-| PHONE   |	N	| Card holder’s phone used for the Secure Card registration. |
+| PHONE   |	N	| Card holder’s phone used for the Secure Token registration. |
-| CREATIONDATE |	N	| Creation date of the Secure Card. Format: DD-MM-YYYY.|
+| 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 **[[developer:api_specification:special_fields_and_parameters|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**. |
 </searchtable>
 \\
@@ Line 647: / Line 716: @@
 ==== Examples for a Request ====
-  * **Scenario**: Simple request to retrieve a list of secure cards.
+  * **Scenario**: Simple request to retrieve a list of secure token.
   * **Terminal**: 6491002.
   * **Terminal Secret**: x4n35c32RT.
@@ Line 670: / Line 739: @@
 </WRAP>
 \\
+**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.
@@ Line 678: / Line 752: @@
 <searchtable>
 ^ **FIELD** ^ **DESCRIPTION** ^
-| SECURECARD | List of Secure Cards registered, which matched the search criteria. Each secure card contains a set of subelements as defined in **ND002 - Secure Card Elements**. |
+| 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.|
 </searchtable>
 \\
@@ Line 694: / Line 770: @@
 </WRAP>
-  * **[1]** - **MERCHANTREF**/**CARDREFERENCE**/**CARDHOLDERNAME**: The HASH should contain the concatenation of all the strings representing each secure card returned, in the sequence they were returned. The string of each secure card should be formed by the concatenation of these tree elements.
+  * **[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 Card Elements**
+**ND002 - Secure Token Elements**
-Each secure card returned by the search has a set of nested elements, as defined below:
+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 Card. |
+| 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).|
@@ Line 730: / Line 806: @@
 | E08 | INVALID MERCHANTREF |
 | E13 | INVALID HASH |
-| E34 | SECURE CARD WAS NOT FOUND |
+| E34 | SECURE TOKEN WAS NOT FOUND |
-| E35 | SECURE CARD WAS DELETED |
+| E35 | SECURE TOKEN WAS DELETED |
 \\
@@ Line 757: / Line 833: @@
 		<CARDHOLDERNAME>Phelippo Henry Sibouer</CARDHOLDERNAME>
 	</SECURECARD>
-	<!-- Until 10 Secure Card registries are returned -->
+	<!-- Until 10 Secure Token registries are returned -->
 	<DATETIME>29-06-2017:09:52:12:650</DATETIME>
 	<HASH>a978a30afd8303cd24035d8bad6692d7]</HASH>

Differences

Worldnet

Learn More

Request

Contact Us