# Create Autopay plan

Endpoint: POST /people/{personId}/loans/{loanId}/autopay
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.

  - `loanId` (string, required)
    The unique identifier of the Loan we wish to retrieve. Can be
Peach or lender's external identifier.

## Request fields (application/json):

  - `agreementDocumentId` (string)
    The document ID for the signed autopay agreement. Required if `previewMode=false`.

  - `caseId` (string)
    An identifier for an existing case.

  - `isAlignedToDueDates` (boolean)
    `true` - the Autopay payments will be aligned and processed on the loan's due dates.
`false` - the Autopay payments schedule will be different from the loan's due dates schedule.
If `isAlignedToDueDates=false` then `paymentFrequency` and `specificDays` must be provided.
If the frequency and specific days of autopay matches the loan, we assume that it is `isAlignedToDueDates=true`.

  - `paymentFrequency` (string)
    The Autopay payments frequency.
    Enum: "weekly", "everyTwoWeeks", "twiceMonthly", "monthly"

  - `paymentInstrumentId` (string, required)
    The payment instrument ID with which this autopay plan will be charged through.

  - `previewMode` (boolean)
    In `previewMode=true`, the loan doesn't change, and no changes are saved to the database.

  - `sendNotice` (boolean)
    When set to `false`, the system will NOT send a `autopayEnabled` notice to the borrower.

  - `specificDays` (array)
    Specific days designate the day(s) that due dates will fall on. The allowed values for specific
day(s) depends on the `paymentFrequency`.
`weekly` - provide one number in the valid range 1-7. 1=Monday...7=Sunday.
For example: [1].
`everyTwoWeeks` - provide two inputs. The first input (required) is an integer in the valid range 1-7. 1=Monday...7=Sunday.
The second input is a date that indicates when to start the cycle. If the second input is not passed, the system will default
to the first valid start date based on the first input (the day of week passed in). If this date is provided then it can override
the minimum due date gap specified on the loan type.
For example: [1, "2020-09-16"].
`twiceMonthly` - provide two numbers in the valid range 1-31. 1=first day of a month. Use 31 to
indicate the last day of a month.
For example: [1, 15] or [15, 31].
`monthly` - provide one or two numbers, depending on the loan type `periodCalculationType` configuration:
- If `periodCalculationType=dueDate`, then provide one number in the valid range 1-31. This is the recurring due date. 1=first
day of a month. Use 31 to indicate the last day of a month. For example: [1].
- If `periodCalculationType=statementDate`, then provide one number in the valid range 1-31. This is the recurring statement date.
1=first day of a month. Use 31 to indicate the last day of a month. For example: [1].
- If `periodCalculationType=fixedStatementAndDueDates`, then provide two numbers. First number represents a recurring statement
date and the valid range is 1-31. Use 31 to indicate the last day of a month. Second number represents a recurring due date and
the valid range is 1-28. Two numbers must be different. For example: [1, 15] - statements are on 1st and due dates are on 15th.
Notes:
  - If the due date precedes the statement day, it's pushed to the next month. For example: [20, 10] and today is Oct 1, 2024. The
first statement date is Oct 20, 2024 and the first due date is Nov 10th.
  - For February in non-leap years, if the statement date is ≥ 29 and the due date is 28, the statement date becomes March 1st.

`singleTerm` - provide one number to indicate duration as a number of calendar days or provide a valid calendar date in the
future. This option is only valid for use on the installment type and at loan origination.
For example: [90] or ["2020-09-16"].
For `weekly`, `everyTwoWeeks`, `twiceMonthly`, `monthly`:
If specificDays is left null, then the system will calculate due dates according to the paymentFrequency relative
to the origination or activation date (or use existing specific days in the case of change due date).
For `singleTerm`:
The specificDays is mandatory.

  - `amountType` (string)
    Indicates how Autopay amount will be calculated for each closed statement.
`statementMinimumAmount` - an Autopay will debit the statement minimum amount for the period. The statement minimum
amount is defined as the sum of the expected payment amounts in the given period.
`statementMinimumAmountPlusExtra` - an Autopay will debit the statement minimum amount for the period plus
extra amount. The extra amount is typically applied to principal. In any given autopay period, if the
'statementMinimumAmountPlusExtra' is greater than the outstanding balance on the line of credit, we only debit
up to the amount of the latter.
`statementBalanceAmount` - an Autopay transaction will debit the statement balance as of the statement creation
date for the given period.
    Enum: "statementMinimumAmount", "statementMinimumAmountPlusExtra", "statementBalanceAmount"

  - `extraAmount` (number)
    The extra amount that the borrower agrees to pay if `type=statementMinimumAmountPlusExtra`.

  - `isAlignedToDueDates` (boolean)
    `true` - the Autopay transactions will be processed on the loan's due dates.
