Skip to main content

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​

ParameterTypeRequiredDescription
existingLoanIdstringYesID of the loan being refinanced
newLoanProductIdstringYesProduct ID for the new refinanced loan
newLoanAmountdecimalYesPrincipal amount of new loan
newInterestRatedecimalYesInterest rate for new loan
newTermMonthsintegerYesTerm in months for new loan
refinanceReasonstringYesReason for refinancing
effectiveDatedatetimeYesDate when refinance takes effect
cashOutAmountdecimalNoAdditional cash disbursed to borrower
notesstringNoAdditional 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);
  • 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

Product Documentation​

For business process and technical flow details, see: