The Card Account Updater service provides merchants the ability to keep their customers' card data up-to-date.
Date Updated: 11/13/2021
GET Request Support for Profiles
The GET request now includes an optional query parameter, profiles=true, to include corresponding CardPointe Gateway profile details (profileid/acctid pair) for updates linked to profiles in the GET response.
Date Updated: 7/20/2021
CONTAC Status Added to GET Response
The status field in the GET response now supports the CONTAC status, which indicates that you should contact the issuer for more information on the status of the card account.
Card Account Updater Reporting
Card Account Updater reporting is now available in the CardPointe web application. The Card Updates page, available from the Reporting tab, includes an Update History report that displays all Card Account Updater events that occurred within the past year, as well as a Decline Report that displays all declined transactions and the most recent update for each card.
If you are using the CardPointe Gateway profile service, profiles must include "auoptout":"N" (the default value if not specified). Setting "auoptout":"y" opts a profile out of the Card Account Updater service, and the profile will not be checked for updates.
Whether you are using the CardPointe Gateway's profile service or you are managing your own cardholder profiles using tokens, you must comply with the Visa and Mastercard Stored Credential Transaction Framework Mandate. This card brand mandate includes requirements for obtaining cardholder consent, as well as API and application changes required to appropriately identify transactions using stored customer data. See our support article for detailed information on these requirements.
Use the inquireMerchant endpoint of the CardPointe Gateway API to determine whether the merchant account is enrolled in the Card Account Updater service.
Consider the following limitations:
Card Account Updater is only available for merchants on the First Data North and Rapid Connect back-end processors.
This service only provides updates for Visa, Mastercard, and Discover accounts.
Additionally, the Card Account Updater API is intended as alternative solution to enrolling accounts in the Card Account Updater Service via stored profiles. Using both solutions may cause data integrity issues.
If you currently use the CardPointe Gateway's Profile service to store and manage cardholder profiles, contact firstname.lastname@example.org before enrolling any accounts using the Card Account Update API.
To use the Card Account Updater service, you must be enrolled in the service. Contact Support to add the Card Account Updater service to your merchant account.
How it Works
The Updater service requests daily updates from Visa, Mastercard, and Discover for accounts that are enrolled in this service via CardPointe Gateway profiles, and accounts that have been enrolled using this API. The card brands respond within 3-5 days with any changes to the account, such as:
new account number
new expiration date
Accounts that are stored in a CardPointe Gateway profile and enrolled in this service are updated automatically when changes to card data are reported by the card brand, while changes to card data for accounts that have been enrolled using the API are stored and can be retrieved at any time using the GET request.
If the card brand reports that a new card has replaced the existing one, or a replacement card was issued with a new expiration date, the new card data is tokenized and takes the place of the previous card data for that account. The new card data is then continually monitored for any further changes.
If the card brand reports that an account has been closed, or a newly enrolled account is invalid, the account is no longer monitored for updates.
If the card brand reports no change in card data for a specific account, the Updater service continues to request updates for that account. Requests for changes in card data are sent daily, but as the card brands typically respond within 3-5 days, an individual account is checked 1-2 times per week for any change.
The following diagram illustrates the Card Account Updater service workflow:
Enrolling an Account
Accounts can be enrolled by setting "auoptout":"N"
for a CardPointe Gateway's profile, or by using a PUT request to the updater endpoint of the CardPointe Gateway API to manually enroll
To help you get started with your integration, we have created a Postman Collection that includes all of the requests outlined in this document.
Included with the collection is a Postman Environment containing variables for your API key and Merchant ID. Enter your API key and Merchant ID in these environment variables before sending any API requests.
A username and password are required in the HTTP Authorization Header
property in each API request. Use the API credentials that were provided for use with your merchant account.
Basic Authorization is expected, using a Base64-encoded username and
password string as the value. If this value is incorrect or not provided
in the request header, HTTP Status 401 Unauthorized is returned
to the caller.
See the API Connectivity Guide for more information on connecting to the CardPointe Gateway and other services.
Updater Service PUT Request
The PUT request enrolls accounts in the Card Account Updater service manually, by supplying tokens or clear PANs. These accounts are monitored for changes in account status, expiry, or card number. Card Account Updater relies on information provided by Visa, Mastercard, and Discover to determine when a change has occurred, and stores the changes for retrieval using the GET method.
PUT Request Headers
PUT Request Body
Parameters in bold are required.
The CardPointe Merchant ID associated with the stored profiles
Note: The merchant account must be acquired by CardConnect and enrolled in the Card Account Updater service.
Note: The maximum number of accounts per PUT request is limited to 2,000
The accounts array consists of objects containing the account parameter, and optionally, the expiry parameter.
The 16 digit token or PAN to enroll
Note: If a clear PAN is provided, the PAN is tokenized and the token is returned in any GET method responses.
The card's expiration date in MMYY format
Note: To avoid potential charges as a result of the service obtaining the expiry automatically, it is best practice to include the expiry whenever possible. Omitting the expiry or providing the expiry in an incorrect format will result in the expiry returned by the card brands to be counted as a billable update due to the mismatch.
"errors" : [
"field" : "accounts",
"message" : "must not be null or missing or empty"
Updater Service GET Request
The GET request retrieves all available account changes that have occurred within the 30 day period preceding the current date, or within the previous number of days specified using the daysBack parameter.
If no update records are available, the response returns an empty array for the updates field.
Updater Service DELETE Request
The DELETE request unenrolls accounts that have been manually added
using the PUT method. You can specify the accounts to unenroll in either a query string or JSON-encoded request.
It is not possible to use the DELETE method to unenroll an account associated with a stored profile. Use the CardPointe Gateway profile endpoint to set "auoptout":"Y" for accounts associated with a stored profile.
Query String DELETE Requests
Submitting a DELETE request as a query string requires only basic authentication. The maximum number of tokens submitted in a query string is 1,897.
Query String Request Headers
Query String Request Parameters
Parameters in bold are required.
The Merchant ID associated with the stored profiles or accounts
A comma-separated list of tokens to unenroll
Note: The maximum number of tokens per query string DELETE request is 1,897
For each token that cannot be unenrolled, an object is returned within the notDeleted array, containing the account and associated error message.
The token that cannot be unenrolled
The error message
Example: Successful DELETE Response Body
"merchid" : "1234567890",
"total" : 3,
"deleted" : 2,
"notDeleted" : [
"account" : "9405271370445901",
"message" : "account/token does not exist in CAU database"
An unsuccessful DELETE request returns HTTP Status 400 with a JSON-encoded response, containing the errors array.
Example: Unsuccessful DELETE Response Body
"errors" : [
"field" : "accounts",
"message" : "accounts size must be less than 500"
Testing in the UAT Environment
The UAT environment for First Data North and Rapid Connect platforms emulates account updates and the responses expected in the production environment. This allows you to send PUT, GET, and DELETE requests for testing purposes.
Account updates are emulated in the UAT environment at an accelerated pace to aid in testing your integration. The updates reported by the card brands every 3-5 days in the production environment are emulated in the UAT environment 30 minutes following the initial PUT request, with daily updates emulated thereafter.
Testing Account Enrollment
Use the PUT request to enroll test PANs or tokens in the UAT environment, just as you would in the production environment. An update is generated for enrolled accounts 30 minutes following the initial PUT request.
To test for an individual use case, enroll an account where the last 4 digits matches a value used to generate a specific update status, as explained in the next section.
Simulating a Specific Update Status
The UAT environment is configured to return a specific update status when the last 4 digits of the account match one of the values in the table below:
If an account has already received an UPDATE, CLOSED, or NOGOOD response, then you must delete and re-enroll the account to continue using it for testing.
UAT Status Response
Simulate no change in status
Testing Account Updates
Use the GET request to retrieve the emulated updates for enrolled accounts. Emulated updates are generated 30 minutes following the initial PUT request, and subsequent updates are emulated once per day thereafter.
A randomized update is emulated unless the last 4 digits of the account match a value used to simulate a specific update status, or the account's current status is CLOSED or NOGOOD.
Use the DELETE request to unenroll an account that is no longer receiving emulated updates due to a CLOSED or NOGOOD status. You can then enroll the account again using the PUT request to trigger a new update.
You can use this procedure to trigger a new update for accounts in any status, however this functionality is limited to the UAT environment as an aid in testing your integration.
You should also note that the emulator randomly selects a number of accounts that receive no update in status during each update cycle in the UAT environment. This is to simulate the behavior in the production environment where no update is reported by the card brand. Therefore not all accounts enrolled in the UAT environment will be returned in the GET response.
When an update is generated for an account, the emulator returns the following possible values in the GET response:
20301231, 20351231, 20401231, 20451231, 20461231, or 20781231
A randomly generated token to simulate a token for a new payment account