Checking access…

Skip to main content
Version: v2

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.

Integration Details
  • Prerequisite: A customer wallet with a saved CARD or BANK_ACCOUNT payment 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-management scope).
  • 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​

Not yet in the webhooks-v2 OpenAPI spec

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.

EventWhen Triggered
PAYMENT_METHOD_DELETEDThe old payment method (card A) is removed from the wallet
PAYMENT_METHOD_REPLACEDThe 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
}
}
caution

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_DELETED and PAYMENT_METHOD_REPLACED as 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