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

# Real time account updates

> Update stored card details automatically when a merchant-initiated payment is declined, and test it with the simulator.

The real time account updater automatically checks for updated card details at the point of a decline. Where new card details are available, the payment method is updated in place and the transaction is retried with the same connector. The payment method keeps its ID, and Gr4vy sends a `payment-method.updated` [webhook](/guides/features/webhooks/events). This approach requires no integration changes.

## Setup

To have the real time account updater enabled on your instance please fill out [this form][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.

## Usage and limitations

The real-time account updater only runs when all of the following are true.

* The transaction uses a stored card.
* The transaction is a subsequent merchant-initiated transaction, with `merchant_initiated` and `is_subsequent_payment` set to `true`.
* The connection was sent the card number (PAN). Digital wallets and network tokens don't qualify. Neither does a [closed-loop](/guides/features/recurring-payments/open-loop) connection that charges its own stored token for the card.
* The decline has one of the following error codes, or a merchant advice code (MAC) of `01`.
  * `canceled_payment_method`
  * `expired_payment_method`
  * `incorrect_expiry_date`
  * `issuer_decline`
* The card hasn't been excluded from updates after an earlier final response from the updater.

The updater runs at most once per transaction. Only Visa and Mastercard are currently supported. Cards with pending updates from the batch account updater use the new stored credentials instead.

[form]: https://gr4vy.atlassian.net/servicedesk/customer/portal/1/group/7/create/32

<Note>
  As with other updates, merchants are only charged for cards that are updated.
</Note>

## Simulator

Your sandbox instance is automatically enabled to use the real time account updater simulator.

You can test different scenarios by using the `connection_options` property when creating a transaction. Please see the various scenarios and examples below.

<Note>
  Using the card simulator connection is the easiest way to test different scenarios as this connector returns specific decline error codes depending on the transaction amount.
</Note>

The real time account updater logic only triggers for subsequent merchant-initiated transactions that send the card number, so set up your test as follows.

1. In the dashboard, open the Card simulator connection and turn on **Open loop**. It's off by default, and without it the connection charges its own token instead of the card number.
2. Create a stored payment method, for example with a customer-initiated transaction with `store` set to `true`.
3. Create a subsequent merchant-initiated transaction with the payment method ID, an amount that the simulator declines with a qualifying error code, and the `connection_options` for the scenario. For example, the amount `200005` returns `expired_payment_method`. See the [simulator amounts](/guides/features/simulators/overview).

When the updater returns a new card number or expiry date, the payment method is updated, the transaction is retried on the same connection, and Gr4vy sends a `payment-method.updated` webhook.

<CodeGroup>
  ```json Request theme={"system"}
  {
    "amount": 200005,
    "country": "US",
    "currency": "USD",
    "payment_service_id": "46973e9d-88a7-44a6-abfe-be4ff0134ff4",
    "merchant_initiated": true,
    "payment_source": "card_on_file",
    "is_subsequent_payment": true,
    "payment_method": {
      "method": "id",
      "id": "f6933999-362f-468b-83c3-ed16b1a4ca17",
      "redirect_url": "https://gr4vy.com/callback"
    },
    "connection_options": {
      "account-updater": {
        "response_code": "updated",
        "account_number": "4242424242424242"
      }
    }
  }
  ```
</CodeGroup>

### Examples

The following are a few examples of how to use the `connection_options` to trigger particular situations.

<CodeGroup>
  ```json Full new details theme={"system"}
  {
    ...
    "connection_options": {
      "account-updater": {
        "response_code": "updated",
        "account_number": "4242424242424242",
        "expiration_month": "12",
        "expiration_year": "2050"
      }
    }
  }
  ```

  ```json New number only theme={"system"}
  {
    ...
    "connection_options": {
      "account-updater": {
        "response_code": "updated",
        "account_number": "4242424242424242"
      }
    }
  }
  ```

  ```json Unchanged theme={"system"}
  {
    ...
    "connection_options": {
      "account-updater": {
        "response_code": "unchanged"
      }
    }
  }
  ```

  ```json Error theme={"system"}
  {
    ...
    "connection_options": {
      "account-updater": {
        "error_code": "error"
      }
    }
  }
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.