Payment Plans

Payment plans are a specific type of hardship tool that can be used to create a temporary loan schedule for a borrower. Lenders can create a payment plan by specifying the paymentPlanType, numberOfPeriods and amount. After the numberOfPeriods ends, any remaining periods of the loan will be paid according to the originally scheduled recurring amount and frequency of the loan at the time when the payment plan was created.

When the agreed upon recurring payment plan amount is less than the originally scheduled payment amount, the system uses isExtendLoanDuration to ascertain whether to keep the existing loan duration or automatically extend the original loan duration.

When the agreed upon recurring payment plan amount is more than the originally scheduled recurring amount, the loan duration will be shortened to the point where the remaining balance of the loan is paid off.

Only one active payment plan is allowed at a time. Please note that creating an active payment plan will overwrite changes made to the loan schedule such as due date deferrals, change due date, and change loan terms. This is because the payment plan by design creates a new loan schedule.

If a loan is on a payment plan, other hardship tools cannot be used. Lenders must cancel the payment plan and then make any required loan modifications.

Payment plan is presently for installment only.

Create payment plan

Creates a custom payment plan for the borrower. numberOfPeriods is required. If paymentPlanType=fixedAmountAndFees, then the amount is required.

Only applicable to installment loans.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

loanId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

The unique identifier of the Loan we wish to retrieve. Can be Peach or lender's external identifier.

Request Body schema: application/json
required
externalId
string (customPaymentPlanExternalId)

A lender's identifier for a payment pay plan.

After the object is successfully created, a lender can use ID or externalId identifiers to fetch the object.

To fetch the object using externalId you need to add ext- to the URL.

Note: Don't add ext- to the identifier value. For example: if the external identifier is ABCDE, then pass externalId=ACBCE and NOT ext-ABCDE when creating the object.

previewMode
boolean
Default: false

In previewMode=true, the loan doesn't change, and no changes are saved to the database.

sendNotice
boolean (SendNoticeCancelAutopay)
Default: true

When set to false, the system will NOT send a loanPaymentScheduleChanged notice to the borrower.

Note: Changing the loan terms will automatically cancel an existing Autopay (if enabled). A borrower, an agent or API caller needs to turn on / enable a new Autopay plan after the loan terms change is completed. If the loan has Autopay enabled:

  • When sendNotice=false, the system will NOT send an autopayCanceledBySystem notice.
  • When sendNotice=true, the system will send an autopayCanceledBySystem notice in addition to the applicable loan terms notice.
paymentPlanType
string (customPaymentPlanType)
Default: "fixedAmountAndFees"

Determines how the system will calculate payment plan payments during the payment plan's numberOfPeriods.

fixedAmountAndFees - the payment plan payment amounts will be set as a recurring amount. Note that any configured recurring fees (e.g. service fees) will also be included in the payment plan amount unless explicitly canceled. amount must be passed at the time of payment plan creation when using this option.

interestAndFees - the payment plan amounts will be calculated by Peach's system as "interest only". Note that any configured recurring fees (e.g. service fees) will also be included in the payment plan amount unless explicitly canceled. Do not pass amount when using this option.

Enum: "fixedAmountAndFees" "interestAndFees"
selectedDueDate
string <date> (customPaymentPlanSelectedDueDate)

The due date of the period from which to begin the payment plan. If selectedDueDate is not provided upon payment plan creation, the system will use the current period due date as the selectedDueDate. If selectedDueDate is provided, it must be for a due date in the future.

numberOfPeriods
required
integer (customPaymentPlanNumberOfPeriods)

The number of periods during which the payment plan terms are effective. Represented as the number of paymentFrequency periods. The system will begin counting the numberOfPeriods from the period represented by the selectedDueDate.

The numberOfPeriods of the payment plan must take place within the existing loan duration. Moreover, if isExtendLoanDuration is true, the numberOfPeriods must end on or before the last period of the loan. If isExtendLoanDuration is false, then numberOfPeriods for the payment plan must end on or before the second to last payment.

For example, if the payment plan frequency=weekly and numberOfPeriods=6 and the remaining loan duration is 12, the payment plan will be created with a 6 weeks duration during which the designated payment plan amount is in effect. Any subsequent periods after the payment plan has ended will revert to the original periodic payment amount.

amount
number <float> (customPaymentPlanAmount)

Amount required to be fulfilled for each payment plan period. The amount provided should be the recurring amount rather than the total amount of the plan. Peach's system will use the amount provided to determine whether the borrower is past due and report to bureaus accordingly (if applicable). Note: Any fees added during the duration of the payment plan must also be paid in order for the borrower to remain "current".

amount can be higher or lower than the borrower's originally contracted amount. Peach's system will revert to the recurring amount after the payment plan end date if the loan still has a balance at the end of the payment plan.

Do not pass this attribute if the payment plan type is interestAndFees.

isExtendLoanDuration
boolean (customPaymentPlanIsExtendLoanDuration)
Default: true

If true, the system may adjust and increase the loan duration beyond the current end date to accommodate the payment plan. If false, the system will not add additional periods beyond the current loan duration.

caseId
string

An identifier for an existing case.

Responses
200

Success

post/people/{personId}/loans/{loanId}/custom-payment-plans
Request samples
application/json
{
  • "externalId": "string",
  • "previewMode": false,
  • "sendNotice": true,
  • "paymentPlanType": "fixedAmountAndFees",
  • "selectedDueDate": "2019-08-24",
  • "numberOfPeriods": 0,
  • "amount": 0,
  • "isExtendLoanDuration": true,
  • "caseId": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get payment plans

Returns all payment plans associated with a loan.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

loanId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

The unique identifier of the Loan we wish to retrieve. Can be Peach or lender's external identifier.

query Parameters
status
string

Use this to filter a search for custom payment plans that are active, inactive or canceled.

Enum: "active" "inactive" "canceled"
Responses
200

Success

get/people/{personId}/loans/{loanId}/custom-payment-plans
Response samples
application/json
{
  • "status": 0,
  • "count": 0,
  • "data": [
    ]
}

Get payment plan by id

Return a single payment plan.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

loanId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

The unique identifier of the Loan we wish to retrieve. Can be Peach or lender's external identifier.

paymentPlanId
required
string

The identifier of the payment plan.

Responses
200

Success

get/people/{personId}/loans/{loanId}/custom-payment-plans/{paymentPlanId}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Cancel payment plan

Use this endpoint to cancel a payment plan. Any existing payment plan must be canceled prior to creating a new payment plan. After canceling a payment plan, Peach's system will revert the loan schedule (from the current period onwards) to the previous recurring payment amount and frequency prior to creating the payment plan.

As a result of cancellation, the loan duration and loan end date will be adjusted to match with the last non zero expected payment, if required.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

loanId
required
string (AnyId) ^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+...

The unique identifier of the Loan we wish to retrieve. Can be Peach or lender's external identifier.

paymentPlanId
required
string

The identifier of the payment plan.

Request Body schema: application/json
required
cancellationReason
required
string (customPaymentPlanCancellationReason)

The cancellation reason:

canceledByUser - payment plan was canceled by an agent or borrower.

loanTermsChanged - loan terms changed.

loanChargedOff - loan was charged off.

loanAccelerated - loan was accelerated.

otherPaymentPlanOffered - another payment plan was offered.

other - for any other reason requiring cancellation.

Enum: "canceledByUser" "loanTermsChanged" "loanChargedOff" "loanAccelerated" "otherPaymentPlanOffered" "other"
reasonDetails
string (customPaymentPlanReasonDetails)

The reason for payment plan cancellation. This is typically entered by an agent canceling a payment plan via the front end.

caseId
string

An identifier for an existing case.

sendNotice
boolean
Default: false

When set to false, the system will NOT send a loanPaymentScheduleChanged notice to the borrower.

Responses
204

Success

post/people/{personId}/loans/{loanId}/custom-payment-plans/{paymentPlanId}/cancel
Request samples
application/json
{
  • "cancellationReason": "canceledByUser",
  • "reasonDetails": "string",
  • "caseId": "string",
  • "sendNotice": false
}

Request sandbox access