Replaced Payment Method
When a vendor (e.g., Stripe) tells CCG that a saved card has been reissued — most commonly due to expiration, loss/theft, or a card-network update — CCG automatically replaces the old card with the new one in the customer's wallet and notifies merchants so their records stay in sync.
- Purpose: Explains how CCG handles replacement of payment methods (e.g., expired cards).
- Key Actions: Duplicate card removal, merchant notifications, and event structure.
- Triggers: Card expiration, reissued cards, bank account updates.
- Supported Types:
CARDandBANK_ACCOUNT - Event Schema: See Payment Methods Webhooks for the full
PAYMENT_METHOD_REPLACEDpayload structure
Scenario Overview
Suppose a user has card A (ending 1234) in their wallet. When card A expires and the user receives a new card B (ending 5678), they add card B to their wallet. CCG receives an event from the vendor indicating that card A has been updated to card B.
- Card A is treated as a duplicate and replaced by card B in the user's wallet.
- This logic applies to all supported payment method types (cards and bank accounts).
Common Replacement Triggers
- Card Expiration: When a card reaches its expiry date and a new one is issued.
- Lost or Stolen Cards: When a card needs to be reissued due to loss or theft.
- Bank Changes: When a bank account changes routing or account numbers.
- Card Network Updates: When payment networks update card numbers for security reasons.
What Happens to the Replaced Card?
- CCG automatically removes the old card A from the wallet.
- Merchants are notified via a
PAYMENT_METHOD_DELETEDevent for card A. - All associated payment links to the old payment method are updated to reference the new payment method.
Notifications
CCG sends a PAYMENT_METHOD_REPLACED event, including details of the new payment method (B) and the replaced (deleted) payment method (A) via deletedPaymentMethodId. See Payment Methods Webhooks for the full event and payload schema, including sample payloads for both card and bank account replacements.
PAYMENT_METHOD_REPLACED always arrives alongside a PAYMENT_METHOD_DELETED event for the old payment method. Process both — do not rely on one in isolation.
Implementation Considerations for Merchants
- If your system stores references to card A, those should be updated to card B.
- Update any recurring payments or saved payment instructions to use the new payment method ID.
- Validate that the event was processed successfully to maintain data consistency.
Error Handling
This is a vendor-event-driven flow with no merchant-initiated request to fail. If a webhook delivery is missed, reconcile using Find Payment Method rather than waiting for redelivery.
Frequently Asked Questions
What happens to subscriptions that use the replaced payment method?
Subscriptions and recurring payments using the old payment method will automatically use the new payment method, provided merchants have implemented proper handling of the PAYMENT_METHOD_REPLACED event.
Can users opt out of automatic payment method replacement?
No, this is a system-level feature that maintains wallet integrity and ensures payment methods remain current.
How quickly does the replacement process occur?
The replacement process happens in near real-time once CCG receives the update event from the payment provider.
What if a merchant misses the replacement event?
Merchants should implement retry mechanisms and reconciliation processes to handle missed events. Find Payment Method can also be used to verify current payment method status.
Note: This event-driven approach ensures merchants always have the latest payment method information and can provide a seamless experience to their customers.