Our account updater is provided as an on-demand and asynchronous service, available via API. Currently we support Visa, Mastercard, American Express, and Discover.

​
Setup

To use the account updater service you need to have the service enabled. To have the batch account updater enabled on your instance please fill out this form. The enrollment happens directly with the card schemes and may take up to two weeks. Our customer support team may reach out with more questions if needed.

If you’re already enrolled for this service with the schemes, filling out the form is still required to set up the necessary data points in our systems as well as our downstream partner’s system.

​
Request an update check

Once enabled it is possible to call the account updater service using the POST /account-updater/jobs endpoint.

curl --request POST \
  --url https://api.{gr4vy_id}.gr4vy.app/account-updater/jobs \
  --header 'Authorization: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payment_method_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}'

The request can contain any set of stored card IDs. The set of cards is then submitted to the schemes to receive any updates on their account details. This process can take up to 7 days.

Any updates to the card are done automatically. Therefore there is no need to handle the response of the account updater service. If the payment method is made unavailable, either because the card has been canceled or the buyer has indicated to stop recurring payments by this merchant, then the card does not get updated but transactions will be declined. At this point, we recommend you delete the stored card via our API.

Scheme enrollment limitations

Account updates are enabled individually per card scheme and per merchant ID (MID). It is important to be aware of which schemes your MID has been enrolled in. If an update job is submitted for a card in a scheme for which you are not enrolled, then your update may remain stuck in a pending state for up to 7 days.

​
Handling updated details

When the results are ready, the new account details are stored on the payment method but left in a “standby” mode. This means the details have been received but will not be used immediately.

The reason for this is that it can happen that details have been updated, for example, a new card with a new expiry date has been issued, but these details are pending activation of the cardholder. The old card might still be in use in the meantime.

Card details are eventually updated when it is determined that the old details are no longer valid. After the card details have been updated the payment method ID remains the same but the last_replaced_at field on the payment method will be updated. This way, as a merchant, you can keep using the same identifier to trigger recurring payments using up-to-date details.

There are three scenarios in which the actual replacement occurs.

  • When the card has an expiry date in the past
  • When we received an update that only changes the expiration date
  • When a transaction using this card is declined with any of the following codes
    • canceled_payment_method
    • expired_payment_method
    • unavailable_payment_method
    • unknown_payment_method

​
Webhooks

Once a payment method has been updated a webhook will be sent out for the payment method to notify you of the change. You can use this webhook to pull in the latest expiry date, last 4 digits, or BIN for use in your own UI.

Was this page helpful?

OverviewScheduled updates