Please note that we are no longer onboarding new customers to this version of our API. Please visit our new documentation site https://docs.acquired.com
Get a test account Login

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 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

Endpoints

Time to play - access your API using these endpoints:

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.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id string 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
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.
Acceptable Characters: 0-9 a-z A-z _ -
transaction object
transaction_type string 1-20 The transaction type being performed. Should be set to ‘ACCOUNT_UPDATER’.
Acceptable Characters: a-z A-Z _
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.
Acceptable Characters: 0-9
This service is not completed in real-time. Once we receive 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 received 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.
Acceptable Characters: 0-9 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.
Acceptable Characters: 0-9 a-z A-z _ - ()[]{};~!@#$%^*,./\?:”’ +=`
company_id string 1-11 API Company ID we issue to merchants.
Acceptable Characters: 0-9
mid string 1-11 The merchant ID value. Details the specific MID ID the transaction was processed through.
Acceptable Characters: 0-9
transaction_id string 1-10 Unique ID we assign to each transaction that is processed.
Acceptable Characters: 0-9
transaction_type string 1-20 Transaction type, repeated from the request message.
Acceptable Characters: a-z A-Z _
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 the URL where you would like us to send these account_updater webhooks. After these have been configured, we will provide the IP addresses you will have to whitelist to be able to accept our incoming webhook messages. For more more information on how to configure and use our webhook solution, please see here.

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.
Acceptable Characters: 0-9
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).
bulk_update int 1 Code which identifies if the update was due to a REBILL or a batch run on your expired cards.

0 - Triggered by a declined REBILL.
1 - Triggered by Acquired.com on the 15th of every month in our batch run.
response_code string 1 For Visa cards - we 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 receive 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",
        "bulk_update":"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",
        "bulk_update":"1",
        "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.
Acceptable Characters: 0-9 in the format yyyymmddhhmmss
company_id int 3 API Company ID issued by Acquired to the merchant.
Acceptable Characters: 0-9
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.
Acceptable Characters: 0-9
transaction_id int 1-10 The unique ID generated by Acquired for the account_updater request.
Acceptable Characters: 0-9
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 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 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.