Account Updater is a vital service that automatically checks and updates account numbers and expiration dates for stored cards on file, ensuring seamless transactions and reducing declines for recurring payments. This comprehensive guide covers the key aspects of Account Updater to help merchants optimize their payment processes.
Setting Up Account Updater
Before getting started, you must ensure your account is enabled for the Account Updater feature. You can find out if you have access by logging into the Portal and clicking Customers from the Portal navigation sidebar. If a plus and dropdown reveal the Payment Updates page, your account has already been enabled.
If you do not see the Payment Updates page, your account still needs the Account Updater feature enabled. Contact your service provider to have the feature enabled.
Account Updater supports Visa, Mastercard, and Discover cards. Token IDs will remain the same throughout each update.
Enable Account Updater Parameters
To enable the Account Updater parameter and its related sub-parameters, follow these steps:
Account Updater Enablement - Portal
Step 1: Access the Group or Merchant Profile page. Then select Parameters from the left-hand menu.
Step 2: Click Add Parameters, then click the edit icon in the upper right corner of the page.
Step 3: Scroll to the “Extra” section, then enable the following:
Step 4: Click the confirm icon in the upper right corner of the page to confirm the enablement.
Result: The Account Updater feature has been enabled for the individual Merchant or Group, and will update both standard card-on-file and subscription tokens, providing each Merchant with up-to-date, valid cardholder tokens to continue subscriptions, recurring payments, or single payments with card-on-file.
Account Updater Enablement - API
Parameters Headers |
CODE
POST /parameters HTTP /1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com
|
Request Body
CODE
{
"login": "t1_log_123abc4d567890efg1h2i34",
"org": "t1_org_123abc4d567890efg1h2i34",
"accountUpdaterEnabled": 1,
"updateAllTokensEnabled": 1,
"accountUpdaterFrequency": 30,
"inactive": 0,
"frozen": 0
}
Required Parameter | Type | Description | Valid Values |
---|
login
| ID | ID for the user that owns this parameter configuration. Typically a Referrer or Facilitator. | Format: t1_log_123abc4d567890efg1h2i34
|
org
| ID | The ID of the Merchant Group (org) the enabled parameter(s) will be assigned to. | Format: t1_org_123abc4d567890efg1h2i34
|
accountUpdaterEnabled
| boolean | Whether payments will be checked for updates. Payments will be checked and updated if enabled. | Valid Values: Default is 0 |
updateAllTokensEnabled
| boolean | Whether all tokenized payments will be checked for updates or just subscription tokens. Payments will be checked and updated if enabled. | Valid Values: Default is 0 |
accountUpdaterFrequency
| number | The frequency (in days) of which to check for payment updates. The default setting is 30. | Any whole number between 1 and 365 . |
inactive
| boolean | | Valid Values: Default is 0 |
frozen
| boolean | | Valid Values: Default is 0 |
Example Response Body
CODE
{
"id": "p1_prm_123abc4d567890efg1h2i34",
"created": "2023-03-18 01:03:27.5514",
"modified": "2024-03-18 01:03:27.5514",
"creator": "t1_log_123abc4d567890efg1h2i34",
"modifier": "t1_log_123abc4d567890efg1h2i34",
"login": "t1_log_123abc4d567890efg1h2i34",
"org": "t1_org_123abc4d567890efg1h2i34",
"accountUpdaterEnabled": 1,
"updateAllTokensEnabled": 1,
"accountUpdaterFrequency": 30,
"inactive": 0,
"frozen": 0
}
Parameter | Type | Description | Valid Values |
---|
id
| ID | The ID of the newly created Parameter configuration. | Format: t1_prm_123abc4d567890efg1h2i34
|
created
| date-time | The date the Parameter configuration was first created. | Format: YYYY-MM-DD HH:MM:SS (UTC) Example: 2024-03-29T21:26:55.016Z
|
modified
| date-time | The date the Parameter configuration was last modified, if applicable. | Format: YYYY-MM-DD HH:MM:SS (UTC) Example: 2024-03-29T21:26:55.016Z
|
creator
| ID | The User (Login) ID for the user that created the Parameter configuration. | This field is stored as a text string. Example Format: t1_log_123abc4d567890efg1h2i34
|
modifier
| ID | The User (Login) ID for the user that last modified the Parameter configuration. | This field is stored as a text string. Format: t1_log_123abc4d567890efg1h2i34
|
login
| ID | ID for the user that owns this parameter configuration. Typically a Referrer or Facilitator. | Format: t1_log_123abc4d567890efg1h2i34
|
org
| ID | The ID of the Merchant Group (org) the enabled parameter(s) will be assigned to. | Format: t1_org_123abc4d567890efg1h2i34
|
accountUpdaterEnabled
| boolean | Whether payments will be checked for updates. Payments will be checked and updated if enabled. | Valid Values: Default is 0 |
updateAllTokensEnabled
| boolean | Whether all tokenized payments will be checked for updates or just subscription tokens. Payments will be checked and updated if enabled. | Valid Values: Default is 0 |
accountUpdaterFrequency
| number | The frequency (in days) of which to check for payment updates. The default setting is 30. | Any whole number between 1 and 365 . |
inactive
| boolean | | Valid Values: Default is 0 |
frozen
| boolean | | Valid Values: Default is 0 |
Note: Payment Update parameters can only be enabled for individual Merchants using the Portal. We recommend enabling them from the Group level as this can be done via API or the Portal and will apply to multiple Merchants simultaneously, including Merchants you add to that Group in the future.
When cardholder account information is updated, you’ll receive one of the following response codes upon successful update:
Response | Description |
---|
“Account number was changed” | Submit the account number returned in the completion response. |
“Account was closed” | Contact the cardholder for updated information. |
“Expiration date was changed” | Submit the expiration date returned in the completion response. |
“Issuing bank does not participate in the update program” | The issuer does not participate in the Account Updater program. Submit original card information. |
“Contact cardholder for updated information” | Contact the cardholder for their updated card information |
“No match found” | There was no match found in the updated information. Submit the original card information |
“No changes found” | Submit the original card information. |
Warning: A status of Failed will return the following responses:
Invalid credit card number - The card data failed validation. You will need to correct the issue and resubmit.
Invalid expiration date - The expiration date failed validation. You will need to correct the issue and resubmit.
To review updated account information after enabling the Account Updater feature, follow these steps:
Review Updated Account Info - Portal
Step 1: Click the “+” icon next to Customers on the Portal navigation sidebar, then select Payment Updates.
Step 2: You now have a view of the token information, or “Payment Updates” for all cardholders on file.
Displayed Data: Use the list icon ( ) to customize your displayed table data.
More Info: Use the arrow () on each listing to show or hide additional data.
Filter: Use the SORT BY box to sort table listings by your preferred criteria
Search: Utilize the search bar to locate cardholders, the last 4 of their card, or other criteria quickly.
Export: Download the table data in CSV or XLS format for efficient customer communication
Review Updated Account Info - API
Payment Updates (Account Updater) Headers |
CODE
GET /paymentUpdates HTTP /1.1
Content-Type: application/json
Accept: application/json
APIKEY:{{apiKey or txnSessionKey}}
Host: api-test.payrix.com
|
Example Response Body
CODE
{
"id": "p1_pmu_123abc4d567890efg1h2i34",
"created": "2023-03-18 01:03:27.5514",
"modified": "2024-03-18 01:03:27.5514",
"creator": "t1_log_123abc4d567890efg1h2i34",
"modifier": "t1_log_123abc4d567890efg1h2i34",
"paymentUpdateGroup": "p1_pug_123abc4d567890efg1h2i34",
"status": "pending",
"token": "p1_tok_123abc4d567890efg1h2i34",
"account": null,
"platform": "VANTIV",
"ref": null,
"clientRef": "123456789",
"message": "The expiration date was changed.",
"expiration": "1024"
}
Parameter | Type | Description | Valid Values |
---|
id
| ID | The ID of the newly created Payment Update record entry. | Format: t1_pmu_123abc4d567890efg1h2i34
|
created
| date-time | The date the Payment Update record entry was first created. | Format: YYYY-MM-DD HH:MM:SS (UTC) Example: 2024-03-29T21:26:55.016Z
|
modified
| date-time | The date the Payment Update record entry was last modified, if applicable. | Format: YYYY-MM-DD HH:MM:SS (UTC) Example: 2024-03-29T21:26:55.016Z
|
creator
| ID | The User (Login) ID for the user that created the Payment Update record entry. | This field is stored as a text string. Example Format: t1_log_123abc4d567890efg1h2i34
|
modifier
| ID | The User (Login) ID for the user that last modified the Payment Update record entry. | This field is stored as a text string. Format: t1_log_123abc4d567890efg1h2i34
|
paymentUpdateGroup
| ID | The PaymentGroup resource that this paymentUpdatebelongs to. | This field is stored as a text string. Format: t1_pug_123abc4d567890efg1h2i34
|
status
| string | The status of the paymentUpdate. | pending - The paymentUpdate was sent and is pending to be processed.
processing - The paymentUpdate was received and is processing.
failed - The paymentUpdate failed during processing.
processed - The paymentUpdate was successfully processed.
|
token
| ID | The ID for the token associated with the payment method. | This field is stored as a text string. Format: t1_tok_123abc4d567890efg1h2i34
|
account
| ID | The account associated with the Payment being updated. Used for instant funding payouts. | Typically returned as null unless configured under special circumstances through the service provider. |
platform
| string | The platform used to process this PaymentUpdate. | Valid Values: APPLE
ELAVON
FIRSTDATA
GOOGLE
VANTIV
VCORE
WELLSACH
WELLSFARGO
WFSINGLE
WORLDPAY
TDBANKCA
|
ref
| string | A platform reference for this PaymentUpdate. | This field is stored as a text string and must be between 0 and 50 characters long |
clientRef
| string | An internally generated reference for this PaymentUpdate. | This field is stored as a text string and must be between 1 and 50 characters long. Typically a 6-10 digit number. |
message
| string | The message returned from the processor after the update has occurred regarding the reason. | This field is stored as a text string and must be between 0 and 500 characters long. |
expiration
| string | The new expiration date for the updated payment method. | This field is stored as a text string in 'MMYY' format. Format: 0627 = June 2027.
|
Tip: You can also download the Account Updater Report from the Reports page to easily filter and set time ranges or specific Merchant entities.
Account Updates (paymentUpdates
) vs. Account Updater Groups (paymentUpdateGroups
)
Account Updates: An individual record of the token submitted to the Account Updater Service. This indicates the token associated with the payment and its status.
Account Update Groups: A group created for each entity payment that is associated with all payment updates created for each valid token.
Account Updater Setup Costs and Ongoing Fees
When the Account Updater feature is enabled ongoing fees may be assessed from the Platform or a Referrer when cardholders' account information is updated within a Merchant’s portfolio.
Whether using the Portal or the API, you can configure fees on an event-triggered basis so that Merchants are charged each time you pay an Account Updater fee for a cardholder payment token (card info) that has been updated through this automatic feature to pass the cost along to your Merchant.
The following fee schedules can be used to assess Account Updater-related fees to Merchants:
Fee Schedule | Description |
---|
Account Updater Update (44 ) | Triggers Fee on token update |
Account Updater Group Update (46 ) | Triggers on payment update |
Fee Cost Analysis
Charges are calculated per response from the Account Updater service and charged per updated token. Service responses that will trigger a fee include:
Contact the cardholder for updated information.
The account number was changed.
The account was closed.
The expiration date was changed.
Note: If no updates occur on a card, the Merchant will not be charged. You will only be billed a service fee for cards that are updated.