Apr Module - Response

The Data object for a response from the Apr module is defined below, in the order the fields are returned:

🟥 Data

The Data object encapsulates the response data for a given module, and will always be present.

Fields: None

Objects: 🟥 Errors[], 🟥 Warnings[], 🟥 Apr, 🟦 TestResults, 🟥 Loan, 🟥 AmTable

🟥 Data.Errors[]

The Errors[] field contains an array of Strings which describe any errors encountered while handling the request. If the length of the Errors[] Array is zero (0), then the module processed the request successfully, and the Data object can be further processed by the calling application for the returned data.

On the other hand, if the length of the Errors[] Array is greater than zero (0), then this indicates that an error condition has been detected, and the calling application should not process the respons Data object further. In this case, the contents of the Errors[] array will describe the error(s) encountered.

Typical errors include the omission of 🟥 required fields, invalid field values, etc.

🟥 Data.Warnings[]

The Warnings[] field contains an array of Strings which describe any warnings generated by the module handling the request. The most common warnings returned by modules inform the calling application that the module does not recognize a specified field (which may help to isolate a field name spelling error in the calling application's code). Note that field names which start with "//" will bre treated as comment fields by the SCE, and no warnings will be generated for these unrecognized fields.

Example - Request and response illustrating warnings when passing unrecognized fields:

{
  "Module" : "Apr",
  "Data" : {
    "//" : "This is a comment.",
    "Hello" : "Friend!",
    "How" : "are you?"
  }
}

{
  "Result" : 200,
  "Module" : "Apr",
  "Data" : {
    "Errors" : [
      "Data.Advances[] (Array) not found.",
      "Data.PmtStreams[] (Array) not found."
    ],
    "Warnings" : [
      "Request field Data.Hello (String) not recognized.",
      "Request field Data.How (String) not recognized."
    ]
  }
}   

🟥 Data.Apr

Fields: 🔸Value, 🔸Method, 🔹Accrual, 🔹UnitPeriod, 🔹UnitPeriodBase, 🔹UnitPeriodMult, 🔹PeriodsPerYear

Objects: None

The APR data is contained in the fields of this object.

🔸 Data.Apr.Value

The numeric value of the computed Apr, expressed as a percentage.

🔸 Data.Apr.Method

This field returns the Apr method used to compute the numeric Apr value.

🔹 Data.Apr.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.

🔹 Data.Apr.UnitPeriod

The value in this field concatenates the Apr.UnitPeriodMult and Apr.UnitPeriodBase into one value. For instance, when with "Base : "Month" and "Mult" : "1", this field's value will be is { "UnitPeriod" : "1_Month" }.

This field will only be present when the Apr method is Actuarial, EU, or US Rule with a unit period calendar.

🔹 Data.Apr.UnitPeriodBase

The Unit Period for Actuarial, EU, and US Rule (using a unit period calendar) APRs have a basic unit of measurement. The value of this field discloses the basic unit of measurement.

This field will only be present when the Apr method is Actuarial, EU, or US Rule with a unit period calendar.

🔹 Data.Apr.UnitPeriodMult

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

This field will only be present when the Apr method is Actuarial, EU, or US Rule with a unit period calendar.

🔹 Data.Apr.PeriodsPerYear

The value of this field holds the number of periods per year.

This field will only be present when the Apr method is Actuarial or US Rule with a unit period calendar.

🟦 Data.TestResults

The TestResults object is present if the calling application has specified one of the following: (i) TestApr, (ii) TestFinChg, or (iii) TestTotPmt. The child fields of this object descibe the analysis of each of the three possible tests.

Fields: None

Objects: 🟦 Apr, 🟦 FinChg, 🟦 TotPmt

🟦 Data.TestResults.Apr

This object is only present if the request provided a value greater than zero in for the value of the TestApr field.

Fields: 🔹LoanType, 🔹MultAdv, 🔹IrregPeriod, 🔹IrregPmt, 🔸Value, 🔸TestValue, 🔸Difference, 🔹Tolerance, 🔹InCompliance, 🔹OnCusp

Objects: None

🔹 Data.TestResults.Apr.LoanType

The LoanType is either Regular or Irregular. All loans are assumed to be Regular unless they contain multiple advances, an irregular period other than the first, or an Irregular Payment other than the first or final, all of which are defined below. Note: Skipped payment loans are irregular loans, because, though the payments are regular, the periods are not.

This field is only present when the APR method is Actuarial or US Rule.

🔹 Data.TestResults.Apr.MultAdv

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

This field is only present when the APR method is Actuarial or US Rule.

🔹 Data.TestResults.Apr.IrregPeriod

If a loan has an irregular period between payments, this value of this field is true; otherwise, it is false. An irregular period is any period between payments not a unit period. (See 12 C.F.R. § 1026.22(a)(3))

This field is only present when the APR method is Actuarial or US Rule.

🔹 Data.TestResults.Apr.IrregPmt

If a loan has an irregular payment, this value of this field 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 field will be true.

This field is only present when the APR method is Actuarial or US Rule.

🔸 Data.TestResults.Apr.Value

The APR computed by the SCE.

🔸 Data.TestResults.Apr.TestValue

The APR specified by the request which is to be tested for compliance.

🔸 Data.TestResults.Apr.Difference

The magnitude of the difference between the test APR and the computed APR.

🔹 Data.TestResults.Apr.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. See official staff commentary 226.22(a)(1) - (3)

This field is only present when the APR method is Actuarial or US Rule.

🔹 Data.TestResults.Apr.InCompliance

This value of this field is true or false depending on whether the Difference 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.

This field is only present when the APR method is Actuarial or US Rule.

🔹 Data.TestResults.Apr.OnCusp

If a test apr is exactly equal to the tolerance, the OnCusp field is true; otherwise, it is false. Though the loan is within compliance, a loan far enough out of compliance to be on the cusp of acceptability may want to be flagged for closer scrutiny.

This field is only present when the APR method is Actuarial or US Rule.

🟦 Data.TestResults.FinChg

This object is only present if the request provided a value greater than zero in for the value of the TestFinChg field.

Fields: 🔸Value, 🔸TestValue, 🔸Difference

Objects: None

🔸 Data.TestResults.FinChg.Value

The Finance Charge computed by the SCE.

🔸 Data.TestResults.FinChg.TestValue

The Finance Charge specified by the request which is to be tested for compliance.

🔸 Data.TestResults.FinChg.Difference

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

🟦 Data.TestResults.TotPmt

This object is only present if the request provided a value greater than zero in for the value of the TestTotPmt field.

Fields: 🔸Value, 🔸TestValue, 🔸Difference

Objects: None

🔸 Data.TestResults.TotPmt.Value

The Total of Payments computed by the SCE.

🔸 Data.TestResults.TotPmt.TestValue

The Total of Payments specified by the request which is to be tested for compliance.

🔸 Data.TestResults.TotPmt.Difference

The magnitude of the difference between the test Total of Payments and the computed Total of Payments.

🟥 Data.Loan

Fields: 🔸TransactionDate, 🔸AmountFinanced, 🔸NumAdvances, 🔹AdvPresBal, 🔸TotPmt, 🔸NumPmts, 🔹TotPmtPresBal

Objects: None

🔸 Data.Loan.TransactionDate

The Transaction Date is one of three values, depending on the input: The date entered as the TransactionDate from the request, the date of the first advance if the TransactionDate was omitted, or one unit period before the first payment in the case of loans with odd days interest.

🔸 Data.Loan.AmountFinanced

The total amount financed for the loan.

🔸 Data.Loan.NumAdvances

The value of this field represents the number of advances in the specified loan.

🔹 Data.Loan.AdvPresBal

The value of this field is the present value of all advances made in the specified loan.

This field is only present when the APR method is Actuarial.

🔸 Data.Loan.TotPmt

The total of all payments made in the requested loan.

🔸 Data.Loan.NumPmts

The value of this field represents the number of payments made in the specified loan.

🔹 Data.Loan.TotPmtPresBal

The value of this field is the present value of all payments made in the specified loan.

This field is only present when the APR method is Actuarial.

🟥 Data.AmTable

This object holds the amortization table as well as important error function results as fields.

Fields: 🔸Error, 🔸ErrorDown, 🔸ErrorUp

Objects: 🟥AmLines

🔸 Data.AmTable.Error

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

🔸 Data.AmTable.ErrorDown

The balance at the end of amortization using the disclosed APR less one rate unit. As an example, if the disclosed APR is 10.000%, then the ErrorDown field 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 field, because the rate with a minimum error magnitude defines the correct APR.

🔸 Data.AmTable.ErrorUp

The balance at the end of amortization using the disclosed APR plus one rate unit. As an example, if the disclosed RegZAPR is 10.000%, then the ErrorUp field 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 field, because the rate with a minimum error magnitude defines the correct APR.

🟥 Data.AmTable.AmLines[]

This field is an array of AmLine objects, which describe each amortization line in the schedule.

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

Objects: None

🔸 Data.AmTable.AmLines[].Idx

The index of the amortization event, starting with zero.

🔸 Data.AmTable.AmLines[].Date

The date of the amortization event.

🔹 Data.AmTable.AmLines[].Adv

The amount of the advance.

This field is only present if this AmLine object is an advance event.

🔹 Data.AmTable.AmLines[].Pmt

The payment amount.

This field is only present if this AmLine object is a payment event.

🔹 Data.AmTable.AmLines[].Prem

The premium amount.

This field is only present if this AmLine object is a premium event.

🔹 Data.AmTable.AmLines[].Unit

The number of full unit periods from this event to the transaction date.

See 12 C.F.R. § 1026, Appendix J(b)(5)).

