# Setting Up Autopay

This guide explains how to set up autopay for borrower loans. You'll learn to create payment methods, manage autopay agreements, and establish automatic payments through a step-by-step process.

## Overview

The Autopay API enables programmatic, recurring loan payments in Peach implementations. The process is divided into three main stages:

1. **Creating a Payment Instrument**
2. **Handling the Autopay Agreement Document**
3. **Finalizing the Autopay Configuration**


## Configuration Options

When finalizing autopay setup, you have several configuration options:

- `amountType` : Determines what amount will be automatically paid
- `statementBalanceAmount` : Pay the full statement balance
- `statementMinimumAmount` : Pay only the minimum amount due
- `isAlignedToDueDates` : When true, autopay dates will match the loan's due dates
- `offsetFromDueDate` : Number of days before/after the due date to process the payment.


## Prerequisites

Before starting, ensure the following:

- You have a Peach account with API access.
- API credentials are ready.
- A borrower record already exists.


## Authentication

Include your API key in the request header for all API calls:


```http
X-API-KEY: YOUR_API_KEY
```

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


## Setting Up Autopay

### Step 1: Create a Payment Instrument

The first step involves creating a payment instrument for automatic payments.

**Request**


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

{
  "status": "active",
  "verified": true,
  "nickname": "Bank",
  "instrumentType": "bankAccount",
  "accountNumber": "12341111",
  "routingNumber": "103000648",
  "accountType": "checking",
  "accountHolderType": "personal",
  "accountHolderName": "John Doe"
}
```

**Response**


```json
{
  "data": [{
    "accountHolderName": "John Doe",
    "accountHolderType": "personal",
    "accountNumberLastFour": "1234",
    "accountType": "checking",
    "companyId": "CP-3421-7842",
    "createdAt": "2022-09-30T19:18:01.404070+00:00",
    "id": "PT-9087-4563",
    "nickname": "Bank",
    "status": "active",
    "verified": true
  }],
  "message": "Created payment instrument",
  "status": 201
}
```

Save the `id` (`paymentInstrumentId`) for later.

### Step 2: Handle the Autopay Agreement Document

Borrowers must accept an autopay agreement before activation.

**2.1 Create Document Descriptor**


```http
POST /people/{personId}/documents
Content-Type: application/json
X-API-KEY: YOUR_API_KEY

{
  "type": "loanAutopayAgreement",
  "status": "draft",
  "loanId": "LN-2348-5679",
  "fileName": "LoanAutopayAgreement-LN-2348-5679.html"
}
```

**Response**


```json
{
  "id": "DD-5678-1234",
  "loanId": "LN-2348-5679",
  "status": "draft",
  "type": "loanAutopayAgreement",
  "fileName": "LoanAutopayAgreement-LN-2348-5679.html",
  "companyId": "CP-3421-7842"
}
```

Save the `documentDescriptorId` (`id`) for later.

**2.2 Render the Agreement Document**


```http
POST /communicator/render-to-document?fmt=html
Content-Type: application/json
X-API-KEY: YOUR_API_KEY

{
  "fmt": "pdf",
  "subject": "autopayAgreement",
  "documentId": "DD-5678-1234",
  "context": {
    "lenderName": "Your Lender Name",
    "paymentMethod": "bankAccount",
    "paymentMethodLastFour": "1234",
    "dateSigned": "2024-12-12"
  },
  "loanId": "LN-2348-5679"
}
```

**2.3 Mark Agreement as Accepted**


```http
PUT /people/{personId}/documents/{documentDescriptorId}
Content-Type: application/json
X-API-KEY: YOUR_API_KEY

{
  "status": "accepted"
}
```

### Step 3: Configure Autopay

Finally, create the autopay configuration using the payment instrument and agreement document:

**Request**


```http
POST /people/{personId}/loans/{loanId}/autopay
Content-Type: application/json
X-API-KEY: YOUR_API_KEY

{
  "previewMode": false,
  "amountType": "statementBalanceAmount",
  "isAlignedToDueDates": true,
  "paymentInstrumentId": "PT-9087-4563",
  "agreementDocumentId": "DD-5678-1234"
}
```

**Response**


```json
{
  "data": {
    "agreementDocumentId": "DD-5678-1234",
    "paymentInstrumentId": "PT-9087-4563",
    "paymentFrequency": "monthly",
    "schedule": [{
      "amount": 473.78,
      "date": "2022-10-15",
      "status": "booked"
    }],
    "type": "statementBalanceAmount"
  },
  "status": 200
}
```

## Next steps

- **[Peach Processing](/payments/peach-processing)** — Configure Peach as your payment processor before enabling autopay.
- **[Payment Processing Overview](/payments)** — Index of payment processing options and concepts.