Skip to content
/
Create transaction

Create transaction

Request

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

typepermission
One Time Paymenttransaction:create.onetimepayment
Service Credittransaction:create.servicecredit
Down Paymenttransaction:create.downpayment

Once a loan has been onboarded to Peach's platform, valid loan statuses for each transaction type are as follows:

typevalid loan statuses
One Time Paymentactive, accelerated, or chargedOff*
Service Creditactive, accelerated, or chargedOff*
Down Paymentactive

*=chargedOff is only valid when the loan type configuration paymentAllowedWhenChargedOff is true.

During migration while a loan is in prepMigration, valid loan statuses for each transaction type are as follows:

typevalid loan statuses
One Time Paymentoriginated
Service Creditoriginated
Down Paymentactive
Security
oauth2(Required scopes: transaction: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.

Query
syncboolean

Make the process synchronous.

Default:false
Bodyapplication/jsonrequired
One of:
amountnumber, (float), >= 0write-onlyrequired

The amount of the payment.

customDisplayNamestring or null

A friendly description of the transaction. If provided, this value will be displayed in Peach UI/App and Statements (or can be used by lender in their App). If the value is not provided, the Peach UI/App and Statements logic will render the transaction name based on type and status. Make sure you provide value that makes sense to the borrower. This is NOT what the borrower will see in their online bank or card account.

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

Peach's unique or lender's external identifier.

externalIdstring or null, <= 200 characters(externalId)

A lender's identifier for a transaction.

failureReasonstring

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"
metaDataobject or null(TransactionMetaData)

Store any type of key/value pairs in the form of a JSON dictionary.

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

The payment instrument identifier that was charged.

typestringwrite-onlyrequired
Value:"oneTime"
consentDocumentIdstring(AnyId)^ext-|^[A-Z][A-Z0-9]-[A-Z0-9]+-[A-Z0-9]+|^\d+$write-only

Peach's unique or lender's external identifier.

drawIdstring

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.

effectiveDatestring, (date)

The effective date of the transaction in the product timezone.

For active loans (non-migrating), to create and backdate the transaction in one call:

  1. Pass effectiveDate (today or in the past)
  2. Pass effectiveTimeOfDay (see effectiveTimeOfDay for details)
  3. Leave scheduledDate empty
  4. Set isExternal=true
  5. Set status to succeeded or pending

The call triggers replay; use sync=true to wait for completion (408 on timeout)

  • Note: succeededAt will equal createdAt, while appliedAt and pendingAt will equal effectiveDate + effectiveTimeOfDay
  • The transaction will appear on the next day's loan tape (relative to the API call date in the product timezone)

For migrating loans (prepMigration), the attribute is used during migration ingest only.

effectiveTimeOfDayobject(TimeOfDay)write-only

The effective time of day on effectiveDate in the product timezone. Required if effectiveDate is passed. For active loans with external payments, required together with effectiveDate for single-call backdating.

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

enablePrepaymentsboolean

DEPRECATED ATTRIBUTE 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.

If this field is not passed, we reference the allowPrepayments configuration on the loan type.

holdDaysEndDatestring or null, (date)(HoldDaysEndDate)

Allows lenders to configure the openToBuyAmount calculation. Peach's system will not include the transaction in the openToBuyAmount calculation until this date (in the product timezone). For example, if a transaction's holdDaysEndDate is tomorrow or later, the transaction will NOT be included in the openToBuyAmount calculation. Setting this value will override loan.paymentHoldDays.numHoldDays and loanType.paymentHoldDays.numHoldDays.

If holdDaysEndDate is not set upon transaction create, the holdDaysEndDate will be calculated based on loan.paymentHoldDays.numHoldDays.

If loan.paymentHoldDays.numHoldDays is not set, holdDaysEndDate will be calculated based on loanType.paymentHoldDays.numHoldDays. This will only apply to borrower payments and is not applicable for other types of transactions (e.g. service credits)

isExternalboolean

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

scheduledDatestring, (date)

This attribute should be used only for transactions that are scheduled in the future. Transactions that should be processed now/today, leave the attribute empty and the system will set appropriate date and timestamp values based on the API call time.

Note: The maximum date you can set is the maximum of either three years after the last expected payment or three years from today.

statusstring(TransactionCreationStatus)

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

An identifier for an existing case.

POST
/people/{personId}/loans/{loanId}/transactions
curl -i -X POST \
  'https://sandboxapi.peach.finance/api/people/{personId}/loans/{loanId}/transactions?sync=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 0,
    "customDisplayName": "string",
    "evidenceDocumentId": "string",
    "externalId": "string",
    "failureReason": "insufficientFunds",
    "metaData": {},
    "paymentInstrumentId": "string",
    "type": "oneTime",
    "consentDocumentId": "string",
    "drawId": "string",
    "effectiveDate": "2019-08-24",
    "effectiveTimeOfDay": {
      "hour": 0,
      "minute": 0,
      "second": 0
    },
    "enablePrepayments": true,
    "holdDaysEndDate": "2019-08-24",
    "isExternal": true,
    "scheduledDate": "2019-08-24",
    "status": "scheduled",
    "caseId": "string"
  }'

