Refunds - Request

Please see the Legend to understand the conventions used to document each element and attribute. Note that for requests, the XML elements are documented in alphabetical order by parent element.

Element	Attributes
🟥 `<inREFUND>`	`🔹Account`, `🔹DataDirPath`, `🔹ForceReload`, `🔹LoanType`, `🔹PPY`
\|- 🟦 `<AH>`	`🔹CoverageType`, `🔹Plan`, `🔹Premium`, `🔹ScheduledPmts`
\|- 🟦 `<AmortTerm>`
\|- 🟥 `<Balloon>`
\|- 🟦 `<CL>`	`🔹CoverageType`, `🔹Premium`, `🔹PremiumMethod`, `🔹ScheduledPmts`
\|- 🟦 `<IntRate>`
\|- 🟦 `<IU>`	`🔹Premium`, `🔹ScheduledPmts`
\|- 🟦 `<LL>`	`🔹Premium`
\|- 🟥 `<LoanDate>`
\|- 🟥 `<Payment>`
\|- 🟦 `<PmtDate>`
\|- 🟦 `<PP>`	`🔹Premium`, `🔹ScheduledPmts`
\|- 🟥 `<RefundDate>`
\|- 🟥 `<Term>`

🟥 `<inREFUND>`

Element Type	Data Type
Parent	-

This is the root element of the XML refund request and is required. This contains child elements which specify the particulars of the requested refund. The following attributes of the <inREFUND> element are defined:

🔹 `Account`

Data Type	Values	Default
Integer	`[1...9999]`	`1`

This attribute specifies which account should be used to compute the requested loan. Each account is numbered from 1 to 9,999, and each account corresponds to a set of setup files which define numerous settings which may affect the loan calculation, such as the accrual method, insurance methods and rates, etc. If this attribute is not specified, a default value of 1 will be used.

🔹 `DataDirPath`

Data Type	Values	Default
Text	See below	See below

If this attribute is set, the SCE will look for a data folder containing the setup files in the path specified. Thus, if the DataDirPath is set to C:\SCEX\, the SCE will look for the setup files in C:\SCEX\data.

If the calling application wishes to specify the data directory path in its entirety (e.g. the calling app does not want the SCE to append \data to the provided path), then simply terminate the specified DataDirPath with an asterisk (*). Thus, if the DataDirPath is set to C:\SCEX\bank1\*, the SCE will look for the setup files in C:\SCEX\bank1\.

If this attribute is not set, the SCE will attempt to locate the data folder in the default data directory path location, which can be retrieved using the <inVERSION> module query, and set via the SCE API.

This attribute is useful if you wish to use only a single installation of the SCE, but have many different setup file groupings. By specifying a different DataDirPath for each grouping, you can easily separate the groups from one another instead of grouping them all together in a single directory.

🔹 `ForceReload`

Data Type	Values	Default
Boolean	`true`, `false`, `1`, `0`	`false`

The SCE caches setup files previously used. This improves performance for subsequent loan requests using one of the cached accounts. However, if you need the SCE to reload the setup files for a given request (e.g. you just copied over new setup files), then you can set this attribute to true and the setup files will be forced to reload. If left at the default value of false, then setup files are only reloaded when the SCE notices that one of the setup files has been modified.

🔹 `LoanType`

Data Type	Values	Default
Enum	`equal`, `balloon`, `spn`, `intonly`, `prinplus`, `irreg`	`equal`

Different types of loans may require different refund calculations, depending upon the configured refund method for a given insurance type. If this attribute is not specified a value of equal will be assumed.

The allowed values of this attribute and their meanings are described in the table below:

Loan Type	Description
equal	Equal payment loan
balloon	Balloon payment loan
spn	Single payment note
intonly	Interest only loan
prinplus	Fixed principal reduction loan, with optional interest only payments
irreg	Irregular payment loan with optional skipped payments

🔹 `PPY`

Data Type	Values	Default
Enum	See below	`monthly`

PPY is an abbreviation for payments per year, and as one might surmise, determines the payment frequency for the loan. The default value of monthly will result in a loan with 12 payments per year. If you require a loan with a payment frequency other than monthly, specify it using this attribute.

Value	Translation	Description
`1`	`Annual`	Once Per Year
`2`	`SemiAnnual`	Twice Per year (every six months)
`4`	`Quarterly`	Four per year (every three months)
`6`	`Bimonthly`	Six per year (every two months)
`12`	`Monthly`	Twelve per year (every month)
`24`	`Semimonthly`	Twice Per Month^*
`26`	`Biweekly`	Every two weeks
`52`	`Weekly`	Every week

^* Semimonthly loans are characterized by making two payments per month on the same days. A common semimonthly schedule is to make payments every 1st and 16th of the month. Another common schedule is the 15th and the end of every month.

🟦 `<AH>`

Element Type	Data Type
Empty	-

If single premium disability was written on the original loan, then this element should be present to provide the necessary information to compute a disability refund. The element itself is empty, with all required data associated with the computed disability product specified using the following attributes of this element.

🔹 `CoverageType`

Data Type	Values	Default
Enum	`single`, `joint`	`single`

The value of this attribute specifies whether the original decreasing life premium covered one or two borrowers.

🔹 `Plan`

Data Type	Values	Default
Integer	`[0..19]`	`0`

