Checking access…

Skip to main content
Version: v1

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.

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
  • 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 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 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:

  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

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
Flag Handling Limitations

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

ScenarioResultReason
Adding default card when existing is a manufacturer cardDefault flag NOT honoredManufacturer cards cannot be set as default
Adding manufacturer card when existing is a default cardManufacturer flag honored, default status removedSystem prioritizes manufacturer flag
Adding non-default card when existing is defaultNon-default status honoredUser 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."
}
}
]
info

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:

  1. Process Events in Order: Handle PAYMENT_METHOD_CREATED first, followed by PAYMENT_METHOD_UPDATED
  2. Check Payment Method IDs: Verify 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

Implementation Best Practices​

  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

Troubleshooting Guide​

IssuePossible CauseSolution
Expected new payment method but got updatedDuplicate detectedCheck API response for DUPLICATE_ENTRY warning
Default flag not applied to newly added cardExisting card is a manufacturer cardSee Special Handling of Card Flags
Payment method shows outdated infoFailed update processVerify latest information in CCG and re-sync if needed

Error Handling​

Refer SetUp Payment Method Error Codes and Find Payment Method Error Codes.