# Payment Instrument Setup

This guide walks you through setting up payment instruments. We'll continue working with James Smith to add a bank account and debit card for loan payments.

## Overview

A payment instrument represents any method a borrower can use to make payments:

- Bank accounts (ACH)
- Debit cards
- Credit cards


You can add multiple payment instruments and designate them for different purposes like autopay or one-time payments.

## Prerequisites

Before you begin, make sure you have:

- A Peach account with API access
- Your API key
- borrower ID:


> **Note**: The following examples use commonly used fields, but for full details, including additional data and parameters, refer to the API Reference.


## Check Existing Payment Instruments

Let's first see what payment methods James already has:


```http
GET /people/{personId}/payment-instruments
X-API-KEY: <YOUR-API-KEY>
```

## Adding a Bank Account

Now let's add James' checking account for automatic payments:


```http
POST /people/{personId}/payment-instruments
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "instrumentType": "bankAccount",
  "accountType": "checking",
  "accountHolderType": "personal",
  "accountHolderName": "James Smith",
  "accountNumber": "123456789",
  "routingNumber": "021313103",
  "nickname": "Primary Checking",
  "status": "pending",
  "verified": false
}
```

### Verify Bank Account with Microdeposits

After creating the bank account, Peach will initiate two small deposits to verify account ownership. Once James sees these deposits, we can verify the account:


```http
POST /people/{personId}/payment-instruments/{instrumentId}/verify
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "deposit1": 32,
  "deposit2": 45
}
```

If successful, the account's `verified` status will change to `true`.

## Adding a Debit Card

Let's also add James' debit card as a backup payment method:


```http
POST /people/{personId}/payment-instruments
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "instrumentType": "card",
  "cardType": "debit",
  "accountHolderName": "James Smith",
  "cardNumber": "4111111111111111",
  "expirationMonth": 12,
  "expirationYear": 2025,
  "cvv": "123",
  "nickname": "Personal Debit",
  "status": "pending",
  "address": {
    "addressLine1": "1 Main St",
    "city": "Houston",
    "state": "TX",
    "postalCode": "77002",
    "country": "US"
  }
}
```

## Payment Instrument States

Each payment instrument has a status that indicates its usability:

- `pending` - Initial state after creation
- `active` - Ready for use in payments
- `inactive` - Temporarily unavailable
- `failed` - Failed verification or validation


## Verification Methods

Different payment types have different verification requirements:

### Bank Accounts

- Microdeposit verification (2-3 business days)
- Plaid instant verification (if configured)


### Cards

- Address verification (AVS)
- Card verification value (CVV)
- Test authorization


## Managing Payment Instruments

### Update Payment Details

If James's card expires, we can update it:


```http
PUT /people/{personId}/payment-instruments/{instrumentId}
X-API-KEY: <YOUR-API-KEY>
Content-Type: application/json

{
  "expirationMonth": 12,
  "expirationYear": 2026,
  "status": "active"
}
```

### Delete Payment Method

To remove an outdated payment instrument:


```http
DELETE /people/{personId}/payment-instruments/{instrumentId}
X-API-KEY: <YOUR-API-KEY>
```

## See also

- **[Borrower Quickstart](/borrowers/quickstart)** — Walks through creating a borrower and attaching their first contact and payment details.
- **[Borrowers overview](/borrowers)** — Index of borrower-related entities and operations.