Skip to content
/
Create refund v2

Create refund v2

Request

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.
Security
oauth2(Required scopes: loan.refund:create) or bearerAuth or apiKeyHeader
Path
personIdstring(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-onlyrequired

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

loanIdstring(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-onlyrequired

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

Bodyapplication/jsonrequired
atFaultPartystringrequired

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

The case identifier.

externalIdstring 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.

feesExceptionListArray of strings

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.
Default:[]
isRefundDownPaymentboolean

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.

Default:false
isRefundLateFeesboolean

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.

Default:false
isRefundMDRboolean

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.

Default:false
isRefundOriginationFeesboolean

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.

Default:false
isRefundOtherFeesboolean

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.

Default:false
refundAmountnumber, (float), > 0required

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

refundDatestring, (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.

refundDetailsobject(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.)
refundTimeOfDayobject(TimeOfDay)write-only

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.

Default:{"hour":12,"minute":1,"second":0}
sendNoticebooleanwrite-only

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

Default:true
POST
/people/{personId}/loans/{loanId}/refunds-v2
curl -i -X POST \
  'https://sandboxapi.peach.finance/api/people/{personId}/loans/{loanId}/refunds-v2' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "atFaultParty": "loanOwner",
    "caseId": "string",
    "externalId": "string",
    "feesExceptionList": [],
    "isRefundDownPayment": false,
    "isRefundLateFees": false,
    "isRefundMDR": false,
    "isRefundOriginationFees": false,
    "isRefundOtherFees": false,
    "refundAmount": 1,
    "refundDate": "2019-08-24",
    "refundDetails": {
      "description": "Refund",
      "merchantId": "string",
      "merchantName": "string",
      "metadata": {}
    },
    "refundTimeOfDay": {
      "hour": 12,
      "minute": 1,
      "second": 0
    },
    "sendNotice": true
  }'

Responses

Loan Refund

Bodyapplication/json
messagestring

Description of the server action or error.

statusinteger

HTTP status code.

dataobject(LoanRefundV2)
Response
{
  "message": "string",
  "status": 0,
  "data": {
    "atFaultParty": "loanOwner",
    "canceledBy": { … },
    "cancellationCaseId": "string",
    "cancellationReason": "wrongAmountOrDetails",
    "cancellationReasonDetails": "string",
    "caseId": "string",
    "createdBy": { … },
    "externalId": "string",
    "feesExceptionList": [],
    "id": "string",
    "isFullRefund": true,
    "isRefundDownPayment": false,
    "isRefundLateFees": false,
    "isRefundMDR": false,
    "isRefundOriginationFees": false,
    "isRefundOtherFees": false,
    "originalAmount": 0.1,
    "refundAmount": 1,
    "refundDate": "2019-08-24",
    "refundDetails": { … },
    "status": "settled",
    "timestamps": { … }
  }
}