---
title: "Replace a payment method"
method: PUT
path: "/billing/customers/{customerId}/paymentmethods/{paymentMethodToken}/new"
---

# Replace a payment method

`PUT /billing/customers/{customerId}/paymentmethods/{paymentMethodToken}/new`

## Request

- Base URL: `https://api-sandbox.ezypay.com/v2`
- URL: `https://api-sandbox.ezypay.com/v2/billing/customers/{customerId}/paymentmethods/{paymentMethodToken}/new`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://identity-sandbox.ezypay.com/token`

Replace a payment method with another payment method while keeping all existing customer, subscription and invoice links. This is useful when replacing invalid payment methods to existing customers without needing to additionally update their subscription and invoice details.

## Path parameters

- `paymentMethodToken` string, required
- `customerId` string, required

## Headers

- `merchant` string, required

## Request body

- object
  - `newPaymentMethodToken` string, required: Auto-generated unique identifier of the payment method token generated by vault.
  - `primary` string: Indicator to set this payment method as Customer's preferred Payment Method. `PromptPay` payment method token cannot be set as the `primary` payment method.

## Response `200`

200

- object
  - `paymentMethodToken` string
  - `customerId` string
  - `type` string
  - `bank` unknown
  - `card` object
    - `first6` string
    - `last4` string
    - `accountHolderName` string
    - `type` string
    - `expiryMonth` string
    - `expiryYear` string
  - `invalidReason` unknown
  - `lastUsedOn` unknown
  - `replacedPaymentMethodData` object
    - `paymentMethodToken` string
    - `customerId` string
    - `type` string
    - `bank` unknown
    - `card` object
      - `first6` string
      - `last4` string
      - `accountHolderName` string
      - `type` string
      - `expiryMonth` string
      - `expiryYear` string
    - `invalidReason` unknown
    - `lastUsedOn` unknown
    - `replacedPaymentMethodData` unknown
    - `valid` boolean
    - `primary` boolean
  - `valid` boolean
  - `primary` boolean

## Other responses

- `400`: 400

## Changes

- **2026-11-03** `924be4030f56`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ezypay/apis/vault/changes/billing/customers/:customerId/paymentmethods/:paymentMethodToken/new/put.md)

---

[API](https://skmtc.dev/ezypay/apis/vault.md) - [All operations](https://skmtc.dev/ezypay/apis/vault/llms.txt) - [OpenAPI document](https://skmtc.dev/ezypay/apis/vault/revisions/924be4030f56?raw)