If the specified account has been set up with multiple disability plans, then this attribute determines which plan number will be used. If no plan number is specified, the first plan (plan zero) will be used. To find out the number of available plans, use the <AHSetCount> element returned from an <inINPUT_TOOL> query.

🔹 `Premium`

Data Type	Values	Default
Currency	`>= 0`	`0`

The value of this attribute specifies the original decreasing life premium quoted with the original loan. If this attribute is not specified, a default value of zero (0) will be assumed, and no refund computed.

🔹 `ScheduledPmts`

Data Type	Values	Default
Integer	`>= 0`	`0`

Specify the original decreasing life term of coverage (in months) as the value of this attribute. If a decreasing life premium greater than zero is specified, then this attribute is also required, and no refund computed.

🟦 `<AmortTerm>`

Element Type	Data Type	Values	Default
Data	Integer	`>= 0`	`0`

To compute refunds for certain TruStage insurance products (specifically, those using refund formulas 7 and 8), the desired amortization term of the original loan is required.

🟥 `<Balloon>`

Element Type	Data Type	Values
Data	Currency	`> 0`

This value of this element is the final payment of the original loan. If the final payment is the same value as the regular payment (see above), then simply specify the same value for this element as well.

🟦 `<CL>`

Element Type	Data Type
Empty	-

If single premium decreasing credit life was written on the original loan, then this element should be present to provide the necessary information to compute a decreasing life refund. The element itself is empty, with all required data associated with the computed decreasing life product specified using the following attributes of this element.

🔹 `CoverageType`

Data Type	Values	Default
Enum	`single`, `joint`	`single`

The value of this attribute specifies whether the original decreasing life premium covered one or two borrowers.

🔹 `Premium`

Data Type	Values	Default
Currency	`>= 0`	`0`

🔹 `PremiumMethod`

Data Type	Values	Default
Enum	`gross`, `net`	`gross`

If the specified Account has been configured to offer the option of net or gross coverage written on the original loan, then the value of this attribute should specify the type of coverage written on the original loan. If the specified Account allows for only one type of decreasing life coverage, then this attribute may be omitted.

🔹 `ScheduledPmts`

Data Type	Values	Default
Integer	`>= 0`	`0`

🟦 `<IntRate>`

Element Type	Data Type	Values	Default
Data	Decimal	`[-99.999...600]`	`0`

This element specifies the interest rate used in the calculation of the original loan. The interest rate is not always required, as some refund calculations ignore the original interest rate. However, since some refund calculations do require the interest rate, we recommend that you always include it with the XML input. The interest rate should be expressed as a percentage. For example, a loan computed with a rate of 6.125% would be specified as <IntRate>6.125</IntRate>.

🟦 `<IU>`

Element Type	Data Type
Empty	-

If single premium involuntary unemployment was written on the original loan, then this element should be present to provide the necessary information to compute an involuntary unemployment refund. The element itself is empty, with all required data associated with the computed involuntary unemployment product specified using the following attributes of this element.

🔹 `Premium`

Data Type	Values	Default
Currency	`>= 0`	`0`

🔹 `ScheduledPmts`

Data Type	Values	Default
Integer	`>= 0`	`0`

🟦 `<LL>`

Element Type	Data Type
Empty	-

If single premium level credit life was written on the original loan, then this element should be present to provide the necessary information to compute a level life refund. The element itself is empty, with all required data associated with the computed level life product specified using the following attributes of this element.

🔹 `Premium`

Data Type	Values	Default
Currency	`>=0`	`0`

The value of this attribute specifies the original level life premium quoted with the original loan. If this attribute is not specified, a default value of zero (0) will be assumed, and no refund computed.

🟥 `<LoanDate>`

Element Type	Data Type	Values
Data	Date	`>= 1900-01-01`

This element contains the date on which the original loan amount was disbursed. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. A loan date of June 6, 2015 would be specified as <LoanDate>2015-06-06</LoanDate>.

🟥 `<Payment>`

Element Type	Data Type	Values
Data	Currency	`> 0`

This element should hold the computed regular payment of the original loan.

🟦 `<PmtDate>`

Element Type	Data Type	Values	Default
Data	Date	`>=` `<LoanDate>`	`0`

If the original loan was a single payment note (i.e. LoanType = "spn"), then the payment date of the single payment is required. For all other loan types, this element will be ignored. All dates must be in the form of YYYY-MM-DD, and be 10 characters long.

🟦 `<PP>`

Element Type	Data Type
Empty	-

If single premium personal property was written on the original loan, then this element should be present to provide the necessary information to compute a personal property refund. The element itself is empty, with all required data associated with the computed personal property product specified using the following attributes of this element.

🔹 `Premium`

Data Type	Values	Default
Currency	`>= 0`	`0`

🔹 `ScheduledPmts`

Data Type	Values	Default
Integer	`>=0`	`0`

🟥 `<RefundDate>`

Element Type	Data Type	Values
Data	Date	`>= 1900-01-01`

The value of this element contains the date on which the refund is to be computed. All dates must be in the form of YYYY-MM-DD, and be 10 characters long.

🟥 `<Term>`

Element Type	Data Type	Values
Data	Integer	`> 0`

The term indicates the number of payments that were originally scheduled to be made when the loan was written.

SCEX Reference Manual 2025-04