`false` - the Autopay transactions schedule will be different from the loan's due dates schedule.
If `isAlignedToDueDates=false` then `offsetFromDueDate` must be provided.

  - `offsetFromDueDate` (array)
    Number of calendars days before due dates when Autopay payments are processed.
If `isAlignedToDueDates` is false, it is required to specify the offset from the due dates. Depending on whether there are 1 or 2 auto-payments
per period, the array should include either 1 or 2 integers.
- `onceAPeriod` - borrower can choose X days before the due date. Provide one number in a valid range between "1" and "statement to due date"
days (e.g. 14 or 21). For example: `[5]` means the Autopay will be processed 5 calendar days before a given due date.
- `twiceAPeriod` - borrower can choose two offsets, in other words, Autopay will process half the amount on the first Autopay date, and half
the amount on the second Autopay date. Both days are "offsets", with "0" meaning on the due date. For example: `[5, 0]` means the first Autopay
payment will be scheduled and processed 5 days before the due date, and the second Autopay payment will be scheduled and processed on the due date.

  - `previewMode` (boolean)
    If `previewMode=true`, the loan doesn't change and no changes are saved to the database.

## Response 200 fields (application/json):

  - `message` (string)
    Description of the server action or error.

  - `status` (integer)
    HTTP status code.

  - `data` (object)
    The delta change in interest, fees, calendar days, and number of due dates. Only relevant for installment loans. For
non installment loans, `deltaTerms` fields will be null.

  - `data.isLocked` (boolean)
    If true, the loan is in the middle of being updated or replayed. The returned data are not consistent. The caller should poll
