Account Updater

Visa’s Account Updater (VAU) and MasterCard’s Automatic Billing Updater (ABU) allows your business to connect into each of the Card Schemes to obtain new updated card details for those cards that have either expired or have been reported lost or stolen.

A single API request is submitted for each card / token and we handle the rest. In the event that new card details are available, we will automatically update the token within our environment with the new details. This means that when your next payment attempt is due to take place, the request should be successfully authorised – provided the customer has sufficient funds or nothing out of the ordinary occurs.

Auto Update

We have designed the Account Updater solution to be as seamless as possible. To do so, we will initiate a request on your behalf in a few different scenarios.

In these scenarios we update the existing token in our system so no need to change your integration to us - just keep processing payments as normal.

Lost or Stolen Card

If you try to process an authorisation request against a stored card and we return a 402 (Declined: Lost or Stolen Card) response code we will automatically check if a replacement has been issued to the cardholder and inform you via webhook.

Expired Card

If you try to process an authorisation request against a stored card and we return either a 204 (Error: Invalid or Expired cardexp) or 325 (Declined: Card Expired) response code we will automatically check if a new details are available and inform you via webhook.

Card Expiring

Each month (on the 15th) we will proactively try to get updated card details for all the cards you have stored with us that are about to expire. For example, on the 15/10/2019, we will query all the cards with an expiry date of 102019 you have tokenised with us. Again - we'll update you with any new details via webhook.

Manual Update

Don't forget you will need to review the API Intro before integrating this solution for the request_hash and response_hash.

From time to time, you may want to check if an update is available outside of our Auto Update scenarios. No problem at all - just submit this simple API request:

{
    "timestamp":"20190601090000",
    "company_id":"113",
    "company_pass":”password”,
    "request_hash":"cc8882cb0437863f711432a1d143fe6e9f92ce74080a0f30a0dac3a718ad1c28",
    "transaction":{
        "transaction_type":"ACCOUNT_UPDATER",
        "original_transaction_id":"24901878"
    }
}
Parameter Format Length Description
timestamp string 14 Date and time of transaction submission, in the format yyyymmddhhmmss.
company_id string 1-11 API Company ID we issue to merchants.
company_pass int/string 1-30 API Password we issue to merchants.
request_hash string 64 Value of your encrypted hash. Take a look here for more information.
transaction object
transaction_type string 1-20 The transaction type being performed. Should be set to ‘ACCOUNT_UPDATER’.
original_transaction_id int/string 1-10 The transaction_id value returned in the transaction response of the original INIT authorisation request - which represents the token.
This service is not completed in real-time. Once we recieve your request we pass it onto the schemes immediately and query them every 20 minutes for an update - as soon we have one we'll let you know via webhook.

We will respond back to let you know that we have recieved your request and if everything has worked as expected - an 11 (Pending) response code just like the example below:

{
    "timestamp":"20190601090000",
    "response_code":"11",
    "response_message":"Pending",
    "company_id":"113",
    "mid":"1045",
    "transaction_id":"24901878",
    "transaction_type":"ACCOUNT_UPDATER"
    "bank_response_code":"1",
    "response_hash":"5f07efac8a6ccd48124051843a1fd730445d1775bd35e92b1c270f69439749ec"
}
Parameter Format Length Description
timestamp string 14 Date and time of transaction submission, in the format yyyymmddhhmmss.
response_code string 1-3 Code describing the transaction results. A full list of possible response codes are outlined below:
11 - Pending
908 - System error: Invalid response from bank
response_message string 1-100 Message describing the transaction results.
company_id string 1-11 API Company ID we issue to merchants.
mid string 1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
transaction_id string 1-10 Unique ID we assign to each transaction that is processed.
transaction_type string 1-20 Transaction type, repeated from the request message.
bank_response_code int 2 Status code that is assigned by the Card Schemes. It is expected that the majority of requests will be assigned a “1” pending response status (given that updated card details are not provided in real-time) - see list of response codes below:
0 - Unknown
1 - Pending
2 - Complete
4 - Expired
response_hash string 1-30 Verification hash value.

Webhook Notification

Get in contact with support@acquired.com and let us know where you would like us to send these account_updater webhooks.

It doesn't matter if you are using the Auto Update or Manual Update process - once we have a response from the card schemes we need to let you know. We will do this via the account_updater webhook.

These are some the key fields you should be looking out for and what they mean:

Parameter Format Length Description
transaction_id int 1-10 The unique ID generated by Acquired for the account_updater request
parent_id int 1-10 The transaction_id value returned in the original INIT authorisation request - which represents the token.
status int 1 Lets you know the outcome of the update request. Possible values are:

1 - Updated (Account details successfully updated)
2 - Not Updated (There is no update available for the account provided)
3 - Error (An error occurred with the account updater request)
response_code string 1 For Visa cards - will let you know what happened.Possible values are:

A - Account number changed (expiry date unchanged)
C - Closed account advice
E - Expiry date changed
N - Non-participating BIN
P - Participating BIN, no match
Q - Contact cardholder advice
V - Match made, account number and expiry date unchanged
reason_identifier string 5-10 For MasterCard - will let you know what happened. Possible values are:

UPDATE - Account number changed (expiry date unchanged)
CONTAC - Closed account advice
EXPIRY - Expiry date changed
VALID - Non-participating BIN
UNKNWN - Participating BIN, no match
response_indicator string 1 For MasterCard - a bit more information on the update. Possible values are:

