# 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` |

Once a loan has been onboarded to Peach's platform, valid loan statuses for each transaction type are as follows:
| type | valid loan statuses |
|  --- | --- |
| One Time Payment | `active`, `accelerated`, or `chargedOff`* |
| Service Credit | `active`, `accelerated`, or `chargedOff`* |
| Down Payment | `active` |

*=`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:
| type | valid loan statuses |
|  --- | --- |
| One Time Payment | `originated` |
| Service Credit | `originated` |
| Down Payment | `active` |

Endpoint: POST /people/{personId}/loans/{loanId}/transactions
Version: 2025-03-26
Security: oauth2, bearerAuth, apiKeyHeader

## Path parameters:

  - `personId` (string, required)
    A Borrower's unique identifier, tied to a person or a business. Can be Peach or a lender's external identifier.

  - `loanId` (string, required)
    The unique identifier of the Loan we wish to retrieve. Can be
Peach or lender's external identifier.

## Query parameters:

  - `sync` (boolean)
    Make the process synchronous.

## Request fields (application/json):

  - `consentDocumentId` (string)
    The document ID of a one-time payment consent given by the
borrower to debit their payment instrument.  The document is
stored in the HTML format and contains the disclosure shown to
the borrower at the time of the payment.  Required if
`previewMode=false` and Peach is processing payments (aka
`isExternal=false`) on behalf of the lender.

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

  - `effectiveDate` (string)
    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.

  - `effectiveTimeOfDay` (object)
    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.

  - `effectiveTimeOfDay.hour` (integer, required)
    The hour. Value range is 0-23. 0=Midnight...23=11 PM.

  - `effectiveTimeOfDay.minute` (integer, required)
    The minute. Value range is 0-59.

  - `effectiveTimeOfDay.second` (integer)
    The second. Value range is 0-59.

  - `enablePrepayments` (boolean)
    **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.

  - `holdDaysEndDate` (string)
    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)

  - `isExternal` (boolean)
    A transaction marked `isExternal=true` is for record purposes only. A transaction with an external `paymentInstrument` is automatically marked external.

  - `scheduledDate` (string)
    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.

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

  - `caseId` (string)
    An identifier for an existing case.

  - `serviceCreditType` (string, required)
    Enum: "serviceAgent", "serviceSupervisor", "settlementOfDebt", "settlementOfDebtNoLoss", "balanceTransfer", "rewards", "fraud", "badDebt", "bankruptcy", "deceased", "usuryCap"

  - `effectiveDate` (string)
    The effective date of the transaction in the product timezone.
On active (non-migrating) loans, use with `effectiveTimeOfDay` and without `scheduledDate` to create and
backdate in one call (`isExternal=true`, status `succeeded` or `pending`; date must be today or in the past).
Triggers replay; use `sync=true` to wait for completion (408 on timeout). `effectiveTimeOfDay` is required when
this field is passed.
On migrating loans (`prepMigration`), used during migration ingest only.

  - `scheduledDate` (string)
    If provided must be a date in the future.

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

## Response 201 fields (application/json):

  - `message` (string)
    Description of the server action or error.

  - `status` (integer)
    HTTP status code.

  - `data` (object)

  - `data.autopayPaymentIds` (array)
    Peach identifiers of the autopay expected payments.

  - `data.autopayPlanId` (string)
    Peach identifier of the autopay plan.

  - `data.consentDocumentId` (string)
    The document ID of a one-time payment consent given by the
borrower to debit their payment instrument.  The document is
stored in the HTML format and contains the disclosure shown to
the borrower at the time of the payment.  Required if
`previewMode=false` and Peach is processing payments (aka
`isExternal=false`) on behalf of the lender.

  - `data.drawId` (string)
    The draw identifier for the transaction.

  - `data.enablePrepayments` (boolean)
    **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.

  - `data.evidenceDocumentId` (string)
    The document ID of a one-time payment consent screenshot
captured when a borrower made the payment.  Only applicable when
Peach App is used and company's
`config.evidence.captureScreenshot=true`.

  - `data.initiatingBorrowerId` (string)
    The ID of the borrower who initiated the transaction.

  - `data.isExternal` (any)
    A transaction marked `isExternal=true` is for record purposes only. A transaction with
an external `paymentInstrument` is automatically marked external.

  - `data.isVirtual` (any)
    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.

  - `data.loanId` (string)
    The unique identifier of the Loan.

  - `data.mainBorrowerId` (string)
    The Peach identifier for the main borrower on the loan.

  - `data.paidFeesAmount` (any)
    The paid rounded amount allocated to fees

  - `data.paidInterestAmount` (any)
    The paid rounded amount allocated to interest

  - `data.paidOverAmount` (any)
    Stores any excess rounded amount that was not allocated to principal, interest or fees.

  - `data.paidPrincipalAmount` (any)
    The paid rounded amount allocated to principal

  - `data.unroundedPaidFeesAmount` (number)
    The paid unrounded amount allocated to fees

  - `data.unroundedPaidInterestAmount` (number)
    The paid unrounded amount allocated to interest

  - `data.unroundedPaidOverAmount` (number)
    Stores any excess unrounded amount that was not allocated to principal, interest or fees.

  - `data.unroundedPaidPrincipalAmount` (number)
    The paid unrounded amount allocated to principal

## Response 423 fields (application/json):

  - `message` (string)
    Enum: "Loan is locked for updates. Please try again.", "Loan is locked for updates. Please check back again in a few minutes.", "Previous purchase is processing."