Skip to main content
Version: v2

Replaced Payment Method

Quick Reference
  • 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, wallet merge.
  • Supported Types: CARD and BANK ACCOUNT
  • Use: Reference for event flows and merchant integration.

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 (e.g., cards, bank accounts, digital wallets).

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 Duplicate Card?​

  • CCG automatically removes the duplicate card A from the wallet.
  • Merchants are notified via a PAYMENT_METHOD_DELETED event.
  • All associated payment links to the old payment method are updated to reference the new payment method.

How Are Merchants Notified of the Replacement?​

  • CCG sends a PAYMENT_METHOD_REPLACED event.
  • This event includes details of the new payment method (B) and the replaced (deleted) payment method (A).
  • Merchants can use this information to update their records and maintain accurate payment method data.

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.

Sample Event Structure​

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 
  }
}

Benefits of Automatic Payment Method Replacement​

  • Reduced Payment Failures: Fewer declined transactions due to expired or outdated payment methods.
  • Enhanced Customer Experience: Users don't need to manually update payment information across all merchants.
  • Operational Efficiency: Merchants automatically receive updated payment method details.
  • Consistent Data: All systems maintain synchronized and up-to-date payment information.

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. CCG's API also provides ways 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.