# Update payment instrument

Endpoint: PUT /people/{personId}/payment-instruments/{paymentInstrumentId}
Version: 2025-03-26
Security: oauth2, bearerAuth, apiKeyHeader

## Path parameters:

  - `personId` (string, required)
    A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

  - `paymentInstrumentId` (string, required)
    The payment instrument identifier.

## Query parameters:

  - `sync` (boolean)
    Make the payment instrument authentication process synchronous. Only relevant for cards.

## Request fields (application/json):

  - `sendNotice` (boolean)
    When set to `true`, the system will send a `paymentMethodUpdated` notice to the borrower.

  - `externalId` (string)
    A lender's identifier for the instrument.
After the object is successfully created, a lender can use ID or externalId identifiers to fetch the object.
To fetch the object using externalId you need to add `ext-` to the URL.
Note: Don't add ext- to the identifier value. For example: if the external identifier is `ABCDE`, then pass externalId=ACBCE and NOT ext-ABCDE when creating the object.

  - `inactiveReason` (string)
    The reason the instrument is inactive. Required when setting status=`inactive`.
    Enum: "fraudAlert", "updated", "notVerified", "expired", "failed", "deleted"

  - `nickname` (string)
    A nickname for the instrument. The nickname can be displayed in UI.

  - `status` (string)
    Status of the instrument. Can only be set if `isExternal=true`.
Statuses:
- `active` - the instrument can be charged.
- `pending` - the instrument is pending to be verified.
- `inactive` - the instrument is not active and cannot be charged.

When updating this field, only the following state transitions are allowed.

```
active --> inactive
pending --> active (only for payment instrument with isExternal=true)
pending --> inactive (only for payment instrument with isExternal=true)
inactive --> active (only for payment instrument with isExternal=true)
inactive --> pending (only for payment instrument with isExternal=true)
```
Note: if you update the status from `inactive` to `active` or `pending`,
the system will clear the following attributes: `inactiveReason`, `deletedAt`, `failureReason`,
`failureDescriptionShort`, `failureDescriptionLong`.
    Enum: "active", "inactive", "pending"

  - `verified` (boolean)
    Indicates whether the instrument has been verified.
User must have the `payment.instrument:skip.verification` permission to set this value to `true`, or
the payment instrument must be marked `isExternal=true`.

  - `accountHolderName` (string)
    For `personal` accounts, the full name of the account holder. For `business` accounts, the business name.
This is not an account nickname. It should match the name on file for the account with the bank.

  - `accountHolderType` (string)
    Type of entity that is the account holder.
    Enum: "business", "personal"

  - `address` (object)
    The mailing address.

  - `address.POBox` (string)
    Post Office Box

  - `address.addressLine1` (string)
    Address line 1.
If `company.allowPartialAddress=false`, then this field is required, else it is not required

  - `address.addressLine2` (string)
    Address line 2.

  - `address.city` (string)
    City.

  - `address.country` (string)
    Country. English short name according to
[ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) standard.

  - `address.countyOrRegion` (string)
    County or region.

  - `address.postalCode` (string)
    Postal code. Also known as ZIP code.

  - `address.state` (string)
    State/Province. This is a required field if the country is US or CA.

  - `payToTheOrderOfName` (string)
    The name of a person or organization designated to receive the funds,
such as "John Smith" or "Peach Finance, Inc". Defaults to "Cash",
used when you don't know the person or organization's exact name.