Card updater

Card Updater is a feature that helps you recover transactions that would otherwise fail due to expired or outdated card credentials. When a payment is declined because a customer's card is no longer valid, dLocal automatically retrieves the updated card details and retries the transaction within the same payment flow, with no additional action required from you.

📘
Availability
Card Updater is currently available for card payments in Brazil only.
Supported networks: Visa, Mastercard, and ELO.
Supported issuers: Nubank, Itaú, Santander, Banco Inter, and Banco do Brasil.

How it works

Card Updater operates in two phases: real-time card recovery and proactive card replacement.

Real-time card recovery

When a payment fails due to an expired or outdated card, dLocal attempts to recover it within the same payment session:

You send a payment request to dLocal with the customer's card details.
The payment is declined because the card is expired or outdated.
dLocal checks whether updated card details are available from the card network.
If new card details are found, dLocal automatically retries the payment using the updated credentials.
dLocal returns the final result to you, including the updated card metadata and an account_updater_status of UPDATED in the response.

Proactive card replacement

Once a card has been updated, dLocal stores the mapping between the old and new card credentials. On all future payment attempts using the original expired card:

You send a payment request using the old (expired) card details, as usual.
Before processing, dLocal detects it already has newer card credentials on file for that customer.
dLocal automatically substitutes the updated card details and sends the transaction directly to the network. No retry is needed.
dLocal returns the result to you with an account_updater_status of PREVIOUSLY_UPDATED.

Subsequent payments can use the updated card credentials without an additional retry.

What changes in the API response

When Card Updater is enabled for your account, card payments include a new field inside the card object in the payment response:

card.account_updater_status

Value	Description
`NO_CHANGE`	The transaction was processed using the original card details. No update occurred.
`UPDATED`	The card was expired or outdated. dLocal obtained updated credentials and retried the payment in real time. The card fields in the response (`last4`, `expiration_month`, `expiration_year`) reflect the new card.
`PREVIOUSLY_UPDATED`	The card sent in the request was already on file as outdated. dLocal replaced it with previously stored updated credentials before processing. The card fields in the response reflect the new card.

📘
Updated card fields
When account_updater_status is UPDATED or PREVIOUSLY_UPDATED, all card fields returned in the response (last4, expiration_month, expiration_year) correspond to the updated card, not the original one sent in the request. We recommend storing these values to keep your records in sync.

This field appears in:

Synchronous response of POST /payments
GET /payments/{payment_id}
IPN (webhook) notifications

If Card Updater is not enabled for your account, this field will not appear in the response.

Response examples

Real-time card recovery (UPDATED)

In this example, a payment was submitted with an expired card. dLocal obtained updated card details and successfully retried the transaction in real time.

{
  "id": "T-1067989-x8ed6ff-2l3o49d-5hu67d0s45",
  "amount": 30,
  "currency": "BRL",
  "payment_method_id": "CARD",
  "payment_method_type": "CARD",
  "payment_method_flow": "DIRECT",
  "country": "BR",
  "card": {
    "holder_name": "***************",
    "expiration_month": 10,
    "expiration_year": 2032,
    "brand": "VI",
    "last4": "2222",
    "account_updater_status": "UPDATED"
  },
  "created_date": "2026-03-02T14:12:07.000+0000",
  "approved_date": "2026-03-02T14:12:09.000+0000",
  "status": "AUTHORIZED",
  "status_detail": "The payment was authorized.",
  "status_code": "600",
  "order_id": "4bba6caafc75952894adf7bacr9f",
  "description": "Order description"
}

Proactive card replacement (PREVIOUSLY_UPDATED)

In this example, the card sent in the request was already on file as outdated. dLocal replaced it with the previously stored updated credentials before processing. No retry was needed.

{
  "id": "T-1067989-x8ed6ff-2l3o49d-5hu67d0s45",
  "amount": 30,
  "currency": "BRL",
  "payment_method_id": "CARD",
  "payment_method_type": "CARD",
  "payment_method_flow": "DIRECT",
  "country": "BR",
  "card": {
    "holder_name": "***************",
    "expiration_month": 10,
    "expiration_year": 2032,
    "brand": "VI",
    "last4": "2222",
    "account_updater_status": "PREVIOUSLY_UPDATED"
  },
  "created_date": "2026-03-02T14:12:07.000+0000",
  "approved_date": "2026-03-02T14:12:09.000+0000",
  "status": "AUTHORIZED",
  "status_detail": "The payment was authorized.",
  "status_code": "600",
  "order_id": "4bba6caafc75952894adf7bacr9f",
  "description": "Order description"
}

Recommendations

To make the most of Card Updater, we recommend:

Sync response data. Make sure you are ready to receive the updated card metadata in the response that dLocal sends you.
Update your stored card records. When you receive a response with account_updater_status set to UPDATED or PREVIOUSLY_UPDATED, store the new last4, expiration_month, and expiration_year returned in the card object. This keeps your records accurate for future payments and customer-facing displays.
Use IPN notifications. If you process payments asynchronously, the account_updater_status field is also included in webhook notifications, so you can track updated cards without polling the API.

Enabling Card Updater

To activate Card Updater for your account, contact your dLocal account manager or reach out to our support team. Once enabled, the feature works automatically, and no integration changes are required.