V - Matches the account as reported by the Issuer
P - No match, participating BIN / Issuer
N - No match, non-participating BIN / Issuer
R - Replacement card
B - Brand Flip to MasterCard match
C - Closed account
E - Update expiration date
These are just some of the fields you can expect - take a look here for more detailed information on each field.

Here are some handy examples of the possible webhooks you might recieve for different scenarios.

Visa

{
    "id":"56C6DE12-5E42-32F0-2B23-8D5DA29F2D59",
    "timestamp":"02272018065704",
    "company_id":"113",
    "hash":"cc8882cb0437863f711432a1d143fe6e9f92ce74080a0f30a0dac3a718ad1c28",
    "event":"account_updater",
    "mid":"1045",
    "list":[ {
        "transaction_id":"6509500",
        "parent_id":"138498",
        "status":"1",
        "update_billing":{
            "old_cardnumber":"424242XXXXXX4242",
            "old_expdate":"092018",
            "new_cardnumber":"424242XXXXXX1212",
            "new_expdate":"102023"
        },
        "card_scheme_response":{
            "response_code":"A",
            "reason_identifier":"",
            "response_indicator":""
        }
    } ]
}
{
    "id":"56C6DE12-5E42-32F0-2B23-8D5DA29F2D59",
    "timestamp":"02272018065704",
    "company_id":"113",
    "hash":"cc8882cb0437863f711432a1d143fe6e9f92ce74080a0f30a0dac3a718ad1c28",
    "event":"account_updater",
    "mid":"1045",
    "list":[ {
        "transaction_id":"3429524",
        "parent_id":"222398",
        "status":"2",
        "update_billing":{
            "old_cardnumber":"424242XXXXXX4242",
            "old_expdate":"092018",
            "new_cardnumber":"",
            "new_expdate":""
        },
        "card_scheme_response":{
            "response_code":"V",
            "reason_identifier":"",
            "response_indicator":""
        }
    } ]
}

MasterCard

{
    "id":"56C6DE12-5E42-32F0-2B23-8D5DA29F2D59",
    "timestamp":"02272018065704",
    "company_id":"113",
    "hash":"cc8882cb0437863f711432a1d143fe6e9f92ce74080a0f30a0dac3a718ad1c28",
    "event":"account_updater",
    "mid":"1045",
    "list":[ {
        "transaction_id":"8734990",
        "parent_id":"456911",
        "status":"1",
        "update_billing":{
            "old_cardnumber":" 533409XXXXXX1681",
            "old_expdate":"092018",
            "new_cardnumber":"530514XXXXXX4597",
            "new_expdate":"102023"
        },
        "card_scheme_response":{
            "response_code":"",
            "reason_identifier":"UPDATE",
            "response_indicator":"R"
        }
    }]
} 
{
    "id":"56C6DE12-5E42-32F0-2B23-8D5DA29F2D59",
    "timestamp":"02272018065704",
    "company_id":"113",
    "hash":"cc8882cb0437863f711432a1d143fe6e9f92ce74080a0f30a0dac3a718ad1c28",
    "event":"account_updater",
    "mid":"1045",
    "list":[ {
        "transaction_id":"6928721",
        "parent_id":"742123",
        "status":"2",
        "update_billing":{
            "old_cardnumber":" 533409XXXXXX1681",
            "old_expdate":"092018",
            "new_cardnumber":"",
            "new_expdate":""
        },
        "card_scheme_response":{
            "response_code":"",
            "reason_identifier":"VALID",
            "response_indicator":"V"
        }
    } ]
}

Webhook Parameters

Within the webhook notification that we send, you will receive the following parameters.

Parameter Format Length Description
id string 36 Unique ID assigned to each webhook notification, as per existing webhook logic.
timestamp date 14 The date and time the webhook was triggered in yyyymmddhhmmss format
company_id int 3 API Company ID issued by Acquired to the merchant
hash string 64 The hash field used to verify that the contents are received securely
event Always set to “account_updater”
mid string 4 API MID ID issued by Acquired to the merchant
transaction_id int 1-10 The unique ID generated by Acquired for the account_updater request
parent_id int 1-10 The transaction_id value returned in the transaction response of the original INIT authorisation request - which represents the token.
Status int 2 Code which identifies the outcome of the update request. Possible status codes:

1 - Updated (Account details successfully updated)
2 - Not Updated (There is no update available for the account provided)
3 - Error (An error occurred with the account updater request)
update_billing object
old_cardnumber int 12-19 Contains the masked cardnumber of the existing token
old_expdate string 6 Contains the expiry date of the existing token in the format MMYYYY
new_cardnumber int 12-19 Contains the masked cardnumber of the new token
new_expdate string 6 Contains the expiry date of the new token in the format MMYYYY
card_scheme_response object
response_code string 1 The code that is returned by Visa when a Visa account number has been queried.Possible status codes:

A - Account number changed (expiry date unchanged)
C - Closed account advice
E - Expiry date changed
N - Non-participating BIN
P - Participating BIN, no match
Q - Contact cardholder advice
V - Match made, account number and expiry date unchanged
reason_identifier string 5-10 The reason identifier code that is returned by Mastercard when a Mastercard account number has been queried.

UPDATE - Account number changed (expiry date unchanged)
CONTAC - Closed account advice
EXPIRY - Expiry date changed
VALID - Non-participating BIN
UNKNWN - Participating BIN, no match
response_indicator string 1 The response indicator code that is returned by Mastercard when a Mastercard account number has been queried.

V - Matches the account as reported by the Issuer
P - No match, participating BIN / Issuer
N - No match, non-participating BIN / Issuer
R - Replacement card
B - Brand Flip to MasterCard match
C - Closed account
E - Update expiration date