Duplicate Payment Method
CCG automatically detects when a newly added payment method matches one already in a customer's wallet, updates the existing record instead of creating a second one, and returns a warning so your integration can react correctly.
- 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:
CARDandBANK_ACCOUNT - Related Endpoints: Set Up Payment Method, Find Payment Method
- Business Impact: Reduces user confusion, prevents wallet clutter, and ensures data consistency.
How Duplicate Payment Methods Are Identifiedβ
Cardβ
A card is identified as duplicate when it has:
- Payment method type
CARDwith 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_ACCOUNTwith identical account number and routing number as an existing bank account - Same or updated metadata such as bank account name or 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:
- Updates Existing Payment Method: CCG updates the existing card with any new information (expiry date, name, nickname, zip code)
- Discards New Entry: The newly added duplicate card entry is discarded
- Notifies Merchants: CCG sends two webhook events:
PAYMENT_METHOD_CREATEDindicating initial creation attemptPAYMENT_METHOD_UPDATEDindicating that an existing card was updated instead
Example Scenariosβ
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.
Special Handling of Card Flagsβ
Flag Behavior with Duplicate Cards
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.
Sample Responseβ
The duplicate payment method warning appears 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. Find Payment Methods API Response
[
{
"id": "xxx-xxx-xxx-xxx-xxx",
"paymentMethodType": "CARD",
"vendorPaymentMethodId": "pm_xxx",
"warning": {
"code": "DUPLICATE_ENTRY",
"title": "Payment method already exists",
"description": "Any new details provided have been updated accordingly."
}
}
]
DUPLICATE_ENTRY is a warning, not an error β error remains null and the request still completes successfully. Do not treat it as a failure condition.
Notificationsβ
PAYMENT_METHOD_CREATED and PAYMENT_METHOD_UPDATED events are sent in that order. Refer Webhooks for the full event schema.
Process events in order:
- Process Events in Order: Handle
PAYMENT_METHOD_CREATEDfirst, followed byPAYMENT_METHOD_UPDATED - Check Payment Method IDs: Verify the updated payment method ID is one that already exists in your system
- Update Your Records: Ensure your system reflects the most current payment method details
Implementation Best Practicesβ
- Check for Warning Codes: Always examine API responses for warning codes, especially after adding payment methods
- Provide User Feedback: When
DUPLICATE_ENTRYwarnings occur, inform users that their payment information has been updated rather than added - Refresh Payment Method List: Update your UI to reflect the current state of the wallet after handling duplicates
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 | See Special Handling of Card Flags |
| Payment method shows outdated info | Failed update process | Verify latest information in CCG and re-sync if needed |
Error Handlingβ
Refer SetUp Payment Method Error Codes and Find Payment Method Error Codes.