Initiate Loan Pay-Off

Overview

API endpoint to initiate loan pay-off transactions for borrowers who want to fully repay their loans before the scheduled maturity date, including calculation of any prepayment penalties or early settlement charges.

Command

InitiateLoanPayOffCommand

Endpoint

POST /api/bpm/cmd

Request Headers

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

Request Body

{
  "loanId": "string",
  "payOffDate": "datetime",
  "paymentAccountId": "string",
  "includePrepaymentPenalty": "boolean",
  "notes": "string"
}

Request Parameters

Parameter	Type	Required	Description
loanId	string	Yes	Unique identifier of the loan to pay off
payOffDate	datetime	Yes	Date of pay-off transaction
paymentAccountId	string	Yes	Account to debit for pay-off amount
includePrepaymentPenalty	boolean	No	Whether to include prepayment penalty
notes	string	No	Additional notes or comments

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Loan pay-off initiated successfully",
  "data": {
    "transactionId": "string",
    "loanId": "string",
    "payOffAmount": "decimal",
    "principalAmount": "decimal",
    "interestAmount": "decimal",
    "penaltyAmount": "decimal",
    "totalPayOffAmount": "decimal",
    "payOffDate": "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": "Loan not found"
}

422 Unprocessable Entity

{
  "success": false,
  "message": "Loan pay-off validation failed",
  "errors": [
    "Insufficient funds in payment account",
    "Loan has pending transactions"
  ]
}

Business Rules

1. Loan must be in active status
2. Pay-off amount includes principal, accrued interest, and any penalties
3. Payment account must have sufficient funds
4. Prepayment penalty calculated based on loan terms
5. All pending transactions must be resolved before pay-off

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({
    loanId: 'LN-12345',
    payOffDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
    paymentAccountId: 'ACC-67890',
    includePrepaymentPenalty: true,
    notes: 'Early pay-off requested by customer'
  })
});

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

Related Commands

• CalculateLoanPayOffAmountQuery - Calculate pay-off amount without initiating
• InitiateLoanRefinanceCommand - Refinance instead of pay-off
• RecordLoanPaymentCommand - Record regular loan payments
• CloseLoanCommand - Close loan after pay-off completion

Notes

• Pay-off quotes are typically valid for a specific period (e.g., 10 days)
• Prepayment penalties vary based on loan product and terms
• Per-diem interest is calculated up to the pay-off date
• Automatic payments should be cancelled after pay-off
• Lien releases are processed automatically after successful pay-off