Account Update and Background Notification


“Account Updater” refers to secure tokens saved on Nuvei’s system, which have had their Cardholder details updated electronically via “Visa Account Updater” (VAU) and “Mastercard Automatic Billing Updater” (ABU) respectively. This is a process which helps to ensure a smooth automatic billing cycle by minimizing payment disruptions due to account changes.

Case example:

  • Customers secure tokens are saved to the gateway
  • A monthly subscription is created for the customer
  • As time passes, eventually, the cards expire
  • Nuvei sends a request to Mastercard or Visa asking for the new cards' details
  • Visa/ Mastercard sends the updated card details back to Nuvei
  • The customers' cards (secure tokens) are updated with new info
  • Next months subscription won’t be affected because we now have the correct card details stored for the customers.

The Account Updater operations run as a background task, constantly, and sends batches of Account Updater details to each terminal’s specified notification URL (Configured at Terminal Level for the specific purpose of notifying Terminals of this type of change).

This allows integrations with the Payment Gateway to keep their customers masked card details with valid data on their side - always updating whenever the card scheme sends new data.

Each request containing the Account Updater details will be stored until it has been accepted and validated by the specified notification host.

After receiving this request, the Merchant's Integration side should send a reply messages to:

https://testpayments.nuvei.com/merchant/accountupdater/notification/reply

The live URL will be provided once merchant testing is completed.

Additionally: a new report was added under the Reporting section of SelfCare System, where the Merchants can keep track of the updates performed by the Account Update feature. Take a look at the %selfCare Guide for more details » SelfCare System «.


System Start-up

To enable the Account Updater Background Notifications(AUBN) it is required to set up your terminal to use the new AUBN feature.

Please note that as default the the number of cards sent for each notification will be set to 10,000. If you need to change this limit, please contact Nuvei.

Message Specification

The body of each message is in the format of Comma Separated Values (CSV). Each Account Updater Notification Request from the gateway will contain the following CSV headers and appropriate values.

Request From Gateway

Format to HTTP Post:

  • Produces:​ text/plain
  • Consumes:​ text/plain

The request message size can be modified in a Gateway’s System Settings. The maximum size is 10,000. To ensure messages are not fragmented because of their Secure Token Custom Field names; the Secure Token custom fields are set as name/value pairs in the CSV string. More specifically, they are located under the SCCF1/2/3 columns, and have their names and values delimited by the String “<AUBN||MSG>”.

The Gateway Sends this request to: The ​Account Updater Background Notification URL​ set in Terminal Settings.

Request Body Fields

HEADER TYPE DESCRIPTION
TERMINAL NUMBER Numeric Gateway terminal which the card belongs to
MASKED CARD DETAILS String Card Number with the first 6, and the last 4 digits visible.
MERCHANT REFERENCE String Merchant reference stored on the gateway
HASH String The hash of the current row of data. See Message Hash subsection for more details.
CARD TYPE String Card type, e.g. Visa, Mastercard, etc.
STATUS Integer Status Code​ of the Secure Token Update. See Account Updater Status Codes for more details.
CURRENT EXPIRY String Card expiry date in the format of “MMYY”.
CARD MODIFICATION DATE String The date the secure token was last updated on the gateway via Account Updater. Date format = “yyyy-MM-dd:HH:mm:ss”
UUID String Unique ID to validate message authenticity
MSG EXPIRES IN Numeric Milliseconds. When the gateway will stop accepting merchant responses for this request.
SCCF1 String Any secure token custom fields will go here. The string will contain both name and value of the secure token custom field. For more information see ND001 below
SCCF2 String Same as SCCF1
SCCF3 String Same as SCCF1
ALGORITHM String The hashing algorithm used for the hash string

Notes and Details About the Request

ND001 - Name and Value Format

The name, and value will be delimited by the String “<AUBN||MSG>”.

For example:

  • “name<AUBN|MSG>value”
  • “exigoID<AUBN|MSG>213545”

Received Reply From Merchant

Format to HTTP Post:

  • Produces: text/plain
  • Consumes: text/plain

Once the request is received by the merchant, they should reply with the String “OK” immediately, and a response code of 200.

The server expects a OK as the reply.

Processed Reply From Merchant

Format to HTTP Post:

The live URL will be provided once merchant testing is completed.

After the ‘received reply’ is sent, the merchant server can proceed with processing the account updater background notification data received from the gateway. Once the CSV has been processed on the merchant side, it is required that the gateway be notified if it has been a success or failure.

The reply message must contain the following CSV Headers on the first line of the reply.

Response Body Fields

HEADER TYPE DESCRIPTION
TERMINAL NUMBER Numeric Gateway terminal which the card belongs to
UUID String The original UUID from the original incoming request. Used for message authenticity
SUCCESS Int - 0 or 1 Flag that identifies if the card was processed successfully or not. Possible values: 0 or 1
ERROR MSG String Error Message indicating why it failed. Empty String if successful.
HASH String Hash string of the previous values in the row. See Message Hash subsection for more details.
ALGORITHM String The hashing algorithm used for the hash string.

Message Hash

