Skip to content
/
Setting Up Autopay
Last updated

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:

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

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

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

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

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

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

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

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

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

Previous page
Next page