Account Updater

Account Updater uses Visa’s VAU (Visa Account Updater) and Mastercard’s ABU (Automatic Billing Updater) services to allow merchants to update stored cards. This includes updating the current card number and expiry date for cardholders and making merchants aware when a card has been canceled.

This guide provides information to help you with the request process for updating cards manually as well as how to handle the API responses and what to expect when receiving report details from us.

Account Updater supports one of the following top-level configurations: Update or Insert.

This section focuses on the process for updating cards manually. In this case, you submit a request to us containing the list of stored references for Payer (customer) and Payment Method (card) to be updated.

Authenticate

You must use basic HTTP authentication with each request to the update and status endpoints. The Client ID (Merchant ID) and Shared Secret must be submitted in a specific format:

1. Concatenate your Client ID and Shared Secret with a colon. For example: MerchantId:Secret
2. Encode this string using a Base64 encoder tool like this one. The result will look something like this:
   
   cmVhbGV4c2FuZGJveDpPTXNvTFpuRXZN
   
   
3. The resulting string should be sent as part of the header of your request. It must conform to the
   key : value format as shown below.

So, using our example, the header will be:

Authorization : Basic cmVhbGV4c2FuZGJveDpPTXNvTFpuRXZN

Upload a CSV file

Update requests are submitted by CSV file and are sent as part of a multipart POST request. The file should be attached as follows:

Type: File
Content-type: multipart/form-data; charset=UTF-8
Name: file
Part: {Local location of file being uploaded e.g. C:\pathToFile\file.csv}

If using Postman, the best approach is to use the form-data option and upload the CSV directly to Postman, as shown below.

The request must be submitted to one of the following update endpoints where {currency} is replaced by the currency of the future transactions.

<!-- Live URL for update requests -->
https://api.realexpayments.com/card-updater/jobs/{currency}
<!-- Sandbox URL for test update requests --> 
https://api.sandbox.realexpayments.com/card-updater/jobs/{currency}

The default setting is to allow one successful request to be submitted per currency, per day, to the update endpoint.

• Supported currencies: GBP, EUR, USD, CAD
• Supported card types: Visa, Mastercard

Send the update request

The first step in the process is to send an update request containing the references of Payers and Payment Method to be updated. Files can be submitted to us daily. We will process the enquiry file or submit it to your acquirer on each day (or each weekday, if daily operation is not supported by the acquirer). The Payer and Payment Method references in the request will be used to retrieve the associated card data stored with us, which is then added to the enquiry file.

The update file consists of a comma-separated list of Payer and Payment Method references, predicted amounts, and future transaction dates. If the amount and date are not known, we recommend using an amount of zero and a date of seven days in the future. Payment Method references associated with Visa or Mastercard cards can be submitted in the same request.

Sample update file format

Production

<!-- Blueprint
<Payer Reference>,<Payment Method Reference>,<Amount>,<Transaction Date>
-->
03e28f0e-492e-80bd-20ec318e9334, 3c4af936-483e-a393-f558bec2fb2a ,0 , 20251006
0f357b45-9aa4-4453-a685-c69232e9024f, 10c6a2c7-be7b-a13f-12638937a012 ,200 , 20251004
376a2598-412d-4805-9f47-c177d5605853,ca46344d-4292-47dc-9ced-e8a42ce66977,1000,20251005

Sandbox

In the Sandbox environment, you must use the data below to receive a response file. Using any other data, even if correct, will not provide a response file. This response file will be typically returned within 1 hour. The transaction date must be in the future.

testpayer,realex_test_001,100,20240731
testpayer,realex_test_002,100,20240731
testpayer,realex_test_003,100,20240731
testpayer,realex_test_004,100,20240731
testpayer,realex_test_007,100,20240731
testpayer,realex_test_006,100,20240731
testpayer,realex_test_007,100,20240731
testpayer,realex_test_008,100,20240731
testpayer,realex_test_009,100,20240731
testpayer,realex_test_010,100,20240731
testpayer,realex_test_011,100,20240731
testpayer,realex_test_012,100,20240731
testpayer,realex_test_013,100,20240731
testpayer,realex_test_014,100,20240731

Update file syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) – dependent on another field.

This section focuses on handling the responses you receive when using Account Updater, including sample success/error messages and responses from status requests. We also provide a full explanation of response codes from Visa and Mastercard, along with the actions we take and what you can do if you receive them.

Sample update response

After initial validation of an update request, a JobID is returned in the response. This can be used to track the request through the update lifecycle using the status endpoint. In the event of validation errors occurring, the response will contain additional information on why the request failed.

Successful response

