You are viewing the latest API docs through the legacy docs viewer. The modern viewer can be found here: https://docs.peachfinance.com/api-docs.
Peach Finance

Installment Refunds

This object represents refunds. Various situations require full or partial refunds of a loan. Depending on the refund amount and whether the borrower has made payments, a refund may also trigger a reimbursement to the borrower.

Create refund

The refund endpoint will execute a full or partial refund according to the refundAmount specified. A full refund is equal to the amountFinancedAtOrigination. An atFaultParty must also be specified, in order to trigger the corresponding accounting entries related to billing for the refund.

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
refundDate
string <date>

This attribute can be set only during the migration process of loans from another system to Peach. Any value passed for active loans will be ignored.

The refund effective date in the product timezone. If not provided, the refund will be recorded in the ledger with an effective timestamp of the Create refund call.

refundAmount
required
number <float> > 0

The refund amount. The maximum eligible refund amount is the amountFinancedAtOrigination of the loan. The refund is applied against the principal of the loan.

atFaultParty
required
string

The party at fault for the refund. Mainly used for ledger/accounting.

If loanOwner, the lender is billed for the entire refund, and paid interest and fees are refunded to the borrower.

If loanServicer, the servicer is billed for the entire refund, and paid interest and fees are refunded to the borrower.

If merchant, the merchant is billed for the entire refund, and paid interest and fees are refunded to the borrower.

If borrower, the merchant is billed for the entire refund, and the borrower receives no refund for paid interest and fees.

Enum: "loanOwner" "loanServicer" "merchant" "borrower"
caseId
string

The case identifier.

sendNotice
boolean
Default: true

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

object (RefundDetails)

The details of refund.

Responses
200

Loan Refund

