APR Verification - Response

Please see the Legend to understand the conventions used to document each element and attribute. Note that for responses, the XML elements are documented in the order that they appear in the response.

🟥 <outREGZ_APR>

This is the root element of the XML APR query result message, and is required. This element simply acts as a container for all of the result child elements.

Attributes: None

🟥 <Results>

This parent element contains the reports the success or failure(s) of the calc request.

Attributes: None

🟥 <Results>—><Description>

If the calculation was completed successfully, then this element will contain the value ‘Successful Calculation’. Otherwise, this element will contain a description of the problem encountered during the atstempted computation.

Attributes: None

🟦 <Results>—><XMLDetail>[]

The XMLDetail elements are messages passed back to the calling application which detail the status of the XML request. If the SCEX issues any warnings regarding unrecognized elements or attributes, then each warning message will be displayed in an XMLDetail element.

In our sample output above, no warnings are returned by the SCEX, and hence there are no XMLDetail elements returned.

Attributes: None

🟥 <RegZAPR_Data>

The Regulation Z APR data is contained in the sub-elements of this element. This element contains no data.

Attributes: None

🟥 <RegZAPR_Data>—><Accrual>

US Rule APR’s will disclose the precise method of interest accrual in this element. All of the variation is in regards to “Term factors”. All US Rule interest accrual is governed by the following formula: Interest = APR/100 * Term Factor * Balance. Each accrual method has its own rules for generating these term factors, which represent how many years interest has been accruing.

Attributes: None

🟥 <RegZAPR_Data>—><Method>

‘Actuarial’, ‘US Rule’, or ‘EU-APR’ will be displayed as the value for this element.

Attributes: None

🟥 <RegZAPR_Data>—><PeriodsPerYear>

The number of periods per year are displayed in this element.

Attributes: None

🟥 <RegZAPR_Data>—><RegZAPR>

The computed APR value is reported by this element, according to the APR method and number of decimal places requested through the inputs.

Attributes: None

🟥 <RegZAPR_Data>—><UnitPeriod>

This element contains attributes and a text description of the unit period used in the calculation. The data in this element concatenates the data in its elements. For instance, when Base="Month" and Mult="1", this element is "1_Month".

Attributes: 🔸Base, 🔸Mult

🔸 Base

The Unit Period for any loan has a basic unit of measurement. All possibilities are listed in this attribute.

🔸 Mult

The unit multiple composing the Unit Period. For instance, if the unit period were 6 months, the Base is Month, the Mult is 6.

🟦 <APRCheck_Data>

The elements describing the analysis of a user-entered APR are all contained in the child nodes of this element. This element, itself, has no data. Note that this element and its associated child elements will only be present if a <TestAPR> was included in the request.

Attributes: None

🟥 <APRCheck_Data>—><LoanType>

The Loan Type is either Regular or Irregular. All loans are assumed to be regular unless they contain multiple advances, an irregular period or an irregular payment, all of which are defined below. Note: skipped payment loans are irregular loans, because, though the payments are regular, the periods are not.

Attributes: 🔸IrregPeriod, 🔸IrregPmt, 🔸MultAdv

🔸 IrregPeriod

If a loan has an irregular period between payments, this attribute is true; otherwise, it is false. An irregular period is any period between payments not a unit period. (See Section 18.2.7)

🔸 IrregPmt

If a loan has an irregular payment, this attribute is true; otherwise, it is false. First and final payments are not considered in this assessment. A loan may only have one payment amount from the 2nd through the N-1st payments. If two or more payment amounts exist for these middle payments, this attribute will be true.

🔸 MultAdv

If a loan has more than one advance, this attribute will be true; otherwise, it is false.

🟥 <APRCheck_Data>—><RegZAPR>

The computed APR is reported by this element, according to the number of decimal places requested through the inputs.

Attributes: None

🟥 <APRCheck_Data>—><TestAPR>

The APR that appears in the input xml which is to be tested for compliance.

Attributes: None

🟥 <APRCheck_Data>—><Difference>

The difference between the computed APR and the test APR is displayed for easy comparison to the tolerance.

Attributes: None

🟦 <APRCheck_Data>—><Tolerance>

The tolerance permitted by RegZ for the type of loan in question. In the United States of America, regular loans have a tolerance of “0.125”, while irregular loans have a tolerance of “0.250”. Official Staff Commentary 226.22(a)(1) - (3)

Note that this element will only appear when Actuarial or US Rule APR methods are in effect.

Attributes: None

🟦 <APRCheck_Data>—><InCompliance>

This element is true or false, depending on whether the difference element is greater than the Tolerance or not. If the difference is greater than the allowed tolerance, this element returns “false”. Otherwise, the APR is within compliance and therefore has “true” returned.

Note that this element will only appear when Actuarial or US Rule APR methods are in effect.

Attributes: 🔹OnCusp

🔹 OnCusp

If a <Difference> is exactly equal to the <Tolerance>, the TestAPR is noted as being "On the cusp"; that is to say, it is maximally distant from the actual APR without being flagged as out of tolerance. This designation is not required by Appendix J of Regulation Z, but is a warning that the algorithm producing the test apr may warrant further testing.

🟥 <Event_Data>

Though [<Event_Data>] has no data itself, the elements it contains are the sums of other important quantities, as described below:

Attributes: None

🟥 <Event_Data>—><Transaction_Date>

The <Transaction_Date> is one of three values, depending on the input: The date entered as the <Transaction_Date> from the inputs, the date of the first advance if the <Transaction_Date> was omitted, or one unit period before the first payment in the case of loans with OddDaysPrepaids.

Attributes: None

🟥 <Event_Data>—><AmtFin>

This element represents the total amount financed for the loan or, more generally, the total of <Advance> elements from the Request.

Attributes: 🔸Count, 🔹PresVal

🔸 Count

The number of advances for a loan are displayed in this attribute.

🔹 PresVal

When the APR Method is “Actuarial”, the present value of all advances are displayed in this attribute.

🟦 <Event_Data>—><FinChg>

This element represents the total finance charge for the loan, and will only be present if the request provided a value greater than zero for the <TestFinChg> element.

Attributes: 🔸TestValue, 🔹Difference

🔸 TestValue

The <TestFinChg> that appears in the request which is to be tested for compliance.

🔸 Difference

The magnitude of the difference between the test Finance Charge and the computed Finance Charge.

🟥 <Event_Data>—><TotPmt>

This element represents the sum of all payments.

Attributes: 🔸Count, 🔹PresVal, 🔹TestValue, 🔹Difference

🔸 Count

The number of payments is recorded here.

🔹 PresVal

When the APR Method is “Actuarial”, the present value of all payments are displayed in this attribute.

🔸 TestValue

The <TestTotPmt> that appears in the input xml which is to be tested for compliance.

🔹 Difference

The magnitude of the difference between the test total of payments and the computed total of payments.

🟥 <Event_Data>—><TotPrem>

This element represents the total of premiums input through the request.

Attributes: 🔸Count, 🔹PresVal

🔸 Count

The number of premiums defined in the input are displayed in this attribute.

🔹 PresVal

When the APR Method is “Actuarial”, the present value of all premiums are displayed in this attribute.

🟥 <AmTable>

Though [<AmTable>] has no data itself, the elements it contains are the sums of other important quantities, as described below:

Attributes: 🔸Error, 🔸ErrorDown, 🔸ErrorUp

🔸 Error

The balance at the end of amortization using the disclosed RegZAPR. The correct RegZAPR is the rate which produces the smallest balance after amortization. Therefore, the magnitude of both ErrorDown and ErrorUp attributes should be greater than this value.

🔸 ErrorDown

The balance at the end of amortization using the disclosed RegZAPR less one rate unit. As an example, if the disclosed RegZAPR is 10.000%, then the [ErrorDown] attribute would contain the error after amortizing the loan with a rate of 9.999%.

The magnitude of this value should never be less than the magnitude of the Error attribute, because the rate with a minimum error magnitude defines the correct RegulationZ APR.

🔸 ErrorUp

The balance at the end of amortization using the disclosed RegZAPR plus one rate unit. As an example, if the disclosed RegZAPR is 10.000%, then the ErrorUp attribute would contain the error after amortizing the loan with a rate of 10.001%.

The magnitude of this value should never be less than the magnitude of the Error attribute, because the rate with a minimum error magnitude defines the correct RegulationZ APR.

🟥 <AmTable>—><AmLine>

The AmLine element contains the actual events that drive the calculation of the APR; however, the information required to compute a particular APR depends heavily on what type of APR that's being computed. Of the seven different methods of APR computation (namely Actuarial, USRule, EU_APR, XIRR, XIRR360, IRR, YieldIRR) the structure of <AmLine> attributes can reduce to two structures: Present Value and USRule.

Attributes: 🔹Adv, 🔹BegBal, 🔸Date, 🔹EndBal, 🔹Factor, 🔹Frac, 🔸Idx, 🔹IntPaid, 🔹IntUnpaid, 🔹Pmt, 🔹Prem, 🔹PresVal, 🔹PresValSum, 🔹Unit

🔹 Adv

Cash advances are recorded in this attribute, common to all APR Methods.

🔹 BegBal

USRule APR's are unique, in that they do no compute present values but, rather, re-amortize the loan. The balance prior to applying the cash event and interest is recorded in this attribute.

🔸 Date

The date of the AmLine event is recorded in this attribute in a YYYY-MM-DD format.

🔹 EndBal

USRule APR's note the effect of the AmLine by recording the ending balance. Note that one AmLine's EndBal is the next line's BeginBal.

🔹 Factor

APR Methods of USRule, EU_APR, XIRR, XIRR360, IRR, YieldIRR record the Factor used in their calculation. This factor represents a measure of time appropriate to that calculation.

🔹 Frac

Actuarial APR's require both the number of unit periods and the fraction of a unit period to be computed as required by Appendix J to Regulation Z. From these two values, the cash of the event is discounted. The fractional value is recorded in this attribute.

🔸 Idx

The timewise sequence of events starting at zero is recorded in this attribute.

🔹 IntPaid

USRule APR's record the interest paid, if any.

🔹 IntUnpaid

USRule APR's record any unpaid interest.

🔹 Pmt

Payments are recorded in this attribute, common to all APR Methods.

🔹 Prem

Protection Fees or Premiums are recorded in this attribute.

🔹 PresVal

The present value resulting from the computation on the cash amount is recorded in this attribute.

🔹 PresValSum

The running total of the accumulated present values are stored in this attribute.

🔹 Unit

Actuarial APR's require the number of unit periods between the event and the <Transaction_Date> to be computed before the cash is present value discounted. That number is recorded in this attribute.