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.
- Prerequisite: A customer wallet with a saved
CARDorBANK_ACCOUNTpayment method. - Endpoint: No direct merchant-initiated request — this is a vendor-event-driven flow. Verify current state via
GET /v2/payment-methods/{id}(merchant-wallet-managementscope). - Webhook:
PAYMENT_METHOD_REPLACED - Use: Understanding and reacting to automatic payment-method replacement
API Request
This flow has no merchant-initiated request — it is driven entirely by an upstream vendor notification that a payment method was reissued. There is nothing to send; use the GET request below to verify state after the fact.
API Response
Verify the current wallet state at any time with GET /v2/payment-methods/{id} (merchant-wallet-management scope) — the replaced payment method ID (card A) will no longer resolve, and the new payment method (card B) will appear in the customer's payment-method list. If you only have the old ID (card A) and need to find the new one, see Error Handling below.
Status Handling
There is no status to poll for this flow — it completes atomically on CCG's side once the vendor notification is processed. Confirm the outcome via the PAYMENT_METHOD_REPLACED webhook (below) or by querying the payment method directly.
Webhooks
Payment-method lifecycle events are not currently modeled in /webhooks-v2/ (only Payment, Refund, and Dispute are). The event names and payload below reflect current platform behavior; confirm with your CCG integration contact before relying on them as a versioned contract.
| Event | When Triggered |
|---|---|
PAYMENT_METHOD_DELETED | The old payment method (card A) is removed from the wallet |
PAYMENT_METHOD_REPLACED | The replacement is complete; includes both the new payment method and the deleted one's ID |
PAYMENT_METHOD_REPLACED event
{
"name": "PAYMENT_METHOD_REPLACED",
"payload": {
"paymentMethod": { // Payment Method information of CARD B
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"card": {
"last4": "5678",
"type": "CARD",
"status": "ACTIVE",
"cardBrand": "VISA",
"expiryYear": 2028,
"nameOnCard": "John Doe",
"expiryMonth": 12,
"zipCode": "12345",
"manufacturerCard": false
},
"paymentMethodDetails": {
"last4": "5678",
"type": "CARD",
"status": "ACTIVE",
"cardBrand": "VISA",
"expiryYear": 2028,
"nameOnCard": "John Doe",
"expiryMonth": 12,
"zipCode": "12345",
"manufacturerCard": false
},
"default": true,
"paymentMethodType": "CARD",
"nickname": "Personal Card"
},
"customer": {
"enterpriseId": "enterprise id",
"hsid": "hsid",
"dateOfBirth": "YYYY-MM-DD",
"metadata": {
"patientId": "rx-patient-id"
}
},
"agent": {
"firstName": "First Name",
"lastName": "Last Name",
"userId": "msId",
"isAccessVerified": true
},
"deletedPaymentMethodId": "597f6eca-6276-4993-bfeb-53cbbbba6f12" // CCG Payment Method ID of CARD A
}
}
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.
Error Handling
This is a vendor-event-driven flow with no merchant-initiated request to fail. If a webhook delivery is missed, the old payment-method ID (card A) no longer resolves, so looking it up directly won't recover the new ID. Instead, reconcile by searching the customer's current wallet state:
POST /v2/payment-methods/search
X-Merchant-Id: {merchantId}
{
"customer": { "hsid": "{hsid}" }
}
This returns all active payment methods currently in the customer's wallet (merchant-wallet-management scope) — including the replacement card (card B) — without needing the old ID. If the customer's identity can't be resolved this way either, contact your CCG representative for support-assisted recovery.
FAQ
What happens to subscriptions that use the replaced payment method?
Subscriptions and recurring payments using the old payment method automatically use the new one, provided your integration has implemented proper handling of the PAYMENT_METHOD_REPLACED event.
Can customers opt out of automatic payment method replacement?
No — this is a system-level behavior that maintains wallet integrity and ensures payment methods remain current.
How quickly does the replacement process occur?
Near real-time, once CCG receives the update event from the payment vendor.
What if I miss the replacement webhook event?
The old payment-method ID (card A) no longer resolves, so you can't recover the new ID by looking it up directly. Search the customer's current wallet via POST /v2/payment-methods/search (by email or HSID) to find the replacement card — see Error Handling. If the customer's identity can't be resolved, contact your CCG representative for support-assisted recovery.
Integration Checklist
- Handle
PAYMENT_METHOD_DELETEDandPAYMENT_METHOD_REPLACEDas a pair, not independently - Update any stored references to the old payment method ID (
deletedPaymentMethodId) to the new one - Update recurring-payment or saved-instruction references to use the new payment method ID
- Implement reconciliation for missed webhook events rather than assuming delivery is guaranteed
Related Documentation
- Payment Methods — business capability overview
- Duplicate Payment Method — related automatic wallet-matching behavior
- Webhooks — general webhook setup