Duplicate Payment Method

Quick Reference

• Purpose: Learn how CCG identifies and processes duplicate payment methods in a user's wallet.
• Key Actions: Updates existing payment method details, issues warnings, and sends merchant notifications.
• Supported Types: CARD and BANK_ACCOUNT
• Use Case: Integration and troubleshooting of duplicate payment scenarios.
• Business Impact: Reduces user confusion, prevents wallet clutter, and ensures data consistency.

What is a Duplicate Payment Method?

A payment method is considered duplicate when a newly added payment method matches an existing one in the user's wallet based on specific identifying attributes.

Business Value

Duplicate detection provides several benefits:

• Improved User Experience: Prevents wallet clutter with multiple versions of the same payment method
• Data Consistency: Ensures payment information remains current and accurate
• Reduced Errors: Minimizes payment failures due to outdated payment information

How duplicate payment methods are identified

Duplicate Payment Method Identification

Card

A card is identified as duplicate when it has:

• Payment method type CARD with identical card number and vendor fingerprint as an existing card
• Same or updated metadata such as expiry date, cardholder name, nickname, or zip code

Bank Account

A bank account is identified as duplicate when it has:

• Payment method type BANK_ACCOUNT with identical account number and routing number as an existing bank account
• Same or updated metadata such as bank account name, nickname.

Detection Workflow

User adds payment method → CCG checks for duplicates → 
If duplicate found → Update existing payment method → 
Discard new entry → Return warning in response

CCG's Handling Process

When a duplicate payment method is detected:

1. Updates Existing Payment Method: CCG updates the existing card with any new information (expiry date, name, nickname, zip code)
2. Discards New Entry: The newly added duplicate card entry is discarded
3. Notifies Merchants: CCG sends two webhook events:
   • PAYMENT_METHOD_CREATED indicating initial creation attempt
   • PAYMENT_METHOD_UPDATED indicating that an existing card was updated instead

Use Cases

Example Use Cases

Scenario 1: Updated Expiry Date

User has a Visa card ending in 1234 that expires 06/2025. They add the same card with a new expiry date of 06/2027. CCG updates the existing card with the new expiry date rather than creating a duplicate.

Scenario 2: Updated Cardholder Name

User has a Mastercard registered under "John Doe" and later adds the same card with the name "John A. Doe". CCG updates the existing card's name field.

Scenario 3: Digital Wallet Migration

User adds a card that was previously added via a digital wallet (like Apple Pay). CCG recognizes the underlying card as a duplicate and updates the existing record.

Warning Indicators

Warning Response

When a duplicate is processed, CCG includes a warning in API responses with:

• Code: DUPLICATE_ENTRY
• Title: "Payment method already exists"
• Description: "Any new details provided have been updated accordingly."

Special Handling of Card Flags

Flag Behavior with Duplicate Cards

Flag Handling Limitations

When processing duplicate cards, CCG follows specific rules for handling default and manufacturer card flags:

Scenario	Result	Reason
Adding default card when existing is a manufacturer card	Default flag NOT honored	Manufacturer cards cannot be set as default
Adding manufacturer card when existing is a default card	Manufacturer flag honored, default status removed	System prioritizes manufacturer flag
Adding non-default card when existing is default	Non-default status honored	User preference is respected

This ensures data consistency and compliance with business rules, though it may sometimes result in unexpected behavior from the end-user perspective.

Accessing Warning Details

The duplicate payment method warnings appear in two API responses:

1. Setup Payment Method API Response

{
  "data": {
    "id": "xxx-xxx-xxx-xxx-xxx",
    "platformVendorMerchantId": "platformVendorMerchantId",
    "vendorSetupPaymentMethodSecret": "vendorSetupPaymentMethodSecret",
    "status": "COMPLETED",
    "paymentMethodId": "paymentMethodId",
    "paymentMethodType": "CARD",
    "error": null,
    "warning": {
      "code": "DUPLICATE_ENTRY",
      "title": "Payment method already exists",
      "description": "Any new details provided have been updated accordingly."
    }
  },
  "url": "/customers/<customerId>/setup-payment-methods/<setupPaymentMethodId>"
}

2. List Payment Methods API Response

[
  {
    "id": "xxx-xxx-xxx-xxx-xxx",
    "paymentMethodType": "CARD",
    "vendorPaymentMethodId": "pm_xxx",
    // ...other payment method properties...
    "warning": {
      "code": "DUPLICATE_ENTRY",
      "title": "Payment method already exists",
      "description": "Any new details provided have been updated accordingly."
    },
    // ...remaining properties...
  }
]

Implementation Best Practices

Handling Warnings in Client Applications

When implementing payment method management in client applications:

1. Check for Warning Codes: Always examine API responses for warning codes, especially after adding payment methods
2. Provide User Feedback: When DUPLICATE_ENTRY warnings occur, inform users that their payment information has been updated rather than added
3. Refresh Payment Method List: Update your UI to reflect the current state of the wallet after handling duplicates

Webhook Processing

For proper handling of the event sequence:

1. Process Events in Order: Handle the PAYMENT_METHOD_CREATED event first, followed by PAYMENT_METHOD_UPDATED
2. Check Payment Method IDs: Verify that the updated payment method ID is one that already exists in your system
3. Update Your Records: Ensure your system reflects the most current payment method details

Troubleshooting Guide

Issue	Possible Cause	Solution
Expected new payment method but got updated	Duplicate detected	Check API response for DUPLICATE_ENTRY warning
Default flag not applied to newly added card	Existing card is a manufacturer card	Explain flag handling priorities to user
Payment method shows outdated info	Failed update process	Verify latest information in CCG and re-sync if needed

Implementation Note: Merchants should check for these warnings in API responses when troubleshooting apparent discrepancies between requested and actual payment method configurations.