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
• Behavior:
  • Update card or bank account details for an existing payment method
  • Set a payment method as default
• 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 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
  }
}

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
  }
}

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