Transactions

This object represents payments and credits. Payments represent real money that were paid back by borrowers. Credits are adjustments made on a loan. Credits lower balances similar to payments. Credits can be issued by customer service representatives or supervisors.

Create transaction

Create a transaction. Permissions required depend on the object type passed:

type permission
One Time Payment transaction:create.onetimepayment
Service Credit transaction:create.servicecredit
Down Payment transaction:create.downpayment
Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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^ext-|^[A-Z]{2}-[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
sync
boolean
Default: false

Make the process synchronous.

Request Body schema: application/json
One of:
type
required
string
Value: "oneTime"
drawId
string

The draw identifier. If provided, the system will attempt to apply the payment to the specified draw. Any excess will be applied to the rest of LOC/Draws based on the multi-waterfall that is defined for the line of credit type.

isExternal
boolean

A transaction marked isExternal=true is for record purposes only. A transaction with an external paymentInstrument is automatically marked external.

externalId
string or null

A lender's identifier for a resource.

After the resource is successfully created, a lender can use the Peach assigned ID OR the externalId identifiers to fetch the resource.

Fetching with externalId:

To fetch a resource using an externalId, you MUST use the prefix ext- in the URL.

For example, a loan with an external identifier of ABCDE would be referenced like /api/people/BO-FAKE-IDNT/loans/ext-ABCDE.

Creating with externalId:

To create a resource with an external identifer, you MUST NOT use the prefix ext-.

For example, if the external identifier should be ABCDE, then pass { externalId: "ACBCE", ... } in the request body.

status
string

The transaction status. May only be passed when isExternal=true.

External transactions can be created in: scheduled, initiated, pending, succeeded, or failed. External transactions are applied to the loan balance immediately when created with status initiated, pending, or succeeded. Otherwise, they will be applied the first time they are updated to one of these statuses.

scheduled - payment or credit was scheduled for a future date that has not arrived yet. The payment has not applied to a loan yet.

initiated - payment was initiated and sent to a payment processor. The payment is applied to a loan. This status is used normally for ACH.

pending - payment was acknowledged by the payment processor and is being processed. For ACH the payment can be in pending status for a few days.

succeeded - payment was completed successfully.

failed - payment failed and was removed from the loan effective as of initiated, pending or succeeded status effective date. The system replays the loan as if the payment never happened. It will also re-accrue interest since then.

inDispute - payment is in dispute (typically because of chargeback). The payment is removed from the loan effective as of initiated, pending or succeeded status effective date. The system replays the loan as if the payment never happened. It will also re-accrue interest since then. Disputed payment can be for partial amount.

canceled - payment or credit was canceled. Payment can be canceled only if the current status is scheduled.

chargeback - payment was disputed and ruled against the lender. The payment was returned to the original payment instrument. Chargeback payment can be for partial amount.

Enum: "scheduled" "initiated" "pending" "succeeded" "failed" "canceled" "inDispute" "chargeback"
failureReason
string

The transaction failure reason. This value is ignored except when creating an external transaction with status=failed

Enum: "insufficientFunds" "chargeback" "accountClosed" "invalidAccount" "unknownReason" "invalidCvv" "invalidExpirationDate" "avsFailed" "networkError" "cardDeclined" "accountFrozen" "deceased" "invalidRouting" "paymentStopped" "incorrectNumber" "fraudulent" "unauthorizedDebit"
paymentInstrumentId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Peach's unique or lender's external identifier.

amount
required
number <float> >= 0

The amount of the payment.

scheduledDate
string <date>

If provided must be a date in the future.

enablePrepayments
boolean
Default: false

true if the borrower opts to apply any overpayment amount to prepayment of future obligations. false if the borrower opts to apply overpayments to the current obligation.

caseId
string

An identifier for an existing case.

Responses
201

Created

408

Request Timeout

post/people/{personId}/loans/{loanId}/transactions
Request samples
application/json
{
  • "type": "oneTime",
  • "drawId": "string",
  • "isExternal": true,
  • "externalId": "string",
  • "status": "scheduled",
  • "failureReason": "insufficientFunds",
  • "paymentInstrumentId": "string",
  • "amount": 0,
  • "scheduledDate": "2019-08-24",
  • "enablePrepayments": false,
  • "caseId": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "processingComplete": true,
  • "data": {
    }
}

Get transactions

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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^ext-|^[A-Z]{2}-[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
Items Enum: "scheduled" "initiated" "pending" "succeeded" "failed" "canceled" "inDispute" "chargeback"
paymentInstrumentId
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

The payment instrument identifier.

isExternal
boolean

Fetch entities that are marked external.

isVirtual
boolean
toEffectiveDate
string <date>

Last day for which an object's effective date must match

fromEffectiveDate
string <date>

First day for which an object's effective date must match

limit
integer [ 1 .. 100 ]
Default: 25

The maximum count of results to retrieve.

startingAfter
string

Return results starting after the provided object identifier.

endingBefore
string

Return results ending before the provided object identifier.

Responses
200

Collection of Transactions

get/people/{personId}/loans/{loanId}/transactions
Response samples
application/json
{
  • "total": 0,
  • "count": 0,
  • "nextUrl": "string",
  • "previousUrl": "string",
  • "data": [
    ]
}

Get transaction by ID

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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^ext-|^[A-Z]{2}-[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.

transactionId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Transaction Id. Can be Peach or lender's external identifier.

Responses
200

success

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

Update transaction

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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^ext-|^[A-Z]{2}-[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.

transactionId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Transaction Id. Can be Peach or lender's external identifier.

query Parameters
sync
boolean
Default: false

Make the process synchronous.

Request Body schema: application/json
externalId
string or null

A lender's identifier for a transaction.

isExternal
boolean

A transaction marked isExternal=true is for record purposes only. A transaction with an external paymentInstrument is automatically marked external.

isVirtual
boolean

A transaction marked isVirtual=true is not a real transaction, but represents a part of another transaction. This is used to store the principal/interest split on draws in Line of Credits as well as splits between multiple installment loans that were applied as a single payment.

status
string

The transaction status.

scheduled - payment or credit was scheduled for a future date that has not arrived yet. The payment has not applied to a loan yet.

initiated - payment was initiated and sent to a payment processor. The payment is applied to a loan. This status is used normally for ACH.

pending - payment was acknowledged by the payment processor and is being processed. For ACH the payment can be in pending status for a few days.

succeeded - payment was completed successfully.

failed - payment failed and was removed from the loan effective as of initiated, pending or succeeded status effective date. The system replays the loan as if the payment never happened. It will also re-accrue interest since then.

inDispute - payment is in dispute (typically because of chargeback). The payment is removed from the loan effective as of initiated, pending or succeeded status effective date. The system replays the loan as if the payment never happened. It will also re-accrue interest since then. Disputed payment can be for partial amount.

canceled - payment or credit was canceled. Payment can be canceled only if the current status is scheduled.

chargeback - payment was disputed and ruled against the lender. The payment was returned to the original payment instrument. Chargeback payment can be for partial amount.

Enum: "scheduled" "initiated" "pending" "succeeded" "failed" "canceled" "inDispute" "chargeback"
object

Timestamps of the transaction statuses.

actualAmount
number <float>

The actual amount that was processed. The system never debits more than the loan outstanding balance.

scheduledAmount
number <float>

The scheduled amount. The actual amount charged can be lower from the scheduled amount. It cannot be higher.

paidPrincipalAmount
number <float>

The paid amount allocated to principal

paidInterestAmount
number <float>

The paid amount allocated to interest

paidFeesAmount
number <float>

The paid amount allocated to fees

paidOverAmount
number <float>

Stores any excess amount that was not allocated to principal, interest or fees.

object

Chargeback details.

processingFeeAmount
number

Transaction processing fees that are charged by a payment processor.

processingFeeType
string

Describes whether the processing fees are net or gross. If it is a net fee, the amount of the fee is deducted from the amount of the transaction 'en route'. If it is a gross fee, the amount of the fee is charged by the processor at the end the month.

Enum: "net" "gross"
processorTransactionId
string
processorReversalId
string
processorReconciliationId
string
avsResult
string = 1 characters
failureReason
string

The transaction failure reason.

Enum: "insufficientFunds" "chargeback" "accountClosed" "invalidAccount" "unknownReason" "invalidCvv" "invalidExpirationDate" "avsFailed" "networkError" "cardDeclined" "accountFrozen" "deceased" "invalidRouting" "paymentStopped" "incorrectNumber" "fraudulent" "unauthorizedDebit"
processorFailureReason
string

The raw failure reason returned by the payment processor.

processorFailureDetails
any

The error details returned by the payment processor.

achReturnCode
string <= 5 characters

The ACH return code indicating the reason the transaction failed.

reversedByTransactionId
string

Peach identifier of the transaction that reverses this one.

reversedByTransactionExternalId
string^ext-|^\d+$

Lender's external identifier of the transaction that reverses this one.

parentTransactionId
string

The ID of the real transactions that created this virtual transaction. Only relevant for virtual transactions.

autopayPlanId
string

Peach identifier of the autopay plan.

autopayPaymentIds
Array of integers

Peach identifiers of the autopay expected payments.

cancelReason
string or null
Default: "canceledByUser"

Why the transaction was canceled.

Enum: "invalidPaymentMethod" "paymentMethodRemoved" "tooManyFailedAttempts" "loanFrozen" "loanAccelerated" "loanChargedOff" "loanPaidOff" "canceledByUser" "loanTermsChanged"
enablePrepayments
boolean

true if the borrower opts to apply any overpayment amount to prepayment of future obligations. false if the borrower opts to apply overpayments to the current obligation.

Responses
200

Updated

408

Request Timeout

put/people/{personId}/loans/{loanId}/transactions/{transactionId}
Request samples
application/json
{
  • "externalId": "string",
  • "isExternal": true,
  • "isVirtual": true,
  • "status": "scheduled",
  • "timestamps": {
    },
  • "transactionType": "payment",
  • "paymentDetails": {
    },
  • "actualAmount": 0,
  • "scheduledAmount": 0,
  • "paidPrincipalAmount": 0,
  • "paidInterestAmount": 0,
  • "paidFeesAmount": 0,
  • "paidOverAmount": 0,
  • "currency": "string",
  • "serviceCreditDetails": {
    },
  • "chargebackDetails": {
    },
  • "processingFeeAmount": 0,
  • "processingFeeType": "net",
  • "processorTransactionId": "string",
  • "processorReversalId": "string",
  • "processorReconciliationId": "string",
  • "avsResult": "s",
  • "failureReason": "insufficientFunds",
  • "processorFailureReason": "string",
  • "processorFailureDetails": null,
  • "achReturnCode": "strin",
  • "reversedByTransactionId": "string",
  • "reversedByTransactionExternalId": "string",
  • "parentTransactionId": "string",
  • "autopayPlanId": "string",
  • "autopayPaymentIds": [
    ],
  • "cancelReason": "invalidPaymentMethod",
  • "enablePrepayments": true
}

Cancel transaction

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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^ext-|^[A-Z]{2}-[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.

transactionId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Transaction Id. Can be Peach or lender's external identifier.

query Parameters
cancelReason
string or null
Default: "canceledByUser"

Why the transaction was canceled.

Enum: "invalidPaymentMethod" "paymentMethodRemoved" "tooManyFailedAttempts" "loanFrozen" "loanAccelerated" "loanChargedOff" "loanPaidOff" "canceledByUser" "loanTermsChanged"
Responses
204

canceled

post/people/{personId}/loans/{loanId}/transactions/{transactionId}/cancel

Reverse transaction

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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^ext-|^[A-Z]{2}-[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.

transactionId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Transaction Id. Can be Peach or lender's external identifier.

query Parameters
sync
boolean
Default: false

Make the process synchronous.

Request Body schema: application/json
caseId
string

The identifier of an existing case.

Responses
201

A Transaction

408

Request Timeout

423

Locked

post/people/{personId}/loans/{loanId}/transactions/{transactionId}/reverse
Request samples
application/json
{
  • "caseId": "string"
}
Response samples
application/json
{
  • "status": 0,
  • "message": "string",
  • "data": {
    }
}

Backdate transaction

Backdate a transaction. Can only be applied to transactions with status=succeeded. Can be applied to payments or service credits.

Securityoauth2 or bearerAuth or apiKeyHeader
Request
path Parameters
personId
required
string^ext-|^[A-Z]{2}-[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^ext-|^[A-Z]{2}-[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.

transactionId
required
string^ext-|^[A-Z]{2}-[A-Z0-9]+-[A-Z0-9]+|^\d+$

Transaction Id. Can be Peach or lender's external identifier.

query Parameters
sync
boolean
Default: false

Make the process synchronous.

Request Body schema: application/json
effectiveDate
string <date>

New effective date for the transaction.

caseId
string

The identifier of an existing case.

Responses
200

Backdated

204

Backdated

408

Request Timeout

423

Locked

post/people/{personId}/loans/{loanId}/transactions/{transactionId}/backdate
Request samples
application/json
{
  • "effectiveDate": "2019-08-24",
  • "caseId": "string"
}
Response samples
application/json
{
  • "message": "Loan is locked for updates. Please try again."
}