# Create transaction chargeback

In some cases a borrower might chargeback/dispute a payment that they made in the past. Only transactions in `succeeded` status can be charged back.
If the payment/transaction `isExternal=true`, the caller can post chargeback in two ways:
1. Update status of the transaction to `inDispute` or `chargeback` directly. The chargeback amount defaults to the full amount of the transaction.
The system will create a chargeback object automatically. This option is the easiest way to tell the system about a chargeback.
2. Create chargeback(s) via `Create transaction chargeback` endpoint. This option allows the caller to provide more details about the chargeback.
This option should be used for multiple partial chargebacks. Keep in mind that a transaction can have multiple chargebacks and reversals.

It's important to not mix the options above because it can create edge cases and confusion.
If the payment/transaction is `isExternal=false`, the caller cannot change the transaction status to `inDispute` or `chargeback` nor create chargeback(s)
via `Create transaction chargeback` endpoint. Chargebacks will be received directly from the payment processor.

Endpoint: POST /people/{personId}/loans/{loanId}/transactions/{transactionId}/chargebacks
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.

  - `transactionId` (string, required)
    Transaction ID. Can be Peach or lender's external identifier.

## Query parameters:

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

## Request fields (application/json):

  - `amount` (number)
    The amount of the chargeback. If a value is not provided the system would set the amount to `actualAmount` of the
transaction. If partial chargeback(s) were processed in the past, the caller must provide the amount, otherwise
the call would fail. Amount provided must be less than or equal to the `effectiveAmount` of the transaction at the
time of the call.

  - `caseId` (string)
    The identifier of an existing case.

  - `category` (string)
    The chargeback category as received from the payment processor.

  - `externalCaseNumber` (string)
    The external case number of the chargeback in the payment processor system.

  - `externalId` (string)
    The lender's identifer of the chargeback

  - `reasonCode` (string)
    The reason code as received from the payment processor.

  - `status` (string)
    The status of the chargeback.
- `open` -  the chargeback was opened and is currently in dispute. The system assumes that the chargeback amount is temporarily taken and the
`effectiveAmount` of the transaction is reduced by the chargeback amount. This might trigger a replay.
- `closed` - the chargeback dispute period has closed, and the chargeback has been upheld. This is a terminal state and the chargeback cannot
be reopened. The system assumes that the chargeback amount is permanently taken and the `effectiveAmount` of the transaction is reduced.
- `reversed` - the chargeback dispute period has closed, and the chargeback has been reversed. The system assumes that the chargeback amount
is permanently returned and the `effectiveAmount` of the transaction is increased back. This might trigger a replay.

The chargeback status impacts the transaction status is the following way:
For a transaction with a single chargeback, the chargeback status dictates the transaction status:
- chargeback`status:open` → transaction `status:inDispute`
- chargeback`status:closed` → transaction `status:chargeback`
- chargeback`status:reversed` → transaction `status:succeeded`

For a transaction with multiple chargebacks, the following logic applied:
- Any of the chargebacks in `status:open` → transaction `status:inDispute`
- No chargebacks are in `status:open`, and any chargebacks are in `status:closed` → transaction `status:chargeback`
- All chargebacks are in `status:reversed`→ transaction `status:succeeded`
    Enum: "open", "closed", "reversed"

## Response 201 fields (application/json):

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

  - `status` (integer)
    HTTP status code.

  - `data` (object)

  - `data.amount` (number)
    The amount of the chargeback. Defaults to the `actualAmount` of the transaction.

  - `data.caseId` (string)
    The identifier of an existing case.

  - `data.category` (string)
    The chargeback category as received from the payment processor.

  - `data.description` (string)
    The description of the chargeback as received from the payment processor.

  - `data.externalCaseNumber` (string)
    The external case number of the chargeback in the payment processor system.

  - `data.externalId` (string)
    The lender's identifier of the chargeback.

  - `data.id` (string)
    The identifier of the chargeback.

  - `data.reasonCode` (string)
    The reason code as received from the payment processor.

  - `data.status` (string)
    The status of the chargeback.
- `open` -  the chargeback was opened and is currently in dispute. The system assumes that the chargeback amount is temporarily taken and the
`effectiveAmount` of the transaction is reduced by the chargeback amount. This might trigger a replay.
- `closed` - the chargeback dispute period has closed, and the chargeback has been upheld. This is a terminal state and the chargeback cannot
be reopened. The system assumes that the chargeback amount is permanently taken and the `effectiveAmount` of the transaction is reduced.
- `reversed` - the chargeback dispute period has closed, and the chargeback has been reversed. The system assumes that the chargeback amount
is permanently returned and the `effectiveAmount` of the transaction is increased back. This might trigger a replay.

The chargeback status impacts the transaction status is the following way:
For a transaction with a single chargeback, the chargeback status dictates the transaction status:
- chargeback`status:open` → transaction `status:inDispute`
- chargeback`status:closed` → transaction `status:chargeback`
- chargeback`status:reversed` → transaction `status:succeeded`

For a transaction with multiple chargebacks, the following logic applied:
- Any of the chargebacks in `status:open` → transaction `status:inDispute`
- No chargebacks are in `status:open`, and any chargebacks are in `status:closed` → transaction `status:chargeback`
- All chargebacks are in `status:reversed`→ transaction `status:succeeded`
    Enum: "open", "closed", "reversed"