Overview

The Card Account Updater service provides merchants the ability to keep their customers' card data up-to-date.

What's New?

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.

    See the Card Account Updater Reporting topic in the CardPointe Web App User's Guide for detailed information.

Date Updated: 3/13/2021

Expiry formats other than MMYY are no longer supported in PUT requests. 

The expiry is now ignored when provided in an unsupported format, resulting in the account being added with no expiry value. The expiry value is then retrieved from the card brand, as a billable update.

Requirements

To take advantage of the Card Account Updater service, you must meet the following requirements:

  • Your merchant account must be enrolled in the Card Account Updater service.

  • Your merchant account must be acquired by CardConnect.

  • You must use the CardPointe Gateway's Profile service to store customer payment account information, or manually enroll specific accounts by making a PUT request to the updater resource of the CardPointe Gateway API.

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

Limitations

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 isvsupport@cardconnect.com before enrolling any accounts using the Card Account Update API.

Getting Started

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
  • account closure

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:

CAU v2 flowchart

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 individual accounts.

See the CardPointe Gateway Profile service description for more information on stored profiles.

Postman Collection

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.

Run in Postman

Getting Updates using the CardPointe Gateway API

The Card Account Updater API includes support for tokenization of clear text primary account numbers (PANs) in PUT requests, pagination of GET requests, and the ability to submit DELETE requests.

Use the PUT method to manually submit tokens or clear text PANs to the Card Account Updater service.

Use the GET method to retrieve data about recent updates.

Use the DELETE method to manually remove tokens from the Card Account Updater service.

The DELETE method does not unenroll accounts that are associated with a stored profile. Use the CardPointe Gateway profile endpoint to set "auoptout":"Y" for accounts associated with a stored profile.

Updater Service URL

Your application communicates with the CardPointe Gateway RESTful web service using the following base URL:

https://<site>.cardconnect.com/cardconnect/rest/v2/updater

Authorization

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

Authorization:

Basic

Content-Type:application/json

PUT Request Body

Parameters in bold are required.

Body ParameterTypeDescription
merchidString

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.

accountsArray

An array of accounts to enroll. See Accounts Array for details.

Note: The maximum number of accounts per PUT request is limited to 2,000

Accounts Array

The accounts array consists of objects containing the account parameter, and optionally, the expiry parameter.

Body ParameterTypeDescription
accountStringThe 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.
expiryStringThe 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.

Updater Service PUT Response

A successful PUT request returns a JSON-encoded response with a summary of the results, including the tokenized values of any clear text PANs provided, and any errors encountered.

An unsuccessful PUT request returns HTTP Status 4xx, with a JSON-encoded response that includes the errors array containing additional information.

FieldTypeDescription
merchidStringThe CardPointe Merchant ID specified in the request
totalNumberThe total number of updates
successesNumberThe number of accounts successfully enrolled
failuresNumber

The number of accounts not enrolled

tokensArray

An array of enrolled accounts. See Tokens Array for details.

errors
Array

An array of errors encountered. See Errors Array for details.

Tokens Array

For each clear text PAN provided in the request, an object is returned within the tokens array, containing the account provided and its associated token.

FieldTypeComments
accountStringThe PAN submitted in the request
tokenStringThe tokenized value of the PAN

Errors Array

For each failure, an object is returned within the errors array, containing the field and associated error message.

FieldTypeDescription
fieldStringThe token or PAN that caused the error

Note: HTTP Status 4xx responses return the request field that caused the error.
messageStringOne of the following error messages:
  • invalid card
  • can not tokenize
Note: HTTP Status 4xx responses return additional details about the error encountered.

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.

Additionally, you can view update history details for the past year in the CardPointe Web App, on the Card Updates page. See the Card Account Updater Reporting topic in the CardPointe Web App Users' Guide for more information.


GET Request Headers

Authorization:Basic

GET Request Parameters

Parameters in bold are required.

ParameterTypeComments
merchidQuery

The Merchant ID associated with the stored profiles or accounts

Note: The merchant account must be enrolled in the Card Account Updater service.

