Initiate Loan Write-Off

Overview

API endpoint to initiate loan write-off transactions for loans that are deemed uncollectible, removing them from active loan portfolio while maintaining records for regulatory and tax purposes.

Command

InitiateLoanWriteOffCommand

Endpoint

POST /api/bpm/cmd

Request Headers

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

Request Body

{
  "loanId": "string",
  "writeOffAmount": "decimal",
  "writeOffDate": "datetime",
  "writeOffReason": "string",
  "approvalReference": "string",
  "notes": "string"
}

Request Parameters

Parameter	Type	Required	Description
loanId	string	Yes	Unique identifier of the loan to write off
writeOffAmount	decimal	Yes	Amount to write off
writeOffDate	datetime	Yes	Date of write-off transaction
writeOffReason	string	Yes	Reason for write-off
approvalReference	string	Yes	Reference to approval authorization
notes	string	No	Additional notes or comments

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Loan write-off initiated successfully",
  "data": {
    "transactionId": "string",
    "loanId": "string",
    "writeOffAmount": "decimal",
    "writeOffDate": "datetime",
    "previousBalance": "decimal",
    "newBalance": "decimal",
    "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 write-off validation failed",
  "errors": [
    "Loan status does not permit write-off",
    "Insufficient approval authority"
  ]
}

Business Rules

1. Loan must be in appropriate status for write-off
2. Write-off requires proper approval authorization
3. Write-off amount must not exceed outstanding balance
4. Proper accounting entries must be generated
5. Regulatory reporting requirements must be met

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',
    writeOffAmount: 5000.00,
    writeOffDate: new Date().toISOString(),
    writeOffReason: 'Uncollectible - Customer bankruptcy',
    approvalReference: 'APPR-2024-001',
    notes: 'Full balance write-off after exhausting collection efforts'
  })
});

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

Related Commands

• InitiateLoanPayOffCommand - Pay off loan in full
• InitiateLoanRefinanceCommand - Refinance existing loan
• ApproveTransactionCommand - Approve write-off transaction
• ReverseLoanTransactionCommand - Reverse write-off if needed

Notes

• Write-offs require appropriate approval authority based on amount
• Accounting entries are automatically generated for write-off transactions
• Credit bureau reporting is updated to reflect write-off status
• Tax reporting implications should be considered for write-offs
• Complete audit trail is maintained for all write-off transactions