Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
developer:api_specification:xml_secure_card_features [2019/12/13 10:47] robinc [Response Body Fields] Added BRANDTXIDENTIFIER field |
developer:api_specification:xml_secure_card_features [2022/03/04 10:22] (current) lezlieh replaced secure token with secure card |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== XML Secure Card Features ====== | + | ====== XML Secure Token Features ====== |
| ~~TOC~~ | ~~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%> | <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> | </WRAP> | ||
| Line 22: | Line 22: | ||
| ===== Registration ===== | ===== 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> | * **Main Request body Tag**: <SECURECARDREGISTRATION> | ||
| Line 67: | Line 67: | ||
| **ND003 - CVV Checking** | **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: | 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 ==== | ==== Examples for a Request ==== | ||
| - | * **Scenario**: Simple request to register a secure card. | + | * **Scenario**: Simple request to register a secure token. |
| * **Terminal**: 6491002. | * **Terminal**: 6491002. | ||
| * **Terminal Secret**: x4n35c32RT. | * **Terminal Secret**: x4n35c32RT. | ||
| Line 106: | Line 106: | ||
| **ND004 - Credential on File** | **ND004 - Credential on File** | ||
| - | This feature is currently available to TSYS Saratoga terminals and is configurable by customer support. These fields will only be used on a payment if you have secure card 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. | + | 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. | To provide a transaction with COF, your request needs to add the Credential on File component and its fields, as described below. | ||
| Line 143: | Line 143: | ||
| ^ **FIELD** ^ **DESCRIPTION** ^ | ^ **FIELD** ^ **DESCRIPTION** ^ | ||
| | MERCHANTREF | Same as the one informed on request. | | | 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. | | | 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. | | | 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 215: | Line 215: | ||
| ===== Update ===== | ===== 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> | * **Main Request body Tag**: <SECURECARDUPDATE> | ||
| Line 260: | Line 260: | ||
| **ND003 - CVV Checking** | **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: | Depending on the Payment Processor used by the Terminal, the account verification can be performed in two distinct ways: | ||
| Line 273: | Line 273: | ||
| ==== Examples for a Request ==== | ==== Examples for a Request ==== | ||
| - | * **Scenario**: Simple request to update a secure card. | + | * **Scenario**: Simple request to update a secure token. |
| * **Terminal**: 6491002. | * **Terminal**: 6491002. | ||
| * **Terminal Secret**: x4n35c32RT. | * **Terminal Secret**: x4n35c32RT. | ||
| Line 298: | Line 298: | ||
| **ND004 - Credential on File** | **ND004 - Credential on File** | ||
| - | This feature is currently available to TSYS Saratoga terminals and is configurable by customer support. These fields will only be used on a payment if you have secure card 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. | + | 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. | To provide a transaction with COF, your request needs to add the Credential on File component and its fields, as described below. | ||
| Line 317: | Line 317: | ||
| ^ **FIELD** ^ **DESCRIPTION** ^ | ^ **FIELD** ^ **DESCRIPTION** ^ | ||
| | MERCHANTREF | Same as the one informed on request. | | | 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. | | | 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. | | | 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 387: | Line 387: | ||
| ===== Removal ===== | ===== 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> | * **Main Request body Tag**: <SECURECARDREMOVAL> | ||
| Line 398: | Line 398: | ||
| | MERCHANTREF | Y | Unique Merchant Reference. Length is limited to 48 chars. See **ND003 - Not Reusable Merchant Ref**. | | | 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. | | | 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. | | | 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. | | | 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 423: | Line 423: | ||
| **ND003 - Not Reusable Merchant Ref** | **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 ==== | ==== Examples for a Request ==== | ||
| - | * **Scenario**: Simple request to remove a secure card. | + | * **Scenario**: Simple request to remove a secure token. |
| * **Terminal**: 6491002. | * **Terminal**: 6491002. | ||
| * **Terminal Secret**: x4n35c32RT. | * **Terminal Secret**: x4n35c32RT. | ||
| Line 520: | Line 520: | ||
| ===== Search ===== | ===== 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> | * **Main Request body Tag**: <SECURECARDSEARCH> | ||
| Line 555: | Line 555: | ||
| ==== Examples for a Request ==== | ==== Examples for a Request ==== | ||
| - | * **Scenario**: Simple request to search a secure card. | + | * **Scenario**: Simple request to search a secure token. |
| * **Merchant Reference**: 77001. | * **Merchant Reference**: 77001. | ||
| * **Terminal**: 6491002. | * **Terminal**: 6491002. | ||
| Line 579: | Line 579: | ||
| **ND003 - Credential on File** | **ND003 - Credential on File** | ||
| - | This feature is currently available to TSYS Saratoga terminals and is configurable by customer support. The Credential on File details will be included in the response if an empty CREDENTIALONFILE tag is sent in request. | + | 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: | Quick example: | ||
| Line 601: | Line 601: | ||
| ^ **FIELD** ^ **DESCRIPTION** ^ | ^ **FIELD** ^ **DESCRIPTION** ^ | ||
| | MERCHANTREF | Same as the one informed on request. | | | 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. | | | CARDTYPE | Card Type used for the registration. | | ||
| | CARDEXPIRY | Card Expiry used for registration. A 4 digit expiry field (MMYY).| | | CARDEXPIRY | Card Expiry used for registration. A 4 digit expiry field (MMYY).| | ||
| Line 644: | Line 644: | ||
| | E08 | INVALID MERCHANTREF | | | E08 | INVALID MERCHANTREF | | ||
| | E13 | INVALID HASH | | | 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 676: | Line 676: | ||
| ===== Advanced Search ===== | ===== 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> | * **Main Request body Tag**: <SECURE_CARD_ADVANCED_SEARCH> | ||
| Line 687: | Line 687: | ||
| | MERCHANTREF | Y | Unique Merchant Reference. Length is limited to 48 chars. | | | MERCHANTREF | Y | Unique Merchant Reference. Length is limited to 48 chars. | | ||
| | TERMINALID | Y | A Terminal ID provided by Nuvei. | | | 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. | | | 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. | | | DATETIME | Y | Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS. | | ||
| Line 716: | Line 716: | ||
| ==== Examples for a Request ==== | ==== 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**: 6491002. | ||
| * **Terminal Secret**: x4n35c32RT. | * **Terminal Secret**: x4n35c32RT. | ||
| Line 743: | Line 743: | ||
| **ND003 - Credential on File** | **ND003 - Credential on File** | ||
| - | This feature is currently available on TSYS Saratoga terminals and is configurable by customer support. The Credential on File details will be included in the response if an empty CREDENTIALONFILE tag is sent in request. | + | 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 752: | Line 752: | ||
| <searchtable> | <searchtable> | ||
| ^ **FIELD** ^ **DESCRIPTION** ^ | ^ **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. | | | 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. | | | 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 770: | Line 770: | ||
| </WRAP> | </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** ^ | ^ **FIELD** ^ **DESCRIPTION** ^ | ||
| | MERCHANTREF | Same as the one informed on request. | | | 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. | | | CARDTYPE | Card Type used for the registration. | | ||
| | CARDEXPIRY | Card Expiry used for registration. A 4 digit expiry field (MMYY).| | | CARDEXPIRY | Card Expiry used for registration. A 4 digit expiry field (MMYY).| | ||
| Line 806: | Line 806: | ||
| | E08 | INVALID MERCHANTREF | | | E08 | INVALID MERCHANTREF | | ||
| | E13 | INVALID HASH | | | 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 833: | Line 833: | ||
| <CARDHOLDERNAME>Phelippo Henry Sibouer</CARDHOLDERNAME> | <CARDHOLDERNAME>Phelippo Henry Sibouer</CARDHOLDERNAME> | ||
| </SECURECARD> | </SECURECARD> | ||
| - | <!-- Until 10 Secure Card registries are returned --> | + | <!-- Until 10 Secure Token registries are returned --> |
| <DATETIME>29-06-2017:09:52:12:650</DATETIME> | <DATETIME>29-06-2017:09:52:12:650</DATETIME> | ||
| <HASH>a978a30afd8303cd24035d8bad6692d7]</HASH> | <HASH>a978a30afd8303cd24035d8bad6692d7]</HASH> | ||