Responses

Created

Bodyapplication/json
messagestring

Description of the server action or error.

statusinteger

HTTP status code.

dataobject(Transaction)
Response
{
  "message": "string",
  "status": 0,
  "data": {
    "createdAt": "2019-08-24T14:15:22Z",
    "deletedAt": "2019-08-24T14:15:22Z",
    "id": "string",
    "updatedAt": "2019-08-24T14:15:22Z",
    "externalId": "string",
    "achConfirmed": true,
    "achProcessedSameDay": true,
    "achReturnCode": "strin",
    "achSameDay": true,
    "actualAmount": 0.1,
    "avsResult": "s",
    "cancelLongDescription": "string",
    "cancelReason": "invalidPaymentMethod",
    "cancelShortDescription": "string",
    "createdBy": { … },
    "currency": "string",
    "customDisplayName": "string",
    "failureDescriptionLong": "string",
    "failureDescriptionShort": "string",
    "failureReason": "insufficientFunds",
    "holdDaysEndDate": "2019-08-24",
    "metaData": {},
    "parentTransactionId": "string",
    "paymentDetails": { … },
    "processingFeeAmount": 0,
    "processingFeeType": "net",
    "processorFailureDetails": null,
    "processorFailureReason": "string",
    "processorMerchantId": "string",
    "processorReconciliationId": "string",
    "processorReversalId": "string",
    "processorTransactionId": "string",
    "retryAttempt": 0,
    "retryOriginalTransactionId": "string",
    "reversedAmount": 0.1,
    "reversedByTransactionExternalId": "string",
    "reversedByTransactionId": "string",
    "reversedByTransactionIds": [ … ],
    "reversesTransactionExternalId": "string",
    "reversesTransactionId": "string",
    "scheduledAmount": 0.1,
    "status": "scheduled",
    "timestamps": { … },
    "transactionType": "payment",
    "chargebackAmount": 0.1,
    "chargebackDetails": [ … ],
    "effectiveAmount": 0.1,
    "isExternal": null,
    "isVirtual": null,
    "paidFeesAmount": null,
    "paidInterestAmount": null,
    "paidOverAmount": null,
    "paidPrincipalAmount": null,
    "serviceCreditDetails": { … },
    "autopayPaymentIds": [ … ],
    "autopayPlanId": "string",
    "drawId": "string",
    "enablePrepayments": true,
    "initiatingBorrowerId": "string",
    "loanId": "string",
    "mainBorrowerId": "string",
    "unroundedPaidFeesAmount": 0.1,
    "unroundedPaidInterestAmount": 0.1,
    "unroundedPaidOverAmount": 0.1,
    "unroundedPaidPrincipalAmount": 0.1
  }
}