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. This page covers how detection works, what the API returns, and how to handle it.
- Prerequisite: An existing customer wallet with at least one saved payment method.
- Endpoint:
POST /v2/payment-methods/search(merchant-wallet-managementscope) β list the customer's current payment methods, including any carrying aDUPLICATE_ENTRYwarning - Use: Integrating and troubleshooting duplicate payment-method scenarios
Duplicate Detection Rulesβ
How a payment method is identified as a duplicate
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
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.
API Requestβ
There is no merchant-initiated request that triggers duplicate detection β it happens automatically when the CCG Widget submits a new payment method on the customer's behalf. To check whether a payment method in the wallet carries a duplicate warning, search the customer's current payment methods:
Search Payment Methods request
POST /v2/payment-methods/search
X-Merchant-Id: {merchantId}
Content-Type: application/json
{
"customer": { "hsid": "{hsid}" }
}
API Responseβ
Setup Payment Method response shape (for reference)
The shape below is what the CCG Widget receives when it submits a payment method β shown here because the same warning structure reappears in webhook payloads and search results, so understanding it helps you interpret those.
{
"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>"
}
Search Payment Methods 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.
Status Handlingβ
There is no merchant-side polling for this flow β the CCG Widget handles the setup/poll cycle. Use POST /v2/payment-methods/search to check the current warning state for a payment method, or rely on the PAYMENT_METHOD_CREATED/PAYMENT_METHOD_UPDATED webhooks below for real-time notification.
Webhooksβ
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.
| Event | When Triggered |
|---|---|
PAYMENT_METHOD_CREATED | Sent first, reflecting the initial create attempt |
PAYMENT_METHOD_UPDATED | Sent second, confirming the existing payment method was updated instead |
Process these events in order. The PAYMENT_METHOD_UPDATED event is the one that reflects the final state β do not treat PAYMENT_METHOD_CREATED alone as confirmation that a new payment method was created.
Error Handlingβ
DUPLICATE_ENTRY is a warning on an otherwise-successful response, not an error code β see API Response above. For genuine failure responses on this flow, see the general Payment Error Codes reference.
FAQβ
I expected a new payment method but got an update instead β why?β
CCG detected a duplicate. Check the API response for a DUPLICATE_ENTRY warning to confirm.
Why wasn't the default flag applied to my newly added card?β
The existing matching card is a manufacturer card, which cannot be set as default β see Special Handling of Card Flags.
The payment method still shows outdated information β what happened?β
The update may not have completed. Verify the latest payment method details via POST /v2/payment-methods/search and re-sync your records if needed.
Integration Checklistβ
- Check every payment-method record for a
warningfield, not justerror - Surface
DUPLICATE_ENTRYto users as "your payment information was updated," not as a failure - Process
PAYMENT_METHOD_CREATEDandPAYMENT_METHOD_UPDATEDwebhooks in order and reconcile against the finalPAYMENT_METHOD_UPDATEDstate - Refresh your local payment-method list after handling a duplicate response
Related Documentationβ
- Payment Methods β business capability overview
- Webhooks β general webhook setup
- Payment Error Codes