To determine message authenticity on the merchant side, each row in the csv string of the request message has to be hashed along with the terminals secret passphrase. The hashing algorithm used will be specified in the “ALGORITHM” column in the CSV data. The default hashing algorithm used is “SHA-512”. Check section for valid algorithms. Each column in each row will be concatenated and hashed using the specified algorithm.

Hashing with Algorithm

  • Firstly, the each value in the CSV row will need to be concatenated with the other values in the row.
  • The terminal’s secret passphrase should be appended to the end of the string.
  • The order in which this should be done is as follows:

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

For Request Row Hash

TERMINALNUMBER:MASKEDCARDDETAILS:MERCHANTREF:CARDTYPE:STATUS:CURRENTEXPIRYDATE:CARDMODIFICATIONDATE:UUID:MSGEXPIRESIN:SCCF1:SCCF2:SCCF3:TERMINALSECRET


For Response Row Hash

TERMINALNUMBER:UUID:SUCCESS:ERRORMSG:TERMINALSECRET

Supported Hashing Algorithms

The hashing algorithms that the gateway supports are listed below; these algorithms are valid values for the “ALGORITHM” column in the CSV data.

Algorithm String Format
MD5 Hexadecimal
SHA-256 Hexadecimal
SHA-384 Hexadecimal
SHA-512 Hexadecimal

Additional Information

Account Updater Status Codes

The message from the gateway contains a field called “STATUS”. This field reflects the gateways Secure Token account updater status. This means that the gateway has sent this secure token to Mastercard/Visa (ABU/VAU) and received an update status from their service.

The following table details the meaning of each status code.

Code Name Description
1 UPDATE Match made; update data provided / Account number change (the account number or account number and expiration date are updated).
2 EXPIRY Match made; expiration date changed
3 VALID Match made, account number and expiration date unchanged / No updates were found but the account is valid.
4 CONTACT_CLOSED Match made; account closed / contact cardholder advice (the merchant should contact the cardholder for additional information on the account).
5 CONTACT Contact cardholder advice
6 UNKNOWN The account number could not be found
7 PARTICIPATING No match, participating BIN/issuer
8 NON_PARTICIPATING No match, non-participating BIN/issuer
9 ER_UNSUPPORTED_RESPONSE_CODE Unsupported response code
10 IN_PROCESS Deprecated. No longer sending this response code to merchants.
101 ER_000101 Non-numeric Account Number
102 ER_000102 Account Number is not in BIN Range
103 ER_000103 Invalid Expiration Date
104 ER_000104 Merchant Not Registered
122 ER_000122 Unregistered Sub-merchant
-1 UNDEFINED STATUS_UNKNOWN status

Test Data

The following test data can be used to test your AUBN Service.

Note: The Terminal Secret used in the following data is: secretpass

Request From Gateway:

"TERMINAL NUMBER","MASKED CARD DETAILS","MERCHANT REFERENCE","HASH","CARD TYPE","STATUS","CURRENT EXPIRY","CARD MODIFICATION DATE","UUID","MSG EXPIRES IN","SCCF1","SCCF2","SCCF3","ALGORITHM"
"11001","448596******3864","1000029","98643049966a2d1062f1a3c1f6fdbbccbf0b27cbc7151ddc3f27b5f8f19df989","VISA","1","1218","2016-09-20:20:00:34","5fa3e885-98f2-4e0b-9d29-8c6fe463ec33","150000","robsSCCF<AUBN||MSG>test123","","","SHA-256"
"11001","402400******8322","1000021","ff33eee3fc5bef72bafef621dd7e653c1d5c993744676daac850d63de11c5d89","VISA","1","1218","2016-09-20:20:00:21","7bae3ecf-97c4-43b1-89a0-25797ca325e9","150000","robsSCCF<AUBN||MSG>testtest","","","SHA-256"
"11001","541022******0093","100002","636159312e39094758f07edf3630720793f74bb5930f22ec3b867f968106462b","MASTERCARD","1","1218","2016-09-20:20:00:07","18c78348-cd35-4e35-a817-7dd34dad955c","150000","robsSCCF<AUBN||MSG>tester1","","","SHA-256"

Service should immediately reply with “OK”, and process the CSV in a separate thread.

After CSV parsing/processing the service should respond to the URL specified in item Processed Reply From Merchant, under Received Reply From Merchant subsection.

Expected Reply From Service:

"TERMINAL NUMBER","UUID","SUCCESS","ERROR MSG","HASH","ALGORITHM"
"11001","5fa3e885-98f2-4e0b-9d29-8c6fe463ec33","1","","bdd07d8c8dcd428536b2a9fbe4ac0f5f9d84f321af5f3d4f26c15968688dea8c","SHA-256"
"11001","7bae3ecf-97c4-43b1-89a0-25797ca325e9","1","","1dc620e8c4d8c82febaa0a2599c693b5a74cd7c0346c7f79af70b6db5d870396","SHA-256"
"11001","18c78348-cd35-4e35-a817-7dd34dad955c","1","","5ce1c3d9408a0c6d015132a67c2630bdddb3e73edd1bfec9c8ee0e7709e15dc2","SHA-256"
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International