Card account updater

Cards expire, get lost or are reissued. When that happens, the card you saved no longer works and your next renewal fails.

Account Updater is a card-scheme service (Visa, Mastercard and Elo) that supplies the new card details when an issuer replaces a card. PPRO uses it to recover from these declines automatically.

How it works at PPRO

PPRO's Account Updater runs in real time, at the moment of the decline. You do not change your payment requests.

1. You submit a payment with a RAW_CARD or a vaulted card (CARD_PPRO_VAULTED).
2. The issuer declines with a card lifecycle reason, such as an expired, lost or stolen card.
3. PPRO asks Visa or Mastercard for updated card details.
4. If the scheme returns new details:
   • PPRO updates the stored payment instrument with the new expiry date or card number.
   • PPRO retries the authorization with the new details.
   • If a webhook URL is configured, PPRO sends a PAYMENT_INSTRUMENT_DETAILS_UPDATED webhook.
5. You receive the result of the final authorization attempt: approved, or the decline reason.

sequenceDiagram
    autonumber
    participant M as Merchant
    participant P as PPRO
    participant S as Card scheme<br/>(Visa / Mastercard)
    participant I as Issuer

    M->>P: POST /v1/payment-charges (instrumentId)
    P->>I: Authorization
    I-->>P: Decline (expired / lost / stolen)
    P->>S: Request updated card details
    alt New details found
        S-->>P: New PAN and/or expiry
        P->>P: Update stored instrument
        P-->>M: Webhook PAYMENT_INSTRUMENT_DETAILS_UPDATED
        P->>I: Retry authorization with new details
        I-->>P: Result
    else No update available
        S-->>P: No match or account closed
    end
    P-->>M: Final charge result

What you get back

Enabling Account Updater

• Contact your PPRO Account Manager to activate it for your account.
• No changes to your payment requests are needed.
• Supported networks: Elo, Visa and Mastercard.

Receiving the webhook

The webhook tells you that a stored card changed, so you can refresh your records and show the customer up-to-date card details (for example, the last four digits).

1. Set up your endpoint

• HTTPS only, on port 443. Other ports need to be enabled by your Account Manager.
• Respond with a 2xx status quickly. Store the payload and process it afterwards.
• PPRO retries failed deliveries with exponential backoff (first retry after 15 seconds, doubling each time, up to 15 attempts over roughly 68 hours).

2. Configure the URL

Ask your Account Manager to:

1. Set your default webhooksUrl. If you use separate URLs for payments and disputes, make sure the instrument events go to your payments URL.
2. Set your signing secret, so you can verify the PPRO-Signature header.
3. Optionally add static custom headers, for example for your own routing or authentication.

The webhook URL can also be defined at merchant group or PSP level. PPRO uses the most specific configuration that exists for your merchant.

3. Verify the signature

Each delivery includes a PPRO-Signature header:

ppro-signature: t=1776785532,s=5271af077eb3525e5c50ceaa44834ff10cc6f32f6bd060e341e0dad60bae49bb

1. Compute the HMAC SHA-256 of t + "." + payload, using your signing secret as the key. Use the raw request body, not a re-serialized one.
2. Compare the result with s.
3. Check that t is recent, to guard against replays.

See Webhooks for details.

When is the webhook sent?

PPRO sends PAYMENT_INSTRUMENT_DETAILS_UPDATED whenever the details of a stored payment instrument change. This includes:

• Account Updater finds new card details after a lifecycle decline, as described above.
• The instrument is updated in another way (for example, a merchant-initiated update of the instrument).

It is not sent when:

• Account Updater finds nothing new.
• The card works and nothing changes.

The related instrument events are:

What the webhook looks like

The payload follows the CloudEvents 1.0.2 envelope used by all PPRO webhooks. The data object carries the instrument ID, the update time and the new masked card details. Raw card numbers are never sent: you receive the BIN, last four digits, expiry date and aliases.

{
  "specversion": "1.0.2",
  "source": "https://www.ppro.com",
  "datacontenttype": "application/json",
  "id": "XvpFAF6I7ypsaxv0xJ9BW",
  "type": "PAYMENT_INSTRUMENT_DETAILS_UPDATED",
  "subject": "instr_yGeGPffd4Ch56wZENvDbi",
  "time": "2026-10-09T13:05:14.744Z",
  "data": {
    "type": "PAYMENT_INSTRUMENT_DETAILS_UPDATED",
    "paymentInstrumentId": "instr_yGeGPffd4Ch56wZENvDbi",
    "merchantId": "merch_example",
    "updateTimestamp": "2026-10-09T13:05:14.700Z",
    "details": {
      "type": "CARD_PPRO_VAULTED",
      "details": {
        "brand": "VISA",
        "bin": "411111",
        "last4Digits": "1111",
        "expiryMonth": 2,
        "expiryYear": 2031,
        "holderName": "John Smith",
        "panAlias": "alias_dCM4le6uVLMWc44SO-tBa"
      }
    }
  }
}

Handling the event

• Deduplicate on id, because retries can deliver the same event more than once.
• Treat events as possibly out of order. Compare updateTimestamp before overwriting your data.
• Do not wait for this webhook to continue a payment. The retry and its result are already part of the charge response.

Checking updates without webhooks

• The charge response includes instrumentUpdated, which tells you whether the instrument was updated during that payment.
• Call GET /v1/payment-instruments/{instrumentId} to retrieve the current details at any time.

Account Updater and Merchant Advice Codes

A 01 ("New account information available") means the issuer has new details for the card. With Account Updater enabled, PPRO handles the refresh and retry for you. Without it, ask the customer for the new details. See Merchant Advice Code.