Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt

Use this file to discover all available pages before exploring further.

The batch account updater is provided as an on-demand and asynchronous service, available via API. Currently Visa, Mastercard, American Express, and Discover are supported.

​
Setup

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. The 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 the systems as well as the 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. 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 are declined. At this point, deleting the stored card via the API is recommended.
Scheme enrollment limitationsAccount 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 are not 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 card holder. 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 is 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 an update has been received 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 is 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.