{"jobId":649,"timeStamp":"2016-10-03T14:02:22.852","clientId":"Merchant ID","resultCode":"TRANSFER_COMPLETE"}

Sample error scenarios

{"timestamp":"2016-11-30T11:49:57.896","clientId":"Merchant ID","message":"Invalid Data","resultCode":"INVALID_DATA"}

{"timestamp":"2016-11-30T11:54:31.600+0000","status":401,"error":"Unauthorized","message":"Full authentication is required to access this resource","path":"/card-updater/jobs/GBP"}

Response message syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) – dependent on another field.

Status request

The Status request allows you to query the current status for a particular JobID. We provide a status for each JobID as it goes through the request lifecycle. Each status that can be returned is described in the table below.

Send the status request

The status request must be sent to one of the below endpoints. These endpoints will accept an HTTP GET request. If the content of the initial update request passed validation, the status will be returned (see below). If validation of the initial update request failed, the details of the validation error are returned.

<!-- URL for live status requests -->
https://api.realexpayments.com/card-updater/jobs/{jobid}

<!-- URL for sandbox status requests -->
https://api.sandbox.realexpayments.com/card-updater/jobs/{jobid}

Sample status response

Success

{"status":"AWAITING_SUBMISSION"}

Error

{"status":"VALIDATION_FAILED","errors":[{"errorType":"CARD_NOT_FOUND","errorDescription":"The payer ref / card ref combination provided does not match any card in our system.","payerRef":"TestPayer","cardRef":"TestCard"}]}

Response message syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) – dependent on another field.

Response codes by card brand

The following tables define the response codes of Visa and Mastercard and provide details on our actions as well as actions you can take.

Mastercard response codes

Visa response codes

After successful submission of a request in the live Production environment, the update process will usually take several business days to complete. This includes us submitting the data to the card brands (that is, Visa and Mastercard) and updates from the relevant issuers. Once the update information is received by us, the Payment Method references will be updated as indicated by the response codes received in the file from the acquirer.

We will then email a report to notify you of the completed updates and any cards that were notified as deactivated by the issuer. If required, your application may then submit a Card Delete request for cards notified as deactivated. Alternatively, you can contact the customer to request updated card details and send a Card Edit request.

For cards notified as updated, if your application stores part of the card data (for example, the last four digits of the number), the updated versions of these can be retrieved from the report. Otherwise, no further action is needed.

Client Card Update Report

Summary
Client ID,Date,Time,Total Records,Total Card Updates,Total Card Numbers Changed,Total Expiry Dates Changed,Total Cards Cancelled
myclientid,01/01/2017,09:00,350,199,30,153,5

Report Detail:

Job ID,Payer Ref,Card Ref,Old Cardnumber,Old Expiry,New Cardnumber,New Expiry,Response Code
1234,PayerRef1,CardRef00001,512345XXXXXX7712,1216,512345XXXXXX9159,0718,MA
1234,PayerRef2,CardRef05115,512345XXXXXX5801,1215,,1119,ME
1234,PayerRef4,CardRef47774,412345XXXXXX6872,1218,412345XXXXXX6872,,V9
1234,PayerRef55,CardRef2880,512345XXXXXX2880,0117,512345XXXXXX2880,0619,MA
1234,PayerRef75,CardRef4974,412345XXXXXX6353,1216,,0420,VF
1234,PayerRef777,CardRef9318,412345XXXXXX9318,0219,412345XXXXXX9318,,V9
1234,PayerRef94165456,CardRef1486,412345XXXXXX1486,0916,412345XXXXXX1294,0318,V1
1235,PayerRef1a2a5q5e6,CardRef84847,512345XXXXXX4242,0817,512345XXXXXX4242,,MF
1235,PayerRef554888,CardRef7547854,512345XXXXXX4415,0916,,,MC
...

Validation Failures
Job ID,Payer Ref,Card Ref,Error code
1234,PayerRef1,CardRef848825,INVALID_RESPONSE_CODE
1234,PayerRef2,CardRef745896,INVALID_CARD_NUMBER
1234,PayerRef3,CardRef445787,INVALID_EXPIRY_DATE
1234,PayerRef4,CardRef669874,INVALID_CARD_AND_EXPIRY_DATE
1235,PayerRef4,CardRef4787487,PM_METHODS_DOESN'T_EXIST
...

Report format

Title

The title of the report will always be as follows:

Client Card Update Report

Summary

A summary of the report's contents.

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) – depending on another field.

Report detail

Details of the updates carried out.

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) – depending on another field.

Validation failures

Details of the errors encountered.

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) – depending on another field.