Skip to content
/
Payment Instrument Setup
Last updated

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:

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:

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:

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:

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:

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:

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

See also

  • Borrower Quickstart — Walks through creating a borrower and attaching their first contact and payment details.
  • Borrowers overview — Index of borrower-related entities and operations.
Previous page
Next page