This field is only present when the APR method is Actuarial or US Rule using the Federal Calendar.

🔹 Data.AmTable.AmLines[].Frac

The number of fractional unit periods from this event to the transaction date.

See 12 C.F.R. § 1026, Appendix J(b)(5)).

This field is only present when the APR method is Actuarial or US Rule using the Federal Calendar.

🔹 Data.AmTable.AmLines[].Factor

The Term Factor used to compute interest. (APR/100) Term Factor BegBal = New Interest.

This field is only present when the APR method is not Actuarial.

🔹 Data.AmTable.AmLines[].PresVal

The present value of the event cash at the time of the transaction date.

This field is only present when the APR method is not US Rule.

🔹 Data.AmTable.AmLines[].PresValSum

The running total present value sum.

This field is only present when the APR method is not US Rule.

🔹 Data.AmTable.AmLines[].BegBal

The beginning balance before amortizing this event.

This field is only present when the APR method is US Rule.

🔹 Data.AmTable.AmLines[].IntPaid

The amount of interest paid at this event.

This field is only present when the APR method is US Rule.

🔹 Data.AmTable.AmLines[].IntUnPaid

The amount of unpaid interest remaining after this event is amortized.

This field is only present when the APR method is US Rule.

🔹 Data.AmTable.AmLines[].EndBal

The ending balance after amortizing this event.

This field is only present when the APR method is US Rule.