post/people/{personId}/loans/{loanId}/refunds
Request samples
application/json
{
  • "refundDate": "2019-08-24",
  • "refundAmount": 0,
  • "atFaultParty": "loanOwner",
  • "caseId": "string",
  • "sendNotice": true,
  • "refundDetails": {
    }
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Get refunds

Returns a list of all prior refunds for the loan, as well as the remaining eligible refund amount.

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.

Responses
200

Loan Refund

get/people/{personId}/loans/{loanId}/refunds
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Cancel refund

Cancel a refund.

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.

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

The loan refund identifier.

Request Body schema: application/json
required
cancellationReason
string

Reason the refund was canceled.

Enum: "wrongAmountOrDetails" "processingError" "other"
cancellationReasonDetails
string

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

caseId
string

An identifier for an existing case.

Responses
200

Loan Refund

post/people/{personId}/loans/{loanId}/refunds/{loanRefundId}/cancel
Request samples
application/json
{
  • "cancellationReason": "wrongAmountOrDetails",
  • "cancellationReasonDetails": "string",
  • "caseId": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Create refund v2

The refund endpoint will execute a full or partial refund according to the refundAmount specified. The total of all refunds cannot exceed the amountFinanced (or principalAmount) passed at origination.

A refund is applied in the following way:

  • The system first depletes any non-due principal. This amount will be stored as refundDetails.refundNonDuePrincipalAmount.
  • If any refund amount is left to apply, the system will create a transaction of type service credit and serviceCreditType=refund. This transaction will be applied on the loan using the "payment waterfall". This amount will be stored as refundDetails.refundTransactionAmount.
  • After the system applies the serviceCreditType=refund, if there is any remaining unapplied refund amount, it will be recorded as credit to the borrower (also called reimbursementAmount or amount owed to borrower.)
  • The system will replay the loan from the refundDate.

Please consider the following before creating refunds:

  • If you want to fully refund the loan including interest and fees, pass the following:
    • refundDate equals the activation date.
    • refundAmount equals the amount financed.
    • isRefundOriginationFees, isRefundLateFees and isRefundOtherFees set to true.
    • isRefundMDR and isRefundDownPayment - set these attributes depending on your policy.
  • If you want to partially refund the loan with prorated interest and/or fees, set the following. Prorated interest means the system will lower the principal from the activation date and re-accrue interest.
    • refundDate equals the activation date.
    • refundAmount equals a partial refund amount.
    • isRefundOriginationFees, isRefundLateFees and isRefundOtherFees - set these values depending on your policy.
    • isRefundMDR - set this attribute depending on your policy.
    • isRefundDownPayment - set to false. To remind: this attribute can be true only for a full refund.
  • If you want to partially refund the loan without prorating interest and/or fees prior the refund date, set the following:
    • refundDate equals an effective date of the refund (or keep empty to indicate "today").
    • refundAmount equals a partial refund amount.
    • isRefundOriginationFees, isRefundLateFees and isRefundOtherFees set to false.
    • isRefundMDR - set to false. To remind: this attribute can be true only if refundDate equals the activation date.
    • isRefundDownPayment - set to false. To remind: this attribute can be true only for a full refund.
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 or null non-empty

A lender's identifier for the refund.

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.

refundDate
string <date>

The refund effective date in the product timezone. The refundDate can be any date between the activation date and the current date. If not provided, the refund will be recorded in the ledger with an effective timestamp of the Create refund call.

To make the refund effective from the beginning of the loan, please pass the activation date and don't pass refundTimeOfDay. In this case, the system will create the refund immediately after the activation.

object
Default: {"hour":12,"minute":1,"second":0}

The effective time of day on refundDate in the product timezone. The default value is 12:01:00 AM in the product timezone.

Note: for migration only, the value must be after 2AM in the product timezone.

refundAmount
required
number <float> > 0

The refund amount. The maximum eligible refund amount is the amountFinancedAtOrigination of the loan. The refund is applied against the principal of the loan.

atFaultParty
required
string

The party at fault for the refund. Mainly used for ledger/accounting.

If loanOwner, the lender is billed (on accounting level) for the refund.

If loanServicer, the servicer is billed (on accounting level) for the refund.

If merchant, the merchant is billed (on accounting level) for the refund.

If borrower, the merchant is billed (on accounting level) for the refund.

Enum: "loanOwner" "loanServicer" "merchant" "borrower"
caseId
string

The case identifier.

isRefundOriginationFees
boolean
Default: false

If true, the system will forego origination fee. Only applicable if the refundDate is the loan activation date. If false, the system will not do anything with the origination fee as part of the refund.

Note: refunding the origination fee is different from calling "Update origination fee" endpoint. When the origination fee is refunded, the system books the origination fees amount and move the entries to "foregone" immediately after. When the origination fee amount is updated via Update origination fee, the system changes the origination fee amount, re-books the fee from the activation date and replays the loan.

isRefundLateFees
boolean
Default: false

If true, the system will cancel any late fees charged after refundDate + refundTimeOfDay. If false, the system will not cancel any late fees as part of the refund.

isRefundOtherFees
boolean
Default: false

If true, the system will cancel any dynamic fees (except for late fees and fees listed in the otherFeesExceptionList) charged after refundDate + refundTimeOfDay.

If false, the system will not cancel any dynamic fees (other than late fees and fees listed in the otherFeesExceptionList) as part of the refund.

Note: if an account ends in paidOff status after the refund is applied, any service fees after the payoff date will be canceled, regardless of the isRefundOtherFees value.

feesExceptionList
Array of strings
Default: []

A list of the dynamic fees (aka LoanFee) identifiers that will not be refunded/canceled. The identifiers can be Peach or lender's external identifiers. This allows lenders to exclude specific fees from being refunded. For example:

  • isRefundLateFees=true
  • feesExceptionList=[LF-K98P-NM3E] The system will refund/cancel all late fees except for LF-K98P-NM3E.
isRefundDownPayment
boolean
Default: false

If true, the system will refund the down payment amount (assuming the down payment was paid by the borrower). Only applicable if refunded for a full amount.

isRefundMDR
boolean
Default: false

If true, the system will record the prorated MDR amount to the merchant within the ledger. Peach is not involved in the settlement process with merchants, and will only record amounts in the ledger. Only applicable if refundDate equals the activation date.

sendNotice
boolean
Default: true

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

object (RefundDetailsV2)

The details of how a refund was applied:

  • The system will first deplete any non-due principal. This amount will be stored as refundNonDuePrincipalAmount.
  • If any refund amount is left to apply, the system will create a transaction of type serviceCredit and serviceCreditType=refund. This transaction will be applied on the Draw level first and any leftover amount will be applied on the LOC level (based on the loan type waterfall configuration for payments). This amount will be stored as refundTransactionAmount.
  • Any unapplied refund amount will be recorded as credit to the borrower (also called reimbursementAmount.)
Responses
200

Loan Refund

post/people/{personId}/loans/{loanId}/refunds-v2
Request samples
application/json
{
  • "externalId": "string",
  • "refundDate": "2019-08-24",
  • "refundTimeOfDay": {
    },
  • "refundAmount": 0,
  • "atFaultParty": "loanOwner",
  • "caseId": "string",
  • "isRefundOriginationFees": false,
  • "isRefundLateFees": false,
  • "isRefundOtherFees": false,
  • "feesExceptionList": [ ],
  • "isRefundDownPayment": false,
  • "isRefundMDR": false,
  • "sendNotice": true,
  • "refundDetails": {
    }
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}
➔ Next to Line of Credit Draws