Table of Contents

The features presented in this page will allow your integration to check card accounts. This is a useful service for cases when you need to be usre a card is valid before using or storing it.

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

TYPE URL
REQUESTURL https://testpayments.nuvei.com/merchant/xmlpayment
XML XML desscriptor https://testpayments.nuvei.com/merchant/gateway.xsd

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.

Verification

This feature allows you to check the validity of a card account.

Request Body Fields

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Nuvei.
CARDNUMBER YThe payment card number.
CARDEXPIRY Y A 4 digit expiry field (MMYY)
CARDHOLDERNAME Y The name of the card holder. It should be as displayed on the front of the card.
CVV NThe security code entered by the card holder.
ADDRESS1 N The first address. Required for AVS.
ADDRESS2 N Second line of address. Required for AVS. Same as ADDRESS1
POSTCODE NPost cde for the address. Required for AVS.
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 give at the ND001-Hash Formation, in the next section.
CREDENTIALONEFILE 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 Paramenters section. For this specific feature, you should use the following formats:

TERMINALID:CARDNUMBER:CARDEXPIRY:CARDHOLDERNAME:DATETIME:SECRET

ND002 - Data Encoding for Request

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

ND003 - The Checking Variation

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

Examples for a Request

<?xml version="1.0" encoding="UTF-8"?> 
<ACCOUNT_VERIFICATION>
    <TERMINALID>6491002</TERMINALID>
    <CARDNUMBER>4916163721669613</CARDNUMBER>
    <CARDEXPIRY>1122</CARDEXPIRY>
    <CARDHOLDERNAME>acc verif</CARDHOLDERNAME>
    <CVV>999</CVV>
    <ADDRESS1>addr 1</ADDRESS1>
    <ADDRESS2>addr 2</ADDRESS2>
    <POSTCODE>postcode</POSTCODE>
    <DATETIME>23-01-2019:09:24:16:105</DATETIME>
    <HASH>821cb691de21380b42efa97276ab0cc829c9fdfbcb28f5890492622c6a78093eeb28862b4d721e0e2f8db3a521eefda052da51979da6f66578a7b704b7c8aed5</HASH>
</ACCOUNT_VERIFICATION>

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. The field CREDENTIALONFILE is sent to get the BRANDTXIDENTIFIER in the response message.

Examples for a Request

<?xml version="1.0" encoding="UTF-8"?> 
<ACCOUNT_VERIFICATION>
    <TERMINALID>6491002</TERMINALID>
    <CARDNUMBER>4916163721669613</CARDNUMBER>
    <CARDEXPIRY>1122</CARDEXPIRY>
    <CARDHOLDERNAME>acc verif</CARDHOLDERNAME>
    <CVV>999</CVV>
  <CREDENTIALONFILE/>
    <ADDRESS1>addr 1</ADDRESS1>
    <ADDRESS2>addr 2</ADDRESS2>
    <POSTCODE>postcode</POSTCODE>
    <DATETIME>23-01-2019:09:24:16:105</DATETIME>
    <HASH>821cb691de21380b42efa97276ab0cc829c9fdfbcb28f5890492622c6a78093eeb28862b4d721e0e2f8db3a521eefda052da51979da6f66578a7b704b7c8aed5</HASH>
</ACCOUNT_VERIFICATION>

Response Body Fields

The response body fields will be:

FIELD DESCRIPTION
STATUS Verification result. VERIFIED when the check is successful or UNVERIFIED when the verification fails.
RESPONSE_DETAIL This field adds context to the verifation response, indicating in case or failure, the reason.
DATETIME Request 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 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 Fieds and Parameters section. For this specific feature, you should use the following formats:

ERMINALID:STATUS:RESPONSE_DETAIL:DATETIME:SECRET

RESPONSE_DETAIL is only used if retured and TERMINALID refers to the request field used.

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>

Examples for the Response

<?xml version="1.0" encoding="UTF-8"?>
<ACCOUNT_VERIFICATION_RESPONSE>
    <STATUS>UNVERIFIED</STATUS>
    <RESPONSE_DETAIL>CVV validation failed</RESPONSE_DETAIL>
    <DATETIME>29-04-2019:15:27:45:921</DATETIME>
    <HASH>d71730f0abb95321386bb7e29f13c0c55412c114ea8689f460a0ee68d0c23b300acecd5f88eae84366edcaee5dae121d356e2c10449b61e8319c7eedc19fe8f5</HASH>
</ACCOUNT_VERIFICATION_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.

Examples for the Response

<?xml version="1.0" encoding="UTF-8"?>
<ACCOUNT_VERIFICATION_RESPONSE>
    <STATUS>VERIFIED</STATUS>
    <CREDENTIALONFILE>
        <BRANDTXIDENTIFIER>193252026110014</BRANDTXIDENTIFIER>
    </CREDENTIALONFILE>
     <DATETIME>29-04-2019:15:27:45:921</DATETIME>
    <HASH>d71730f0abb95321386bb7e29f13c0c55412c114ea8689f460a0ee68d0c23b300acecd5f88eae84366edcaee5dae121d356e2c10449b61e8319c7eedc19fe8f5</HASH>
</ACCOUNT_VERIFICATION_RESPONSE>