Initiate Loan Refinance

Overview

API endpoint to initiate loan refinance transactions, replacing existing loans with new loans under different terms, typically to obtain better interest rates, extend repayment periods, or access additional funds.

Command

InitiateLoanRefinanceCommand

Endpoint

POST /api/bpm/cmd

Request Headers

Authorization: Bearer {access_token}
Content-Type: application/json
X-Tenant-ID: {tenant_id}

Request Body

{
  "existingLoanId": "string",
  "newLoanProductId": "string",
  "newLoanAmount": "decimal",
  "newInterestRate": "decimal",
  "newTermMonths": "integer",
  "refinanceReason": "string",
  "effectiveDate": "datetime",
  "cashOutAmount": "decimal",
  "notes": "string"
}

Request Parameters

Parameter	Type	Required	Description
existingLoanId	string	Yes	ID of the loan being refinanced
newLoanProductId	string	Yes	Product ID for the new refinanced loan
newLoanAmount	decimal	Yes	Principal amount of new loan
newInterestRate	decimal	Yes	Interest rate for new loan
newTermMonths	integer	Yes	Term in months for new loan
refinanceReason	string	Yes	Reason for refinancing
effectiveDate	datetime	Yes	Date when refinance takes effect
cashOutAmount	decimal	No	Additional cash disbursed to borrower
notes	string	No	Additional notes or comments

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Loan refinance initiated successfully",
  "data": {
    "transactionId": "string",
    "existingLoanId": "string",
    "newLoanId": "string",
    "existingBalance": "decimal",
    "newLoanAmount": "decimal",
    "cashOutAmount": "decimal",
    "closingCosts": "decimal",
    "effectiveDate": "datetime",
    "status": "string"
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Invalid request parameters",
  "errors": [
    {
      "field": "string",
      "message": "string"
    }
  ]
}

404 Not Found

{
  "success": false,
  "message": "Existing loan not found"
}

422 Unprocessable Entity

{
  "success": false,
  "message": "Loan refinance validation failed",
  "errors": [
    "Loan does not qualify for refinance",
    "Insufficient collateral for new loan amount"
  ]
}

Business Rules

1. Existing loan must be in good standing
2. Borrower must meet underwriting criteria for new loan
3. New loan pays off existing loan in full
4. Collateral must be adequate for new loan amount
5. All fees and closing costs must be accounted for

Code Example

JavaScript Example

const response = await fetch('https://api.example.com/api/bpm/cmd', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
    'X-Tenant-ID': tenantId
  },
  body: JSON.stringify({
    existingLoanId: 'LN-12345',
    newLoanProductId: 'PROD-678',
    newLoanAmount: 50000.00,
    newInterestRate: 4.5,
    newTermMonths: 180,
    refinanceReason: 'Lower interest rate',
    effectiveDate: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
    cashOutAmount: 0,
    notes: 'Rate reduction refinance - no cash out'
  })
});

const result = await response.json();
console.log('Refinance details:', result);

Related Commands

• CalculateRefinanceAmountQuery - Calculate refinance details
• InitiateLoanPayOffCommand - Pay off without refinancing
• CreateLoanCommand - Create the new refinanced loan
• CloseLoanCommand - Close the old loan

Notes

• Refinance typically requires new underwriting and approval
• Existing loan is closed when new loan is funded
• Collateral liens may need to be updated or re-recorded
• Credit bureau reporting reflects loan payoff and new loan
• Refinance may include cash-out or be rate/term only