Dealer Reserve - 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.

🟥 <inDEALER_RESERVE>

This is the root element of the XML Dealer Reserve message, and is required. This contains child elements which specify the particulars of the requested calculation, as well as calculation results. Many of the attributes for this element are identical in function and name as those defined in the chapter on Equal Payment loans. The following new attributes of the <inDEALER_RESERVE> element are:

Attributes: 🔹Account, 🔹AccrualCode, 🔹DataDirPath, 🔹Method, 🔹PPY

🔹 Account

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.

🔹 AccrualCode

This property allows an accrual method to be used other than the accrual method dictated by the setup file for the given account. If no accrual code attribute is specified, the method defined in the setup file will be used. The Accrual Code Table lists all valid accrual codes available. Note that for the split rate accrual codes (i.e. those above 500), the split rate tiers must be defined in the setup file.

🔹 DataDirPath

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.

🔹 Method

This attribute defines how the reserve is to be computed.

• RatioOfRates - Compute the gross reserve factor as the ratio of the difference between the Note Rate and the Buy Rate to the Note rate: Gross reserve factor = (NoteRate - BuyRate) / NoteRate. If the Finance Charge is entered as data, apply the factor to the Finance Charge. If the Finance Charge is not entered, apply the factor to the computed Finance Charge = (<Term> - 1) * <Payment> + <Final> - <AmtFin>.

• DifferenceInRates - Compute a loan based on accrual settings using a rate equal to the NoteRate - Buy Rate, and set the Gross Reserve equal to the computed Finance Charge.

• DifferenceInFinCharges - Compute a loan based on the Buy Rate. If the Finance Charge is entered as data, set the Gross Reserve equal to the entered Finance Charge minus the Finance Charge computed at the Buy Rate. If the Finance Charge is not entered, compute the Finance Charge at the Note Rate as (<Term> - 1) * <Payment> + <Final> - <AmtFin>. Take the difference between this Finance Charge and the Finance Charge at the Buy Rate, and set the Gross Reserve equal this amount.

🔹 PPY

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.

^* 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.

🟥 <AmtFin>

The Amount Financed value of the transaction. This amount is assumed to be the amount earning interest (i.e. no prepaid charges).

Attributes: None

🟥 <BuyRate>

The rate at which the dealer made his or her purchase (must be less than the <NoteRate>). The buy rate should be expressed as a percentage. For example, a buy rate of 8% would be specified as <BuyRate>8.000</BuyRate>.

Attributes: None

🟦 <Final>

The final payment computed for the customer at the Dealer Rate. If this element is not used, the <Payment> will be used as the final payment. If the <Final> is different from the <Payment>, the loan is considered a balloon loan.

Attributes: None

🟦 <FinChg>

The finance charge computed at the Note Rate. If this element is zero or not used, the Finance Charge is computed as (<Term> - 1) * <Payment> + <Final> - <AmtFin>.

Attributes: None

🟦 <FlatFee>

If a flat fee is used instead of a computed reserve amount, that amount is entered here. In this case, a reserve amount is not computed. This flat fee is registered as the Dealer Reserve in the output.

Attributes: None

🟦 <Format>

The <Format> element is one of the first elements parsed from a request, as the attributes of this empty element affect how date and numeric values are parsed and validated.

Attributes: 🔹CurrencyDecimals, 🔹DateFormat, 🔹DateSeparator, 🔹DecimalSeparator, 🔹StrictDP, 🔹ThousandSeparator

🔹 CurrencyDecimals

When displaying and parsing Currency values, the value of this attribute determines the maximum number of decimal places allowed after the DecimalSeparator.

🔹 DateFormat

When displaying and parsing Date values, this field determines the expected format for all Date fields. The following DateFormat options are allowed:

• YMD - All dates should be formatted as YYYY-MM-DD.
• MDY - All dates should be formatted as MM-DD-YYYY.
• DMY - All dates should be formatted as DD-MM-YYYY.

Note that the character which separates the individual month, day, and year portions of the date is configurable via the DateSeparator attribute.

🔹 DateSeparator

When displaying and parsing Date values, this attribute determines the character used to separate the individual month, day, and year portions of a date.

🔹 DecimalSeparator

When displaying and parsing Currency or Decimal numeric values, this attribute determines the character used to separate the fractional part from the whole.

🔹 StrictDP

If the value of this attribute is true, then the SCE will strictly verify the number of decimal places allowed for currency input values. Thus, if the calling application sends in a request with a currency amount of 1000.005, the SCE will return an error code.

If the value of this attribute is false, then currency values sent in with an invalid number of decimal places will be rounded to the correct number of decimal places by the SCE (using five/four rounding), and a warning message with this information will be returned with the response.

🔹 ThousandSeparator

When displaying numeric values, this attribute determines the character used to separate the thousands places from the hundreds. Note that when parsing numeric values, the value of this attribute is ignored.

🟥 <LoanDate>

This element contains the date on which interest begins to accrue. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a loan date of June 6, 2003 would be specified as <LoanDate>2003-06-06</LoanDate>.

Attributes: None

🟥 <NoteRate>

The rate at which the dealer sold the unit. The note rate should be expressed as a percentage. For example, a note rate of 10% would be specified as <NoteRate>10.000</NoteRate>. This rate is assumed to be equal to the Regulation Z APR for purposes of APR verification.

Attributes: None

🟥 <Payment>

The regular payment computed for the customer at the Dealer Rate.

Attributes: None

🟥 <PmtDate>

This element contains the date on which the first payment of the loan is made, and must be on or after the loan date. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a first payment date of July 6, 2003 would be specified as <PmtDate>2003-07-06</PmtDate>.

Attributes: None

🟦 <ProcFee>

If a processing fee is charged (which diminishes the net Dealer Reserve), it should be placed in this element.

Attributes: None

🟥 <ReservePercent>

The distribution of the Gross Reserve between the dealer and the original lender. The reserve percent should be expressed as a percentage. For example, if the dealer should receive 95% of the gross revenue (less any processing fees), then it would be specified as <ReservePercent>95.000</ReservePercent>.

Attributes: None

🟥 <Term>

The term indicates the number of payments to be made at the specified payment frequency, after which the loan is scheduled to be paid off.

Attributes: None