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
- Allowed Session Modes:
- 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.hsaTaggedvalue 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 anagentcannot 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 separatePAYMENT_METHOD_UPDATEDwebhook event for it.
- Error Codes: Refer Update Payment Method Error Codes
-
- Notifications: Refer Webhooks
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
CARDconfiguration will not be able to updateBANK_ACCOUNTin customer wallet
- β οΈ Merchant with
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