daysBackQuery

The number of days prior to the current date, used to retrieve updates reported within that period

Note: Defaults to 30 if not provided.

dateQuery

A date in YYYYMMDD format

Note: This parameter is now deprecated. The current date is used in conjunction with the daysBack parameter to determine the applicable period for retrieving updates.

pageQueryThe number of the page being requested

Note:
Defaults to 1 if not provided.
binInfoQuery

A true or false value where true returns the Bank Identification Number (BIN) information when an UPDATE record for the account includes a new card number.

Note: Defaults to false if not provided.

Updater Service GET Response

The JSON-encoded response includes all updates that occurred within the 30 days preceding the current date, or in the preceding number of days specified using the daysBack parameter.

FieldTypeComments
pageNumberNumberThe number of the current page of results
perPageSizeNumberThe number of results per page
currentPageSizeNumberThe number of results contained in the current page
totalPagesNumberThe total number of pages
totalUpdatesNumberThe total number of updates for the period
updatesStartDateStringThe start date of the time period used to retrieve updates
updatesEndDateStringThe current date
updatesArrayAn array of enrolled account updates. See Updates Array for details.

Updates Array

The updates array consists of objects for each update, containing information about the change in account data and status.

FieldTypeComments
dateupdatedStringThe date when the account was last updated, in YYYYMMDD format
newtokenString

The new token, if the previous PAN was replaced with a new PAN

Note: Only returned when "status" : "UPDATE"

oldtokenStringThe existing token associated with the stored profile or account
newexpiryStringThe updated expiration date for the card associated with the account, in YYYYMMDD format
statusString

The change in status since the last update. Status can be one of the following values:

  • CLOSED - The account has been closed
  • CONTACT - Contact the card issuer for information on the status of this account
  • EXPIRY - The account has a new expiration date
  • NOGOOD - The account has been reported as invalid by the card brand
  • UPDATE - The account details have been updated
binInfoObject

The BIN information for the account. Reference the CardPointe Gateway API documentation for more information about the fields returned with the binInfo object.

Note: Only returned when binInfo=true in the GET request and "status" : "UPDATE".

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

Authorization:

Basic

Query String Request Parameters

Parameters in bold are required.

ParameterTypeComments
merchidQueryThe Merchant ID associated with the stored profiles or accounts
accountsQuery

A comma-separated list of tokens to unenroll

Note: The maximum number of tokens per query string DELETE request is 1,897

JSON DELETE Requests

Submitting a DELETE request as JSON requires basic authentication and the application/json content-type specified in the request header. The maximum number of tokens submitted in a JSON is 2,000.

JSON Request Headers

Authorization:Basic

Content-Type:

application/json

JSON Request Body

Parameters in bold are required.

ParameterTypeComment

merchid

StringThe Merchant ID associated with the stored profiles or accounts
accountsArray of Strings

An array of tokens to unenroll

Note: The maximum number of tokens per JSON DELETE request is 2,000

Updater Service DELETE Response

A successful DELETE request returns a JSON-encoded response with a summary of the results, including any tokens which could not be unenrolled.

FieldTypeComments
merchidStringThe Merchant ID associated with the stored profiles or accounts
totalNumberThe number of token received from the request
deletedNumberThe number of tokens successfully unenrolled
notDeletedArrayAn array of accounts that encountered an error. See Not Deleted Array for details.

Not Deleted Array

For each token that cannot be unenrolled, an object is returned within the notDeleted array, containing the account and associated error message.

FieldTypeComments
accountStringThe token that cannot be unenrolled
messageStringThe error message

An unsuccessful DELETE request returns HTTP Status 400 with a JSON-encoded response, containing the errors array.

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:

UAT Status ResponseLast 4
UPDATE1111, 2222
EXPIRY3333, 4444
CLOSED5555
NOGOOD7777
Simulate no change in status
9999

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:

FieldPossible Values
newexpiry20301231, 20351231, 20401231, 20451231, 20461231, or 20781231
newtoken

A randomly generated token to simulate a token for a new payment account