Checking access…

Skip to main content
Version: v1

Update Payment Method

The Update Payment Method API allows merchants to update payment methods (card or bank account) linked to a customer profile using the merchant-wallet-management scope. This API is used to modify details such as card nickname, default status, or bank account information.

Quick Reference
  • API Endpoint: PATCH v1/payment-methods/{paymentMethodId}
  • Supported Scope: merchant-wallet-management, user
    • Allowed Session Modes: PAYMENT_WITH_WALLET , WALLET
  • Payment Method Types: CARD, BANK_ACCOUNT
  • Key Fields: isDefault, nickname, agent, paymentMethodDetails, hsaTagged
  • Behavior:
    • Update card or bank account details for an existing payment method
    • Set a payment method as default
    • ⚠️ HSA Tagging: Changing an existing card's paymentMethodDetails.hsaTagged value is processed only when the request originates from an active checkout session (e.g., the CCG Widget). If called directly without an active session, the submitted value is ignored and the card's existing tag is left unchanged. A tagged card cannot also be a manufacturer card or the wallet's default payment method, and a request carrying an agent cannot change the tag. At most one payment method per wallet can be tagged at a time β€” tagging a different card automatically untags the previously tagged card and emits a separate PAYMENT_METHOD_UPDATED webhook event for it.
  • Error Codes: Refer Update Payment Method Error Codes

Handling Update Payment Method​

  • Update nickname, default status, or details for a card or bank account
  • Update agent information if required
  • Restricted by merchant configuration (e.g., only cards or only bank accounts)
    • ⚠️ Merchant with CARD configuration will not be able to update BANK_ACCOUNT in customer wallet

Sample Request​

Update Card​

Sample Request – Update Card
{
"isDefault": false,
"nickname": "string",
"agent": {
"firstName": "string",
"lastName": "string",
"userId": "string",
"isAccessVerified": true
},
"paymentMethodDetails": {
"type": "CARD",
"expiryYear": 0,
"nameOnCard": "string",
"expiryMonth": 0,
"zipCode": "99950",
"manufacturerCard": true,
"hsaTagged": false
}
}

Update Bank Account​

Sample Request – Update Bank Account
{
"isDefault": false,
"nickname": "string",
"agent": {
"firstName": "string",
"lastName": "string",
"userId": "string",
"isAccessVerified": true
},
"paymentMethodDetails": {
"type": "BANK_ACCOUNT",
"nameOnAccount": "string",
"accountType": "checking"
}
}

Sample Response​

Sample Response – Card
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"default": true,
"paymentMethodType": "CARD",
"nickname": "string",
"sourceProvider": {
"name": "CCG"
},
"paymentMethodDetails": {
"type": "CARD",
"last4": "string",
"status": "ACTIVE",
"cardBrand": "VISA",
"expiryYear": 0,
"nameOnCard": "string",
"expiryMonth": 0,
"zipCode": "99950",
"manufacturerCard": true,
"hsaTagged": false
}
}
Sample Response – Bank Account
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"default": true,
"paymentMethodType": "BANK_ACCOUNT",
"nickname": "string",
"sourceProvider": {
"name": "CCG"
},
"paymentMethodDetails": {
"type": "BANK_ACCOUNT",
"accountHolderType": "string",
"accountType": "string",
"status": "ACTIVE",
"bankName": "string",
"last4": "string",
"routingNumber": "string",
"nameOnAccount": "string"
}
}

Notifications​

PAYMENT_METHOD_UPDATED event will be triggered to merchants if requested. Refer Webhooks

Error Handling​

Refer Update Payment Method Error Codes