on the `Get loan lock status` endpoint. Once `isLocked`` becomes `false`, the caller should call this endpoint again to get consistent data.

  - `data.agreementDocumentId` (string)
    The document descriptor ID corresponding to the autopay agreement document.

  - `data.cancelReason` (string)
    Why the autopay was canceled.
    Enum: "invalidPaymentMethod", "paymentMethodRemoved", "tooManyFailedAttempts", "loanFrozen", "loanAccelerated", "loanChargedOff", "loanPaidOff", "canceledByUser", "loanTermsChanged"

  - `data.createdAt` (string)

  - `data.id` (string)
    The autopay identifier.

  - `data.paymentFrequency` (string)
    The Autopay payments frequency.
    Enum: "weekly", "everyTwoWeeks", "twiceMonthly", "monthly"

  - `data.paymentInstrumentId` (string)
    The payment instrument ID with which this autopay plan will be charged through.

  - `data.schedule` (array)

  - `data.schedule.amount` (number)
    The amount of the expected payment.

  - `data.schedule.date` (string)
    The due date of the expected payment.

  - `data.schedule.dynamicFeeDetails` (object)
    When `paymentType`=`dynamicFee` this will contain details of the dynamic fee.

  - `data.schedule.dynamicFeeDetails.apiName` (string)
    The API name of the dynamic fee. For example: 'lateFee' or 'breatherFee'.

  - `data.schedule.dynamicFeeDetails.displayName` (string)
    The display name of the dynamic fee as shown to the borrower in the UI. For example: `Late Fee` or `Breather Fee`.

  - `data.schedule.dynamicFeeDetails.dynamicFeeTypeId` (string)
    The dynamic fee type identifier in the system.

  - `data.schedule.dynamicFeeDetails.loanFeeId` (string)
    The loan fee identifier in the system.

  - `data.schedule.interestAmount` (number)
    The portion of the `amount` allocated to net interest.
Available only for `paymentType=periodicPayment`.

  - `data.schedule.interestBeforeDiscountAmount` (number)
    The interest amount that was accrued before promo rate(s) or any discount.
Available only for `paymentType=periodicPayment`.

  - `data.schedule.isDeferred` (boolean)
    `true` if the amount of this expected payment has been deferred before.

  - `data.schedule.originalAmount` (number)
    The amount of the expected payment at creation. The `amount` will change as a result of refreshing
expected payments, but the `originalAmount` will stay the same.

  - `data.schedule.paymentType` (string)
    The payment type.
    Enum: "periodicPayment", "originationFee", "drawFee", "dynamicFee", "downPayment", "discountCredit"

  - `data.schedule.periodId` (string)
    The period identifier.

  - `data.schedule.principalAmount` (number)
    The portion of the `amount` allocated to principal.
Available only for `paymentType=periodicPayment`.

  - `data.schedule.status` (string)
    The status of the expected payment.
`booked` - borrower is or was expected to make the payment.
`modified` - the amount was modified at some point and different from the original amount.
`canceled` - borrower is or was not expected to make the payment.
`processed` - a payment has been scheduled for this expected payment.
    Enum: "booked", "modified", "canceled", "processed"

  - `data.specificDays` (array)
    Specific days designate the day(s) that due dates will fall on. The allowed values for specific
day(s) depends on the `paymentFrequency`.
`weekly` - provide one number in the valid range 1-7. 1=Monday...7=Sunday.
For example: [1].
`everyTwoWeeks` - provide two inputs. The first input (required) is an integer in the valid range 1-7. 1=Monday...7=Sunday.
The second input is a date that indicates when to start the cycle. If the second input is not passed, the system will default
to the first valid start date based on the first input (the day of week passed in). If this date is provided then it can override
the minimum due date gap specified on the loan type.
For example: [1, "2020-09-16"].
`twiceMonthly` - provide two numbers in the valid range 1-31. 1=first day of a month. Use 31 to
indicate the last day of a month.
For example: [1, 15] or [15, 31].
`monthly` - provide one or two numbers, depending on the loan type `periodCalculationType` configuration:
- If `periodCalculationType=dueDate`, then provide one number in the valid range 1-31. This is the recurring due date. 1=first
day of a month. Use 31 to indicate the last day of a month. For example: [1].
- If `periodCalculationType=statementDate`, then provide one number in the valid range 1-31. This is the recurring statement date.
1=first day of a month. Use 31 to indicate the last day of a month. For example: [1].
- If `periodCalculationType=fixedStatementAndDueDates`, then provide two numbers. First number represents a recurring statement
date and the valid range is 1-31. Use 31 to indicate the last day of a month. Second number represents a recurring due date and
the valid range is 1-28. Two numbers must be different. For example: [1, 15] - statements are on 1st and due dates are on 15th.
Notes:
  - If the due date precedes the statement day, it's pushed to the next month. For example: [20, 10] and today is Oct 1, 2024. The
first statement date is Oct 20, 2024 and the first due date is Nov 10th.
  - For February in non-leap years, if the statement date is ≥ 29 and the due date is 28, the statement date becomes March 1st.

`singleTerm` - provide one number to indicate duration as a number of calendar days or provide a valid calendar date in the
future. This option is only valid for use on the installment type and at loan origination.
For example: [90] or ["2020-09-16"].
For `weekly`, `everyTwoWeeks`, `twiceMonthly`, `monthly`:
If specificDays is left null, then the system will calculate due dates according to the paymentFrequency relative
to the origination or activation date (or use existing specific days in the case of change due date).
For `singleTerm`:
The specificDays is mandatory.

  - `data.cancelReason` (string)
    Why the transaction was canceled.
    Enum: "invalidPaymentMethod", "paymentMethodRemoved", "tooManyFailedAttempts", "loanFrozen", "loanAccelerated", "loanChargedOff", "loanPaidOff", "canceledByUser", "loanTermsChanged"

  - `data.extraAmount` (number)
    The extra amount that the borrower agrees to pay if `type=statementMinimumAmountPlusExtra`.

  - `data.isAlignedToDueDates` (boolean)
    `true` - the Autopay transactions will be processed on the loan's due dates.
`false` - the Autopay transactions schedule will be different from the loan's due dates schedule.
If `isAlignedToDueDates=false` then `paymentFrequency` and `specificDays` must be provided.

  - `data.offsetFromDueDate` (array)

  - `data.paymentFrequency` (string)
    The Autopay payments frequency. `Weekly` frequency is not supported for line of credit.
    Enum: "twiceMonthly", "everyTwoWeeks", "monthly"

  - `data.type` (string)
    Indicates how Autopay amount will be calculated for each closed statement.
`statementMinimumAmount` - an Autopay will debit the statement minimum amount for the period.
`statementMinimumAmountPlusExtra` - an Autopay will debit the statement minimum amount for the period plus
extra amount. The extra amount is typically applied to principal. This is ONLY applicable to non-amortized
line of credit loans.
`statementBalanceAmount` - an Autopay transaction will debit the statement balance for the period. This is ONLY applicable to non-amortized
line of credit loans.
    Enum: "statementMinimumAmount", "statementMinimumAmountPlusExtra", "statementBalanceAmount"