# Configuring Fees

This guide walks you through real-world scenarios for managing fees in the Peach platform. Using practical examples, you'll learn how to handle common fee management tasks through typical loan servicing situations.

## Overview

Peach supports several types of fees that serve different purposes in the loan lifecycle:

1. **Origination Fees**: One-time fees charged at loan creation with three charging options:
  - Added to first payment
  - Amortized equally across payments
  - Charged separately at origination
2. **Dynamic Fees**: Situational charges like:
  - Late fees
  - NSF (Non-Sufficient Funds) fees
  - Loan modification fees
  - Service fees


Each fee type has specific configuration options for when and how it's charged. Let's explore common scenarios you'll encounter when managing these fees.

## Prerequisites

Before starting, make sure you have:

- Peach account with API access
- API credentials from the Peach Portal
- REST client (like Postman)
- Understanding of your loan type's fee configuration


## Authentication

Include your API key in all requests:


```http
X-API-KEY: YOUR_API_KEY
```

## Common Scenarios

### Scenario 1: Updating an Origination Fee Post-Loan Creation

Let's say you need to adjust an origination fee from $100 to $75 after discovering a processing error.

1. First, check the current fee:



```http
GET /people/{personId}/loans/{loanId}/fees
```

1. Update the origination fee:



```http
PUT /people/{personId}/loans/{loanId}/fees/origination
Content-Type: application/json

{
  "feeAmount": 75.00,
  "caseId": "CS-ADJ1-0001"  // Track the adjustment reason
}
```

The system will:

- Update the fee amount
- Automatically replay the loan from activation
- Recalculate payment allocations
- Adjust statements if necessary


# Charging a Modification Fee

When a borrower requests to defer a due date, you may need to assess a modification fee. Here's how to verify the fee configuration and charge it through the API.

## Step 1: Verify Fee Configuration

First, check the available fee types for your loan:


```http
GET /loan-types/{loanTypeId}/fee-types
Authorization: Bearer YOUR_API_KEY
```

Look for the modification fee configuration in the response. This will tell you:

- The fee amount (if fixed)
- Any constraints or limits on the fee
- Whether it can be applied to specific draws (for lines of credit)


## Step 2: Charge the Fee

After verifying the configuration, charge the modification fee:


```http
POST /people/{personId}/loans/{loanId}/fees
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "apiName": "modificationFee",
  "externalId": "MOD-FEE-2024-001",  // Your system's identifier for tracking
  "feeAmount": 35.00,                 // Amount configured for due date changes
  "description": "Fee for deferring January payment"  // Optional context
}
```

### Scenario 3: Managing Multiple NSF Fees

When handling multiple returned payments, you might need to assess NSF fees while respecting frequency limits and caps.

1. First, check annual fee totals to verify cap compliance:



```http
GET /people/{personId}/loans/{loanId}/fees?type=nsfFee
```

1. Charge the NSF fee:



```http
POST /people/{personId}/loans/{loanId}/fees
Content-Type: application/json

{
  "apiName": "nsfFee",
  "externalId": "NSF-2024-002",
  "feeAmount": 35.00,
  "customDisplayName": "Returned Payment Fee",
  "chargeDate": "2024-12-09"
}
```

1. If you later need to cancel one of these fees:



```http
POST /people/{personId}/loans/{loanId}/fees/{loanFeeId}/cancel
Content-Type: application/json

{
  "caseId": "NSF-REVERSAL-001"
}
```

### Scenario 4: Loan Modification Fee with State-Specific Amount

When processing a loan modification, you might need to charge a fee that varies by state.

1. Charge the modification fee:



```http
POST /people/{personId}/loans/{loanId}/fees
Content-Type: application/json

{
  "apiName": "modificationFee",
  "externalId": "MOD-2024-001",
  "feeAmount": 50.00,
  "chargeDate": "2024-12-10",
  "caseId": "MODIFICATION-001",  // Link to modification case
  "customDisplayName": "Payment Schedule Modification Fee"
}
```

The system will automatically:

- Validate the fee amount against state regulations
- Apply any applicable caps
- Link the fee to the modification case


## Fee Amount Logic

Peach supports various ways to calculate fee amounts:

1. **Fixed Amount**



```json
{
  "feeAmount": 25.00
}
```

1. **Percentage of Principal**



```json
{
  "type": "percentageOfPrincipal",
  "percentage": 0.05  // 5% of outstanding principal
}
```

1. **Percentage with Cap**



```json
{
  "type": "percentageOfOverdueBalanceInPeriodCapped",
  "percentage": 0.10,
  "maxAmount": 50.00
}
```

## Best Practices

1. **Fee Tracking**
  - Use consistent `externalId` naming conventions
  - Link fees to cases when applicable
  - Document fee changes with clear reasons
2. **Compliance**
  - Verify state-specific limits before charging
  - Track annual and lifetime fee totals
  - Consider borrower notification requirements
3. **Error Handling**
  - Handle loan lock scenarios gracefully
  - Validate fee eligibility before charging
  - Implement proper retry logic
4. **Fee Management**
  - Cancel fees before processing if changes needed
  - Track fee history for audit purposes
  - Monitor fee caps and limits


## Error Handling

Common responses:


```json
// Loan locked
{
  "status": 423,
  "message": "Loan is locked for updates. Please retry in a few minutes."
}

// Fee cap exceeded
{
  "status": 412,
  "message": "Fee amount exceeds annual cap for state CA"
}
```

Handle errors by:

1. Implementing retry logic for locked loans
2. Checking caps before charging fees
3. Validating fee eligibility upfront


## Next steps

- **[About Fees](/loan-lifecycle/fees/about-fees)** — Conceptual overview of how fees work in Peach.
- **[Loan Lifecycle overview](/loan-lifecycle)** — Index of the full loan lifecycle from origination through closeout.