Enrolling Customers in Account Updater

Introduction

Cards change. They get reissued after a breach, they expire, they get closed. For any business that bills a payer more than once — subscriptions, invoicing, recurring orders — those changes turn into declines.

Card Account Updater (CAU) subscribes a stored card to the card networks' update service. When the issuer reissues or updates that card, the platform receives the change and refreshes the stored payment method in place: same pm_ id, new card data. Your next charge just works, and you never have to ask the payer for a new card.

Enrollment is driven by the Customer resource. You enroll a customer; the platform enrolls the cards attached to that customer.

Account Updater is currently in limited beta release

The program has limitations for eligibility, contact your integration specialist to learn more.

What Account Updater does

The card networks report three kinds of change, each of which the platform applies to your stored payment method and reports to you as a webhook:

Change	What happens to the payment method	`change_type`
Card data refreshed	Card number and/or expiry are rotated in place. `cau_last_updated_at` is stamped.	`data_refresh`
Card closed	`status` becomes `closed`. The card can no longer be charged.	`closed`
Cardholder action	`attention_required` becomes `contact_cardholder`.	`attention_required`

The payment method id, the brand, and the customer link never change. Only the underlying card data is refreshed, so every saved-card reference you hold stays valid.

What can be enrolled

Payment method	Eligible
Card — Visa, Mastercard, Discover	Yes
Card — American Express	No. Amex does not participate; enrollment is skipped silently.
Bank account (ACH / EFT)	No. Account Updater is a card-network service.

A card also has to be stored in the platform vault to be eligible. Cards captured through Payment Elements or a Payment Method Intent already are.

Prerequisites

Account Updater must be enabled on the merchant account. This is a boarding-level setting on the account's payment settings, seeded from your partner default — it is not something you toggle through the partner API. Talk to your implementation specialist to turn it on for a partner or an individual merchant.

Once the account is enabled, two things follow:

New customers created under the account default to cau_enrolled: true unless you say otherwise.
You can enroll and unenroll customers freely through the API.

If the account is not enabled, cau_enrolled defaults to false and cards are never subscribed.

1. Enroll a customer

At creation

Set cau_enrolled explicitly when you create the customer:

curl -X POST "https://<api-host>/customers" \
  -H "x-api-key: key_123456789" \
  -H "Content-Type: application/json" \
  -d '{
        "account_id": "acct_12345678",
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "cau_enrolled": true
      }'

{
  "id": "cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE",
  "entity": "customer",
  "business_id": "bus_12345678",
  "primary_account_id": "acct_12345678",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "tax_exempt": "none",
  "cau_enrolled": true,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Omit cau_enrolled and the customer inherits the account's default.

note

A brand-new customer has no cards yet, so nothing is subscribed at this point. The flag is a standing instruction: every card attached to this customer from now on gets enrolled.

Toggling an existing customer

curl -X PATCH "https://<api-host>/customers/cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE" \
  -H "x-api-key: key_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "cau_enrolled": true }'

Toggling to true enrolls every card already attached to the customer, not just future ones. Toggling to false unenrolls all of them.

The customer response returns as soon as the flag is saved; per-card enrollment continues in the background. Poll the payment methods (below) to see where each card landed.

2. Attach cards

Once the customer is enrolled, every card you attach is subscribed automatically.

Collecting a new card

Pass customer_id on the Payment Method Intent. The card is created, attached to the customer, and enrolled in one flow:

curl -X POST "https://<api-host>/payment_method_intents" \
  -H "x-api-key: key_123456789" \
  -H "x-account-id: acct_12345678" \
  -H "Content-Type: application/json" \
  -d '{
        "payment_method_types": ["card"],
        "customer_id": "cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE"        
      }'

See Storing Card and Bank Data for the full flow.

Attaching a card you already stored

curl -X POST "https://<api-host>/payment_methods/pm_1234567890/attach" \
  -H "x-api-key: key_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE" }'

The response carries the enrollment state the card reached during the call:

{
  "id": "pm_1234567890",
  "entity": "payment_method",
  "account_id": "acct_12345678",
  "customer_id": "cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE",
  "payment_method_type": "card",
  "source_type": "vgs",
  "status": "active",
  "cau_enrolled": false,
  "cau_enrollment_status": "enrollment_pending",
  "card": {
    "brand": "visa",
    "last_four_digits": "4242",
    "exp_month": "12",
    "exp_year": "2028"
  },
  "created_at": "2026-01-15T10:32:00Z",
  "updated_at": "2026-01-15T10:35:00Z"
}

3. Track enrollment status

Enrollment is confirmation-driven — the subscription isn't real until the network confirms it, so a card passes through enrollment_pending first.

`cau_enrollment_status`	Meaning
`not_enrolled`	Not subscribed. The default for every new card.
`enrollment_pending`	Subscription submitted, awaiting confirmation.
`enrolled`	Confirmed. The card is being monitored. `cau_enrolled` is `true`.
`enrollment_failed`	The subscription was rejected. Reasons are in `cau_enrollment_messages`.

Four fields on a card payment method describe the enrollment:

Field	Type	Notes
`cau_enrolled`	boolean	`true` only when the status is `enrolled`.
`cau_enrollment_status`	enum	The lifecycle value above.
`cau_enrollment_messages`	string[]	Failure reasons, newest last.
`cau_last_updated_at`	date-time	When Account Updater last refreshed this card. Unset until then.

caution

cau_last_updated_at records the last data refresh, not the enrollment date. A freshly enrolled card has no value here until the issuer actually changes something.

Check every card on a customer

curl "https://<api-host>/customers/cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE/payment_methods" \
  -H "x-api-key: key_123456789"

{
  "data": [
    {
      "id": "pm_1234567890",
      "entity": "payment_method",
      "customer_id": "cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE",
      "payment_method_type": "card",
      "status": "active",
      "cau_enrolled": true,
      "cau_enrollment_status": "enrolled",
      "cau_last_updated_at": "2026-03-02T04:11:07Z",
      "card": {
        "brand": "visa",
        "last_four_digits": "1881",
        "exp_month": "04",
        "exp_year": "2029"
      },
      "created_at": "2026-01-15T10:32:00Z",
      "updated_at": "2026-03-02T04:11:07Z"
    },
    {
      "id": "pm_0987654321",
      "entity": "payment_method",
      "customer_id": "cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE",
      "payment_method_type": "card",
      "status": "active",
      "cau_enrolled": false,
      "cau_enrollment_status": "enrollment_failed",
      "cau_enrollment_messages": ["Card is not eligible for account updates"],
      "card": {
        "brand": "american_express",
        "last_four_digits": "0005",
        "exp_month": "06",
        "exp_year": "2027"
      },
      "created_at": "2026-01-20T09:02:00Z",
      "updated_at": "2026-01-20T09:02:30Z"
    }
  ],
  "meta": { "has_more": false, "limit": 10 }
}

Check a single card

curl "https://<api-host>/payment_methods/pm_1234567890" \
  -H "x-api-key: key_123456789"

4. Receive updates by webhook

Subscribe to payment_method.automatically_updated to be notified whenever Account Updater changes one of your stored cards. See Webhooks for endpoint setup and How to Verify Webhooks for signature verification.

{
  "specversion": "1.1",
  "id": "evt_4TCwjdVJVq6P8Ufz8Qj88KIi5q5",
  "type": "payment_method.automatically_updated",
  "subject": "pm_1234567890",
  "timestamp": "2026-03-02T04:11:07Z",
  "datacontenttype": "application/json",
  "data": {
    "change_type": "data_refresh",
    "object": {
      "id": "pm_1234567890",
      "entity": "payment_method",
      "account_id": "acct_12345678",
      "customer_id": "cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE",
      "payment_method_type": "card",
      "source_type": "vgs",
      "status": "active",
      "cau_enrolled": true,
      "cau_enrollment_status": "enrolled",
      "cau_last_updated_at": "2026-03-02T04:11:07Z",
      "card": {
        "brand": "visa",
        "last_four_digits": "1881",
        "exp_month": "04",
        "exp_year": "2029"
      },
      "created_at": "2026-01-15T10:32:00Z",
      "updated_at": "2026-03-02T04:11:07Z"
    }
  }
}

data.object is the full payment method after the change. Branch on data.change_type:

`change_type`	Suggested handling
`data_refresh`	Nothing required. Optionally refresh the card summary you show the payer (`last_four_digits`, expiry).
`closed`	Stop billing this card. Prompt the payer for a new one; the payment method is no longer chargeable.
`attention_required`	Contact the cardholder. The card may still authorize, but the issuer has flagged it.

5. Unenroll

There are three ways out, depending on scope.

One card, keep the customer enrolled

curl -X POST "https://<api-host>/payment_methods/pm_1234567890/disable_account_updater" \
  -H "x-api-key: key_123456789"

Unsubscribes that card and leaves the customer's cau_enrolled flag alone — future cards still enroll. Returns the updated payment method.

422 if the card isn't currently enrolled.
502 if the unsubscribe couldn't be completed. Retry; the card stays enrolled until the unsubscribe actually lands, so you never get a card that looks disabled but is still being updated.

Every card on a customer

curl -X PATCH "https://<api-host>/customers/cus_2XAvbTyT7PafRQGpn5Y1Zffl3XE" \
  -H "x-api-key: key_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "cau_enrolled": false }'

By detaching the card

curl -X POST "https://<api-host>/payment_methods/pm_1234567890/detach" \
  -H "x-api-key: key_123456789"

Detaching unsubscribes an enrolled card before unlinking it — a card that no longer belongs to a customer is never left subscribed. The same happens for every card when you delete the customer.

Billing

Each Account Updater change reported by the networks may assess an account update fee, per your processing plan. The fee is billed to the merchant by default, or to the partner when your plan is configured that way. Enrollment itself is not billed — only the updates. Talk to your implementation specialist about the rate on your plan.

Multi-account customers

A customer attached to several merchant accounts can only be enrolled if the accounts support it. Attaching a CAU-enrolled customer to an account that does not have Account Updater enabled is rejected:

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "Cannot attach a CAU-enabled customer to a merchant with CAU disabled."
}

Either enable Account Updater on the target account, or unenroll the customer (cau_enrolled: false) before attaching.

Troubleshooting

A card stays enrollment_pending. Confirmation is asynchronous. If it hasn't settled after a few minutes, re-check with GET /payment_methods/{id}; a rejection lands as enrollment_failed with a reason.

cau_enrolled on the customer is true but a card shows not_enrolled. The customer flag is an instruction, not a guarantee. The card is likely Amex, a bank account, or not vaulted — none of which can be enrolled. Check the brand and payment_method_type.

A card is enrollment_failed. Read cau_enrollment_messages. To retry, toggle the customer's cau_enrolled off and back on, which resubmits every eligible card.

No payment_method.automatically_updated webhooks are arriving. Confirm the endpoint is subscribed to that event type and enabled, then confirm the cards actually reached cau_enrolled: true — pending and failed cards are not monitored. Updates are issuer-driven, so a card can be enrolled for months with nothing to report.

A card was updated but the payer's saved-card display is stale. The pm_ id doesn't change on a refresh, so a cached copy of the card summary won't update on its own. Re-read the payment method when you receive a data_refresh event.

Best practices

Enroll at the customer level, not per card. Set cau_enrolled once and let every card the payer adds inherit it.
Create the customer before you collect the card. Passing customer_id on the Payment Method Intent makes attach and enrollment automatic.
Handle closed promptly. It's the one change type where the card genuinely stops working, and it's your earliest warning before a decline.
Don't treat enrollment_pending as failure. Confirmation takes time; only enrollment_failed is terminal.
Keep a fallback payment method on high-value customers. Account Updater reduces involuntary churn — it doesn't eliminate it.

Enrolling Customers in Account Updater

Introduction​

What Account Updater does​

What can be enrolled​

Prerequisites​

1. Enroll a customer​

At creation​

Toggling an existing customer​

2. Attach cards​

Collecting a new card​

Attaching a card you already stored​

3. Track enrollment status​

Check every card on a customer​

Check a single card​

4. Receive updates by webhook​

5. Unenroll​

One card, keep the customer enrolled​

Every card on a customer​

By detaching the card​

Billing​

Multi-account customers​

Troubleshooting​

Best practices​

Related​