Checking access…

Skip to main content
Version: v2

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.

Integration Details
  • Prerequisite: An existing customer wallet with at least one saved payment method.
  • Endpoint: POST /v2/payment-methods/search (merchant-wallet-management scope) β€” list the customer's current payment methods, including any carrying a DUPLICATE_ENTRY warning
  • 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 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

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.

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."
}
}
]
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.

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​

Not yet in the webhooks-v2 OpenAPI spec

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.

EventWhen Triggered
PAYMENT_METHOD_CREATEDSent first, reflecting the initial create attempt
PAYMENT_METHOD_UPDATEDSent second, confirming the existing payment method was updated instead
caution

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 warning field, not just error
  • Surface DUPLICATE_ENTRY to users as "your payment information was updated," not as a failure
  • Process PAYMENT_METHOD_CREATED and PAYMENT_METHOD_UPDATED webhooks in order and reconcile against the final PAYMENT_METHOD_UPDATED state
  • Refresh your local payment-method list after handling a duplicate response