Card Account Updater

Automatically update card on file accounts

The Account Updater service can check Visa, MasterCard, Discover, and American Express cards for changes, updating PaySimple vault records when necessary. The service helps merchants to reduce losses in revenue due to cards declined when re-issued or when expiration dates change.

At this time, the Account Updater service is only available to merchants processing on the WorldPay platform. Partners and merchants must be also be enrolled with the program at PaySimple.

Flag Card for Update

Account Updater will only review cards that have been "flagged for update" each month. Cards that are "flagged" are checked within our batch job for that month. If an expired card is not flagged for update, then it will not be updated to the latest information. Since there is a cost associated with each card matched, the card flagging functionality minimizes excess cost of flagging every card in your vault each month. For example, if a customer in your vault hasn't made a purchase in 2 years, then there is little value in ensuring the latest card information.

There are two ways to flag cards for update:

  1. Automatic - Please contact PaySimple for enablement of this process.
    Partners can utilize the PaySimple automatic system. This system will flag cards for update based on our internal system parameters. By using the PaySimple automatic system, partners reduce the amount of development effort to begin using the functionality.
  • Cards can still be flagged for update manually while using this solution.
  1. Manual
    The alternative solution for Account Updater is manual. This allows the greatest flexibility and customization of flagging cards for update. By coding to our flag_for_update endpoint, you can determine your own parameters for when cards should be flagged for an update.
  • When this override is enabled, cards can only be updated via API.

When you expect to use a card on file in the future, call the flag card for update endpoint to request the card be updated. If a card flagged for update has been changed, it will be updated in the PaySimple Payments API vault within 4 business days. Therefore, PaySimple recommends submitting flag requests 5 business days before a recurring payment is scheduled to be run.

Request:

POST /payment_method/vault/{paymentMethodToken}/flag_for_update

Response:
204 No Content

Webhooks

To create the best experience for customers, we do recommend adding support for our Account Updater webhooks when using either solution. The webhook subscriptions below can be used to notify you when a new merchant has been activated for Account Updater. They can also provide valuable information regarding customer cards that have been updated.

Account Updater - Card Updated
Account Updater - Merchant Status

Card Updated Webhook Event

To subscribe to the webhook, see Webhooks documentation.

The card_updated event will fire each time an update to a card is received by the PaySimple system.

{
  "event_type": "card_updated",
  "event_id": "evt_5b46372e3b63252f94fa2268",
  "merchant_id": 1225,
  "created_at": "2018-07-11T15:44:13.0523594Z",
  "data": {
    "result": "account_changed",
    "updated_at": "2018-07-13T06:00:00Z",
    "payment_method_token": "vlt_90545e2776de4efd997c4fc3ba2298e4",
    "last4": "6734",
    "expiration_month": 3,
    "expiration_year": 2023,
    "externali_id": "3948573483"    
  }
}

Card Updated Results

ResultDescription
account_changedThe card number (and likely the expiration date) on the account has changed
expiration_changedThe card expiration date has changed
account_closedThe credit card account is closed and the customer cannot be charged
contact_cardholderRecommend contacting the cardholder to obtain valid credit card information
errorAn error occurred when attempting to retrieve account update information
no_matchThe submitted card could not be located in the account updater system

Merchant Status Webhook Event

To subscribe to the webhook, see Webhooks documentation.

The account_updater_status event will fire whenever a merchant is either enabled or disabled for the account updater service.

{
  "event_type": "account_updater_status",
  "event_id": "evt_5b46372e3b63252f94fa2268",
  "merchant_id": 1225,
  "created_at": "2018-07-11T15:44:13.0523594Z",
  "data": {
    "account_updater_enabled": true
  }
}

Copy Customer Card Account to Vault

🚧

In order to use the Account Updater, your cards must be stored in the Payments API vault.

To copy a card stored in a customer account, call the following endpoint. Note the PaySimple-Merchant-Id header must be set.

Request:

POST /customer/credit_card/{accountId}/copy_to_vault

Response:

200 OK
{
  "data" : {
    "payment_method_token": "vlt_90545e2776de4efd997c4fc3ba2298e4"
  }
}