Account Updater

Introduction

Account Updater enables you to check if Visa and Mastercard customer card details have changed, then update those details if they’re for recurring payments. This can prevent payments failing when a customer changes or cancels their card without informing you.

By running periodic reviews, you can check for failed recurring transactions and cards that are near, or past, their expiry date. You can then request updated details for those cards from the card schemes.

Updates are requested from the Visa Account Updater (VAU) and Mastercard Automatic Billing Updater (ABU) services by sending SHA2-512 signed JSON requests.

Using Account Updater enables you to:

  • Reduce costs and need to manually contact customers.

  • Minimise the rejected transaction threshold.

  • Update cards on record with new expiry dates if they have expired.

  • Replace card information if cards have been reported lost or stolen.

Sensitive data and PCI-DSS

Using Account Updater means that you will be capturing, transmitting, and possibly storing card data.

The storage of Sensitive Authentication Data (track data and/or CVV2) post-authorisation is prohibited by Visa and Mastercard, as well as Requirement 3 of the Payment Card Industry Data Security Standard (PCI-DSS).

If you use Account Updater you need to demonstrate your systems handle this data securely and that you take full responsibility for your PCI compliance. This includes, but is not limited to, providing your current Attestation of Compliance certificate and evidence of a recent clean vulnerability scan.

A list of approved Security Assessors can be found at: https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors.

For more information on PCI security standards, see https://www.pcisecuritystandards.org.

Getting Started

Prerequisites

To use Account Updater, you must process recurring or account on file payments and use Cashflows as your acquirer.

Check with your Implementation Manager to see if you qualify for the service.

Calculating request signatures

As with all API calls you will need to send a request signature with any requests.

To ensure server to server messages have been issued by valid users, request messages must be signed. The signature field is a SHA2-512 hash calculated by concatenating your API key (provided during Account Updater sign up) with a string of the request object. If you don’t have your API key please contact your Implementation Manager.

If the signature is incorrect, an error will be returned. Repeated failures will lock your account, if this happens, please contact your Implementation Manager.

For example, if you were making an Account Updater request your request object might look like:

"Request": {
    "MerchantId": "5912345",
    "Details": [
        {
            "CardNumber": "4444333322221111",
            "ExpiryDate": "0120"
        },
        {
            "CardNumber": "5555444433332222",
            "ExpiryDate": "0120"
        },
        {
            "CardNumber": "5555444433331111",
            "ExpiryDate": "0121"
        }
    ]
}

You would prepend your API key onto the string of your request contents:

3031E5834AAD94B05C563292E6590ED13336501627EF1248036838C9BEBC08226A030134B3D791B488C086A97EA521FB192B D578CD41583DCB6DC21A896A497E"MerchantId": "5912345","Details": [{"CardNumber":"4444333322221111","ExpiryDate": "0120"},{"CardNumber":"5555444433332222","ExpiryDate": "0120"},{"CardNumber": "5555444433331111","ExpiryDate": "0121"}]

Warning

Whitespace and new lines in the request object are included in the hash calculation. We use CR-LF for line breaks, however Unix systems often use just LF, and this can affect calculations. If you can’t match signatures but have the correct password hash, remove unnecessary whitespace from your Request nodes.

Then use that string to generate a SHA2-512 key:

35b4957df561b0bc0ad64582416e536f75a7f146d7c548e6df17496a351cecf3367c2d555e0d299657c09aea7f5ab311e3cfc 6a3b7d9ba35112a312efde585c4

Finally, add the generated key as the Signature value in your request:

{
    "ApiKey": "12345678-ABCD-ABCD-ABCD-12345678ABCD",
    "Signature": "35b4957df561b0bc0ad64582416e536f75a7f146d7c548e6df17496a351cecf3367c2d555e0d299657c09aea7f5ab311e3cf c6a3b7d9ba35112a312efde585c4",
    "Request": {
        "MerchantId": "5912345",
        "Details": [
                {
                "CardNumber": "4444333322221111",
                "ExpiryDate": "0118"
            },
                {
                "CardNumber": "5555444433332222",
                "ExpiryDate": "0119"
            },
            {
                "CardNumber": "5555444433331111",
                "ExpiryDate": "0119"
            }
        ]
    },
    "Version": "1.0"
}

Base URL

A single API endpoint is provided for all users making API calls to Cashflows. You must identify each request using your API Key and sign the message with a signature.

All calls use HTTPS through the standard port 443, and TLS v1.2 or higher must be used in line with PCI requirements.

The base URLs for Account Updater are:

  • Test - https://integration.cashflows.com/accountupdater/[commandname].

  • Live - https://live.cashflows.com/accountupdater/[commandname].

The [commandname] is the name of the service being requested. For example, to request an account update, the URL would be: https://live.cashflows.com/accountupdater/requestaccountupdate.

Testing

You should use the test environment when integrating or testing with the Account Updater.

Test data needs to be generated to fully build and test Account Updater. For example, a valid Merchant ID is required to attempt RequestAccountUpdate requests.

Contact your Implementation Manager for more information about test accounts and data.

Updating account details

To check for new account details, you need to first request an account update from the card schemes, then retrieve that update once the request has been processed (typically 24 hours). This is achieved with two request calls:

  1. RequestAccountUpdate

  2. RetrieveAccountUpdate

Each request can contain up to 5,000 card updates, and you can only send one request a day for both Visa and Mastercard. Visa process requests between 18:00 and 22:00 UTC, and requests received after 17:30 UTC will not be processed until the next day. Mastercard’s processing window is around 08:00 UTC.

All requests to Account Updater need to include your API Key, API version, signature, and a request object in your JSON payload.

Parameter

Requirement

Type & size

Details

ApiKey

Mandatory

String (36)

API Key responsible for calling the API

Version

Mandatory

String (10)

Version of the API being called

Signature

Mandatory

String (128)

SHA2-512 Hash of API key and request

Request

Mandatory

Object

A request object

RequestAccountUpdate

The RequestAccountUpdate request asks the card schemes for updated card details for the specified card numbers.

To request updated card details you need to make a RequestAccountUpdate request to the …/accountupdater/requestaccountupdate endpoint, providing your Merchant ID, and the card numbers you want to check.

Request object parameters

Parameter

Requirement

Type & size

Details

MerchantId

Mandatory

String(15)

Merchant Id (Acquirer MID) to send in requests

Details

Mandatory

Object

Contains Details.CardNumber and Details.ExpiryDate

Details.CardNumber

Mandatory

String(20)

The full Primary Account Number on the card

Details.ExpiryDate

Optional

String(4)

The payment card’s expiry date and month (mmyy)

The response will return a RequestId that you can query with RetrieveAccountUpdate after 24 hours, the usual time it takes an RequestAccountUpdate request to process.

Example RequestAccountUpdate request:

{
    "ApiKey": "12345678-ABCD-ABCD-ABCD-12345678ABCD",
    "Signature": "35b4957df561b0bc0ad64582416e536f75a7f146d7c548e6df17496a351cecf3367c2d555e0d299657c09aea7f5ab311e3cf c6a3b7d9ba35112a312efde585c4",
    "Request": {
        "MerchantId": "5912345",
        "Details": [
            {
                "CardNumber": "4444333322221111",
                "ExpiryDate": "0118"
            },
            {
                "CardNumber": "5555444433332222",
                "ExpiryDate": "0119"
            },
            {
                "CardNumber": "5555444433331111",
                "ExpiryDate": "0119"
            }
        ]
    },
    "Version": "1.0"
}

Example RequestAccountUpdate response:

{
    "Response": {
        "RequestId": "6fbc91f55d7e401ea89e91dd5fe52af7",
        "MerchantId": "5912345",
        "Results": null,
        "Status": 1
    },
    "Error": null,
    "Date": "2012-04-21T18:25:43Z",
    "Version": "1.0"
}

The status indicates the current state of the request. For RequestAccountUpdate requests, this is usually 1 (pending) as requests take 24 hours to process.

RetrieveAccountUpdate

To retrieve the updated card details you need to make a RetrieveAccountUpdate request to the …/accountupdater/retrieveaccountupdate endpoint, providing the RequestId, received from the RequestAccountUpdate call.

Note

It can take up to 24 hours for updated card details to be supplied from the initial RequestAccountUpdate request.

Retrieve request object parameters

Parameter

Requirement

Type & size

Details

RequestId

Mandatory

String(32)

Unique ID returned in the response to RequestAccountUpdate request.

The response will return a Status field with the following values:

  • 0 - Unknown

  • 1 - Pending

  • 2 - Complete

  • 3 - Error

  • 4 - Expired (results have already been retrieved or not been collected after 7 days)

A Results object with the following parameters will also be returned:

Parameter

Requirement

Type & size

OldCardNumber

String(20)

The original card number

OldExpiryDate

String(4)

The original expiry date

NewCardNumber

String(20)

The new card number

NewExpiryDate

String(4)

The new expiry date

VauRawResponse

Object

Visa only

AbuRawResponse

Object

Mastercard only

Status

String(20)

  • 0 - Unknown

  • 2 - Complete

  • 3 - Error

Example RetrieveAccountUpdate request:

{
    "ApiKey": "12345678-ABCD-ABCD-ABCD-12345678ABCD",
    "Signature": "2c6d6a6e134bebdfaf76034563e4c3975c5628cf715aa8eb509500976a82af0fc06c5072d1755dfee41ee81aa74c8cb34dac d4b4ec8fa53a4ede209cad65cf56",
    "Request": {
        "RequestId": "6fbc91f55d7e401ea89e91dd5fe52af7"
    },
    "Version": "1.0"
}

Example RetrieveAccountUpdate response:

