Promise to Pay Plans

This object represents a Promise to Pay Plan. A Promise to Pay Plan is a group of Promise to Pay Periods— unscheduled payments that was verbally committed by a borrower. Promise to Pay Plans are defined on an account level. Promise to Pay Plans are not guaranteed payments. They are used to track verbal commitments made by borrowers.

Note: When creating or updating a Promise to Pay Plan, either pass a schedule object, or pass schedule descriptor attributes— startDate, frequency, specificDays, duration and amount. Mixing the two approaches is not allowed.

Get Promise to Pay Plans for a company

Returns Promise to Pay Plans for a given company.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
query Parameters
status
Array of strings

Filter by status. Possible values are scheduled, active, kept, broken, canceled.

Items Enum: "scheduled" "active" "kept" "broken" "canceled"
isOverdue
boolean

Filter by overdue status. Possible values are true, false.

Enum: true false
startDateAfter
string <date>

Filter by start date after. Format: YYYY-MM-DD.

endDateBefore
string <date>

Filter by end date before. Format: YYYY-MM-DD.

Responses
200

Success

get/promise-to-pay-plans
Response samples
application/json
{
  • "status": 0,
  • "total": 0,
  • "count": 0,
  • "nextUrl": "string",
  • "previousUrl": "string",
  • "data": [
    ]
}

Create Promise to Pay Plan

Creates a new Promise to Pay 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.

Request Body schema: application/json

Promise to pay plan post

previewMode
boolean
Default: false

In previewMode=true, the Promise to Pay Plan and corresponding Promise Period Objects will be returned for preview without committing the object to database

externalId
string (ExternalId)

A lender's identifier for a promise to 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.

startDate
string <date> (RequestStartDate)

The start date of the promise to pay plan. If startDate is not provided upon promise to pay plan creation, the system will use the created date (i.e. “today”) as the startDate. If startDate is provided, it must be a date in the future. Notes:

  • If you are providing a schedule object, you should not pass the startDate. In case both are provided in the request, a 400 Bad Request error will be returned.
  • If Peach's system creates the schedule based on frequency,specificDays and duration passed, the system will schedule Promise to Pay Periods starting after the startDate.
frequency
string

The agreed payment frequency of the promise. Peach's system will use the desired frequency to create promise to pay period(s) so the lender can monitor progress against promised payment dates and amount paid. weekly, everyTwoWeeks, twiceMonthly, and monthly options create multiple promise to pay periods, according to the duration. singleTerm creates a promise with a single period and desired duration of X calendar days or a specific date that should be passed in specificDays.

Note:

  • If frequency is passed to the endpoint, ensure that duration and amount are also provided.
  • If you are providing a frequency object, you should not pass the schedule. In case both are provided in the request, a 400 Bad Request error will be returned.
Enum: "weekly" "everyTwoWeeks" "twiceMonthly" "monthly" "singleTerm"
Array of (string or null) or integers or null (SpecificDays)

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 number 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].

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.

duration
integer >= 1

The duration of the promise to pay plan as a number of frequency periods. For example: if frequency=weekly and duration=6, the promise will be created with 6 weeks duration and will have 6 periods all with the same amount.

Note:

  • If duration is passed to the endpoint, ensure that frequency and amount are also provided.
  • If you are providing a duration object, you should not pass the schedule. In case both are provided in the request, a 400 Bad Request error will be returned.
amount
number <float> >= 0.01

Amount required to be fulfilled for each period of the promise to pay plan. Peach's system will use the amount provided to trigger any required promise status transitions.

Note:

  • If amount is passed to the endpoint, ensure that frequency and duration are also provided.
  • If you are providing an amount object, you should not pass the schedule. In case both are provided in the request, a 400 Bad Request error will be returned.
Array of objects

To create a custom promise to pay schedule with varying amounts or irregular periods, pass a schedule when creating the promise to pay plan. Note: Either schedule object or schedule descriptor attributes (startDate, frequency, specificDays , 'duration' and 'amount') can be passed to create a promise to pay plan. In case both are provided in the request, a 400 Bad Request error will be returned.

caseId
string or null

The ID of the case associated with the promise to pay plan.

Responses
200

Promise to pay plan

201

Promise to pay plan

post/people/{personId}/loans/{loanId}/promise-to-pay-plans
Request samples
application/json
{
  • "previewMode": false,
  • "externalId": "string",
  • "startDate": "2019-08-24",
  • "frequency": "weekly",
  • "specificDays": [
    ],
  • "duration": 1,
  • "amount": 0.01,
  • "schedule": [
    ],
  • "caseId": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get Promise to Pay Plans for a Loan

Returns Promise to Pay Plans for a given 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
Array of strings

Filter by status. Possible values are scheduled, active, kept, broken, canceled.

Items Enum: "scheduled" "active" "kept" "broken" "canceled"
isOverdue
boolean

Filter by overdue status. Possible values are true, false.

Enum: true false
startDateAfter
string <date>

Filter by start date after. Format: YYYY-MM-DD.

endDateBefore
string <date>

Filter by end date before. Format: YYYY-MM-DD.

Responses
200

Success

get/people/{personId}/loans/{loanId}/promise-to-pay-plans
Response samples
application/json
{
  • "status": 0,
  • "total": 0,
  • "count": 0,
  • "nextUrl": "string",
  • "previousUrl": "string",
  • "data": [
    ]
}

Get Promise to Pay Plan

Returns a Promise to Pay Plan for a given 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.

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

The identifier of a promise to pay plan.

Responses
200

Promise to pay plan

get/people/{personId}/loans/{loanId}/promise-to-pay-plans/{promiseToPayPlanId}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Cancel Promise to Pay Plan

Cancels a Promise to Pay 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.

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

The identifier of a promise to pay plan.

Request Body schema: application/json

Promise to pay plan cancel

cancellationReason
required
string

The reason for canceling the promise to pay plan.

canceledByUser - Promise to pay plan was canceled by an agent or borrower. loanChargedOff - loan was charged off during the promise period. loanAccelerated - loan was accelerated during the promise period. otherPromisePlanOffered - another promise plan was offered. other - for any other reason requiring cancellation.

Enum: "canceledByUser" "loanChargedOff" "loanAccelerated" "otherPromisePlanOffered" "other"
reasonDetails
string or null

Additional details about the reason for canceling the promise to pay plan.

Responses
200

Promise to pay plan

put/people/{personId}/loans/{loanId}/promise-to-pay-plans/{promiseToPayPlanId}/cancel
Request samples
application/json
{
  • "cancellationReason": "canceledByUser",
  • "reasonDetails": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Evaluate Promise to Pay Plan

Evaluates a Promise to Pay Plan and updates the status and isOverdue of the Promise to Pay 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.

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

The identifier of a promise to pay plan.

Responses
200

Promise to pay plan

put/people/{personId}/loans/{loanId}/promise-to-pay-plans/{promiseToPayPlanId}/evaluate
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Evaluate Promise to Pay Plan, does not require personId

Evaluates a Promise to Pay Plan and updates the status and isOverdue of the Promise to Pay Plan.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
companyId
required
string

The unique company 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.

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

The identifier of a promise to pay plan.

Responses
200

Promise to pay plan

put/companies/{companyId}/loans/{loanId}/promise-to-pay-plans/{promiseToPayPlanId}/evaluate
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Request sandbox access