# Create payment instrument

Create a payment instrument.
When creating a payment instrument using the Plaid Account option, two flows are supported:
1) Pass only `accessToken` and `accountIds`. This will create a payment instrument with `status`=`inactive`.
You can then use <a href="./payment-instruments/peach.payment_instruments.handlers.person_payment_instrument_update">Update payment instrument</a>
endpoint to set the `accountHolderType`, and `accountHolderName` fields, and set the `status` to `active`.
2) Pass the required fields as well as `accountHolderType`, and `accountHolderName`. This will create a payment
instrument with `status`=`active`. The payment instrument will then be ready to use.

*Note: This endpoint returns an array containing a single payment instrument to allow future support for Plaid multi-account select.*

Endpoint: POST /people/{personId}/payment-instruments
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.

## Query parameters:

  - `force` (boolean)
    Overrides the results of BIN / Routing Number lookup. Requires the `payment.instrument:force` permission.

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

  - `allowDuplicates` (boolean)
    For external payment instruments, skip duplicate checks. Allows the creation two external payment instruments with the same last 4 digits on the same borrower.

## Request fields (application/json):

  - `accountNumber` (string, required)
    The account number.
If `isExternal=true` then the last two, three, or four digits of the account number can be provided.
Provide four digits if available, otherwise provide two or three digits.

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

  - `cardNumber` (string, required)
    The card number.
If `isExternal=true` then only the last two, three, or four digits of the card number can be provided.
Provide four digits if available, otherwise provide two or three digits.
    Example: 4111111111111111

  - `accessToken` (string, required)
    `public_token` provided by Plaid Link.
**NOTE**: Plaid Link tokens are associated with a specific Plaid API key. If you are performing a Plaid Link in your app/website
and pass it to the Peach API you will first need to set your Plaid API key in the Peach API. Please contact Peach Support
to get access to the Plaid API Key setting endpoint and instructions on how to use it.
If you wish to use your own Plaid Link token in the sandbox environment, please contact Peach Support as you might need
to configure your Plaid sandbox account in a certain way.

  - `accountIds` (array, required)
    List of Plaid account IDs selected by user, provided by Plaid Link

  - `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.

  - `instrumentType` (string)
    Enum: "plaid"

  - `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"

  - `institutionName` (string)
    The name of the financial institution where this account resides. If empty, will default to the name associated
with the routing number.

  - `accountNumber` (string)
    The account number from where the wire was sent. Must consist of only digits.
If `isExternal=true` then the last two, three, or four digits of the account number can be provided.
Provide four digits if available, otherwise provide two or three digits.

## Response 201 fields (application/json):

  - `count` (integer, required)

  - `status` (integer)
    HTTP status code.

  - `data` (array, required)

  - `data.failureDescriptionLong` (string)
    Detailed text describing the failure reason and any appropriate actions the borrower may take to fix the issue.
Normally displayed in UI.

  - `data.failureDescriptionShort` (string)
    Short text describing the failure reason. Normally displayed in UI.

  - `data.failureReason` (string)
    The transaction failure reason.
    Enum: "insufficientFunds", "chargeback", "accountClosed", "invalidAccount", "unknownReason", "invalidCvv", "invalidExpirationDate", "avsFailed", "networkError", "cardDeclined", "accountFrozen", "deceased", "invalidRouting", "paymentStopped", "microdepositsFailed", "microdepositsAttemptFailed", "incorrectNumber", "fraudulent", "unauthorizedDebit"

  - `data.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.

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

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

  - `data.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"

  - `data.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`.

  - `data.accountNumberLastFour` (string)
    The last two, three or four digits of the account number.
Normally, you should expect four digits. Two or three digits are returned when four digits are not available.

  - `data.instrumentType` (string)
    Enum: "bankAccount"

  - `data.routingNumber` (string)
    The routing number.

  - `data.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.

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

  - `data.accountLink` (object)
    An object representing a link with a third party vendor (e.g. Plaid) that allows fetching additional account details.

  - `data.accountLink.accessToken` (string, required)
    The vendor's access token for initial access. With Plaid, this can be the `public_token` provided by Plaid Link, or the `access_token` provided after exchanging the public token.

  - `data.accountLink.accountId` (string, required)
    The identifier used to identify an account with the data vendor.

  - `data.accountLink.dataServices` (array)
    A list of data services available with this link.

  - `data.accountLink.errorCommunicationsSent` (integer)
    The number of times the user has been notified that the account link has failed and needs to be recreated.

  - `data.accountLink.itemId` (string)
    The vendor's item identifier. With Plaid, this is the `item_id`.

  - `data.accountLink.lastErrorCommunicationAt` (string)
    The date and time that the most recent error notification was sent to the user.

  - `data.accountLink.recentError` (object)
    The most recent error that occurred while fetching data from this link.

  - `data.accountLink.recentError.errorCodeByVendor` (string)
    The error code as received from the vendor.

  - `data.accountLink.recentError.errorDescriptionBorrower` (string)
    The error description as received from the vendor for presentation to the borrower.

  - `data.accountLink.recentError.errorDescriptionInternal` (string)
    The internal error description as received from the vendor.

  - `data.accountLink.recentError.errorType` (string)
    The error type. This describes the appropriate way to handle the error.
    Enum: "retry", "relink", "outage"

  - `data.accountLink.recentError.errorTypeByVendor` (string)
    The error type as received from the vendor.

  - `data.accountLink.status` (string)
    The status of the account link.
    Enum: "active", "inactive"

  - `data.accountLink.vendor` (string, required)
    The data vendor identifier.
    Enum: "plaid"

  - `data.accountType` (string)
    Type of the account.
    Enum: "checking", "savings"

  - `data.institutionName` (string)
    The name of the financial institution where this account resides. If empty, will default to the name associated
with the routing number.

  - `data.cardNumberLastFour` (any)
    The last two, three or four digits of the card number.
Normally, you should expect four digits. Two or three digits are returned when four digits are not available.
    Example: 1111

  - `data.cardType` (string)
    The type of card.
- For external payment instruments, this field is required, and does not require additional permissions.
- Otherwise, this field is not required, and using it requires permission `payment.instrument:force`.
    Enum: "credit", "debit"

  - `data.issuer` (string)
    Issuing bank. Requires permission `payment.instrument:force`.

  - `data.network` (string)
    Card network. Requires permission `payment.instrument:force`.
    Enum: "visa", "mastercard", "discover", "americanExpress"

  - `data.address` (object)
    The mailing address.

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

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

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

  - `data.address.city` (string)
    City.

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

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

  - `data.address.object` (string)
    Enum: "address"

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

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

  - `data.address.timezone` (string)
    Timezone for the address.

  - `data.expirationMonth` (integer)
    The expiration month of the card.
    Example: 12

  - `data.expirationYear` (integer)
    The expiration year of the card.
    Example: 2032

  - `data.firstName` (string)
    First name on the card.

  - `data.lastName` (string)
    Last name on the card.

  - `data.checkNumber` (string)
    The check sequence number. Typically located in the top right corner of the check.

  - `data.institutionName` (string)
    The name of the bank where this account resides.

  - `data.isExternal` (boolean)
    Enum: true

  - `data.serialNumber` (string)
    The money order serial number.

  - `data.routingNumber` (string)
    The routing number from where the wire was sent.

  - `data.wireNumber` (string)
    The wire number. Must be unique.

  - `data.wireType` (string)
    Enum: "domestic", "international"