{
    "Response": {
        "RequestId": "6fbc91f55d7e401ea89e91dd5fe52af7",
        "MerchantId": "5912345",
        "Results": [
        {
            "OldCardNumber": "4444333322221111",
            "OldExpiryDate": "0118",
            "NewCardNumber": "4444333332225555",
            "NewExpiryDate": "0221",
            "VauRawResponse":
        {
            "ResponseCode": "A"
        },
            "Status": 2
        },
        {
            "OldCardNumber": "5555444433332222",
            "OldExpiryDate": "0119",
            "NewCardNumber": "5555444433331000",
            "NewExpiryDate": "0122",
            "AbuRawResponse":
            {
                "ReasonIdentifier": "Update",
                "ResponseIndicator": null
            },
            "Status": 2
        },
        {
            "OldCardNumber": "5555444433331111",
            "OldExpiryDate": "0119",
            "Status": 3
        }
        ],
        "Status": 3
    },
    "Date": "2012-04-21T18:25:43Z",
    "Version": "1.0"
}

API reference

This section lists all currently available Account Updater API commands.

Standard API

Standard request parameters

Parameter

Requirement

Type & size

Details

ApiKey

Mandatory

String (36)

API Key responsible for calling the API

Version

Mandatory

String (10)

Version of the API being called

Signature

Mandatory

String (128)

SHA2-512 Hash of API key and request

Request

Mandatory

Object

A request object

Standard response parameters

Parameter

Type & size

Details

Version

String(10)

Confirmation of the version of the API used in the request

DateTime

Datetime

The date of the response

Error

ErrorResponse

Contains the details for all HTTP 4xx or 5xx responses. The structure is shown below

Response

Object

The response object for all HTTP 2xx responses

ErrorResponse

Parameter

Type & size

Details

Identifier

string

Returned with all HTTP 5xx responses, and can be used by customer services to help identify the exact nature of the error

Code

string

A code associated with the error type

Message

string

Summary of the error

Target

string

For validation errors, this states which property is in error

Details

ErrorResponse

Details about each individual error

RequestAccountUpdate reference

Submit new request for updated card details.

Endpoint: https://live.cashflows.com/accountupdater/RequestAccountUpdate

Request parameters

Parameter

Requirement

Type & size

Details

MerchantId

Mandatory

String(15)

Merchant Id (Acquirer MID) to send in requests

Details

Mandatory

Collection of Objects

Contains Details.CardNumber and Details.ExpiryDate

Details.CardNumber

Mandatory

String(20)

The full Primary Account Number (PAN) on the card

Details.ExpiryDate

Optional

String(4)

The payment card’s expiry date and month (mmyy)

RetrieveAccountUpdate reference

Used to obtain update on a previously requested RequestAccountUpdate.

Endpoint: https://live.cashflows.com/accountupdater/RetrieveAccountUpdate

Retrieve request parameters

Parameter

Requirement

Type & size

Details

RequestId

Mandatory

String(32)

Unique ID returned in the response to RequestAccountUpdate request

Response parameters

Parameter

Type & size

Details

MerchantId

String(15)

The merchant number from the original request

Status

String(20)

  • 0 - Unknown

  • 1 - Pending

  • 2 - Complete

  • 3 - Error

  • 4 - Expired (result already retrieved or not collected after 7 days)

Results

Collection of Objects

See Results Object below.

RequestId

String(32)

Unique ID returned to be used to retrieve results of an account update request

Results object

Parameter

Type & size

Details

OldCardNumber

String(20)

The original card number

OldExpiryDate

String(4)

The original expiry date

NewCardNumber

String(20)

The new card number

NewExpiryDate

String(4)

The new expiry date

VauRawResponse

Object

Visa only, see below

AbuRawResponse

Object

Mastercard only, see below

Status

String(20)

  • 0 - Unknown

  • 2 - Complete

  • 3 - Error

If there is an error the following HTTP status codes may be returned in the response header of the response:

Code

Description

Troubleshooting

400

Bad request

Check for correct formation and mandatory parameters

403

Forbidden

Check the signature calculation

429

Too many requests

Rate limits exceeded or replay protection triggered

500

Internal server error

Please contact us for more information

Scheme codes

Visa Service identifier codes

These codes are returned in the standard response parameter when Visa account number has been queried VauRawResponse.

Parameter

Type & size

Details

ResponseCode

String(1)

The code returned by Visa

Response Code

Description

A

Account number change (account number or account number and expiration date updated)

C

Closed account advice

E

Expiration date change

N

Non-participating BIN

P

Participating BIN, no match

Q

Contact cardholder

V

Match made, account number and expiration date unchanged

Mastercard response parameters

Automatic Billing Updater for Mastercard will return reason identifier and response indicator AbuRawResponse.

Reason Identifier

Description

UPDATE

Match made; update data provided (includes issuer Reason Codes R, B, and P):

  • R – Replacement Card

  • B – Brand Flip to Mastercard

  • P – Mastercard to Mastercard Portfolio

CONTAC

Match made; account closed

EXPIRY

Match made; expiration date changed

VALID

No updates were found but the account is valid

UNKNWN

The account number could not be found in the ABU database (see Response Indicator below)

Response indicator

ABU Validation Response Indicator (displayed only when the Reason Identifier is VALID or UNKNWN).

Response Indicator

Description

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