Apr Module - Request

The fields of the Data object supported by the Apr module request are defined in alphabetical order below:

🟥 Data

The Data object encapsulates the request data for a given module, and must always be provided.

Fields: 🔹Decimals, 🔹Method, 🔹TestApr, 🔹TestFinChg, 🔹TestTotPmt, 🔹TransactionDate

Objects: 🟦 ActuarialOpts, 🟦 AmTableOpts, 🟥 Advances[], 🟦 Construction, 🟦 PmtStreams[], 🟦 Premiums[], 🟦 UnitPeriod, 🟦 UsRuleOpts

🔹 Data.Decimals

The number of decimal places of accuracy for the disclosed APR is determined by this field. The default value of this field depends upon the selected Method. For all methods other than EU_APR, the default value is 3. For EU_APR, the default value is 1.

🔹 Data.Method

In the United States of American, Regulation Z allows for APRs to be computed using two different methods: the actuarial method (Actuarial) or the US Rule method (USRule). In the European Union, there is a different method used (EU_APR) to compute the APR. The SCE also supports the calculation of the internal rate of return as defined by Microsoft® Excel's XIRR() function (XIRR), as well as the internal rate of return based upon a unit period 360 days calendar (XIRR360). The IRR method implements a common spreadsheet internal rate of return method which assumes strict regular periods. Deviating from a strict regular periodicity may produce unreliable results. The YieldIRR method is similar to the IRR method, except the rate is converted to an annual yield equivalent, according to the payment frequency.

Use this field to specify the method used to compute the APR. If a value of USRule is specified, make sure to include the USRule object as appropriate.

🔹 Data.TestApr

The SCE will compute an APR for the given loan, then compare the APR it has computed against this value. The difference between the computed and test APRs will be compared. The SCE will inform the calling application whether or not the provided APR is within compliance. If you do not have a test APR to compare, omit this field. The test APR should be expressed as a percentage.

🔹 Data.TestFinChg

If this field is present and contains a value greater than zero, then the SCE will compute the Regulation Z Finance Charge for the given loan and compare it to the value specified in this field. The magnitude of the difference between the computed and test values will be returned in the response.

If this field is not present, or if it is present but contains a value less than or equal to zero, then the Finance Charge will not be returned in the response.

🔹 Data.TestTotPmt

If this field is present and contains a value greater than zero, then the SCE will compute the Regulation Z Total of Payments for the given loan and compare it to the value specified in this field. The magnitude of the difference between the computed and test values will be returned in the response.

If this field is not present, or if it is present but contains a value less than or equal to zero, then the Total of Payments is still returned in the results, however no Difference or TestValue fields will be present.

🔹 Data.TransactionDate

The transaction date is generally the date of the earliet Advance. If, for instance, the finance charge begins beyond the date of the first advance, use this element to define the date the finance charge begins.

See Section (b)(2) Term of the Transaction.

🟦 Data.ActuarialOpts

This object is only considered if the APR Method specified is Actuarial.

Fields: 🔹ForceSemiMonth, 🔹ODI, 🔹SemiMonthlyFixedFraction, 🔹SinglePayFraction

Objects: None

🔹 Data.ActuarialOpts.ForceSemiMonth

The SCE strictly defines a semimonthly unit period as a majority of periods that have "every other payment a month apart and 15 days between payments" as the most common period of time. Since Appendix J loosely defines what a semimonthly period is and a reasonable use of the APR Tool application would allow a looser definition, the SCE now allows for overriding the strict definition with, for example, payments on the 1st and 15th being classified as having a unit period of Semimonth. If an institution wishes a looser definition of semimonth, this setting should be set to true. Otherwise, the strict rule applies.

🔹 Data.ActuarialOpts.ODI

Loans that have used an odd days interest prepaid charge, common with mortgage loans, may use this field to adjust the APR to assume one unit period to the first payment. Otherwise, choose false.

🔹 Data.ActuarialOpts.SemiMonthlyFixedFraction

This field reflects an unintended consequence of Appendix J to Regulation Z's characterization of the fraction of a unit period for semimonthly loans. Applying the rules of Appendix J strictly to each payment in the payment stream results in an oscillating fraction of a unit period. For a constant fraction of a unit period, choose true. To apply the Federal Calendar to each payment, choose false. The latter should typically be selected with an irregular loan.

See Section (b)(5)(iii).

🔹 Data.ActuarialOpts.SinglePayFraction

This field only applies to single advance, single payment transactions of term less than one year. For these loans, when the term of the loan is a number of months, Appendix J allows for the term of the loan to be expressed as either a number of months over twelve, or the number of actual 24-hour days in the loan over 365. For the former, use InMonths. For the latter, use InDays.

See Section (b)(5)(vi, vii).

🟦 Data.AmTableOpts

The fiedls of this object allow the calculation and disclosure of the APR to be adjusted in rarely-needed ways.

Fields: 🔹DollarDec, 🔹ForceDay 🔹RoundInt

Objects: None

🔹 Data.AmTableOpts.DollarDec

Currency amounts within lines of the amortization schedule are disclosed as full floating numbers, which can produce long lines of amortization in the disclosure. The number of decimals for currency quantities may be trimmed to the number of decimal places indicated by this field. Note that this number does not affect the calculation. It merely affects to what number of decimals places to which the floating point number is disclosed. 9 means "do not trim".

🔹 Data.AmTableOpts.ForceDay

End of month considerations may require that a payment's day was intended to be another day. For instance, if payments were intended to be made on the end of the month, and the first payment is in April, making this setting 31 causes the fed calendar to compute time as if the day of the payment was 31, rather than 30.

🔹 Data.AmTableOpts.RoundInt

If interest is rounded within the amortization schedule for US Rule APRs, set the rounding method here.

🟥 Data.Advances[]

This array of Advance objects must have at least one member, and is used to specify the advances made to the borrower. The amount of each advance is equal to the total amount earning interest less any prepaid fees. One may think of these entries as streams of Amounts Financed (in the RegulationZ sense).

Fields: 🔸AmtFin, 🔸Date, 🔹LastDay, 🔹PPY, 🔹Term

Objects: None

🔸 Data.Advances[].AmtFin

The proceeds to be advanced to the borrower less any prepaid fees for each of the Term advances is defined using this field.

🔸 Data.Advances[].Date

This field's value holds the date on which the advance is made. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, an advance date of January 2, 2021 would be specified as "Date" : "2021-01-02".

🔹 Data.Advances[].LastDay

This field is used to resolve ambiguitiess in subsequent advance dates when the Date falls on the last day of a month with fewer than 31 days. If the value of the Term field is 1, then the value of this field is ignored.

Set this field's value to true if the intent was to make subsequent advances occur on the last day of the month. A value of false indicates that subsequent advance dates will fall on the day number specified by the Date field.

🔹 Data.Advances[].PPY

PPY is an abbreviation for "payments per year", and in the case of the Advance object, determines the frequency for the advance stream. If the value of the Term field is 1, then this field is ignored.

🔹 Data.Advances[].Term

The Term field determines the the number of advances to be included at the specified frequency (see Advance.PPY above), after which the advance stream is completed. The default value is 1.

🟦 Data.Construction

Loans which have a construction period require data to be passed using this object. All of the information used to define the construction period is contained in the following fields of the object:

Fields: 🔹AsPrepaid, 🔸EndDate, 🔹HalfCommitment, 🔸Interest, 🔸PermanentAttached, 🔹Prepaid

Objects: None

🔹 Data.Construction.AsPrepaid

This field is only applicable when the PermanentAttached field is true. If the permanent loan treats the construction interest as a prepaid finance fee, then set the value of this field to true.

On the other had, if the construction interest is not treated as a prepaid finance fee and is instead included as a stream of interest only payments during the construction period, then set the value of this field to false.

🔸 Data.Construction.EndDate

The date on which the construction period terminates.

All dates must be in the form of "YYYY-MM-DD", and be 10 characters long. Hence, to end the construction period on July 4, 2021, the field would be specified as "EndDate" : "2021-07-04".

🔹 Data.Construction.HalfCommitment

During the construction period, if estimated interest is disclosed based upon half of the commitment amount, then set the value of this field to true. If interest is due on the entire commitment amount during the construction period, then set this value to false. Multiple advance construction loans are computed with this field set as true.

🔸 Data.Construction.Interest

The total amount of construction interest.

🔸 Data.Construction.PermanentAttached

Construction loans may be computed on their own, or they may be attached to a permanent loan which begins at the conclusion of the construction loan. If a permanent loan is attached to the construction loan, then set this field's value to true. If no permanent loan is attached to the construction loan, then set the field's value to false.

🔹 Data.Construction.Prepaid

This field holds the total prepaid charge for points and fees, excluding construction interest. This field need only be specified when the PermanentAttached field is false.

🟦 Data.PmtStreams[]

One or more PmtStream objects are required to specify the loan's payment stream. For an equal payment loan, a single payment stream element is all that is required. For a balloon payment stream, you will need two. For highly irregular loans (skips, pickups, interest only, etc.) you will need many. All necessary data for each payment stream is contained in the object's fields, which are described below.

Fields: 🔸Begin, 🔹LastDay, 🔸Pmt, 🔹PPY, 🔹SemimonthlyDay, 🔹Term

Objects: None

🔸 Data.PmtStreams[].Begin

This field contains the date on which this payment stream begins. All dates must be in the form of YYYY-MM-DD, and be 10 characters long.

🔹 Data.PmtStreams[].LastDay

This field is used to resolve ambiguitiess in subsequent payment dates when the Begin date falls on the last day of a month with fewer than 31 days. If the value of the Begin field is not a valid date, then the value of this field is ignored.

Set this field's value to true if the intent was to make subsequent payments occur on the last day of the month. A value of false indicates that subsequent payment dates will fall on the day number specified by Begin.

As an example, if the calling application specifies a Begin of `2010-02-281, then subsequent payment dates for a monthly payment frequency will be:

• on the 28th of each subsequent month if "LastDay" : false.
• on the last day of each subsequent month if "LastDay : true.

🔸 Data.PmtStreams[].Pmt

This field defines the principal and interest portion of the payment for each of the Term payments. If the total payment includes any protection products such as MOB life or debt protection fees, then these amounts must be removed as they are not a part of the principal and interest portion of the payment.

🔹 Data.PmtStreams[].PPY

PPY is an abbreviation for "payments per year", and as one might surmise, determines the payment frequency for the payment stream. If the value of the Date field is not a valid date, then the value of this field is ignored.

🔹 Data.PmtStreams[].SemimonthlyDay

When specifying a semimonthly payment stream, the day number on which the first payment is made determines the day number for all of the following odd numbered payments. If you omit this field or specify a value of 0, then the even numbered payments will be generated using the default method within the SCE.

If you wish to specify the day number on which even numbered payments fall (overriding the default method used in the SCE), then set the value of this field to the desired day number. Setting the value of this field to 31 will cause all even payments to fall on the last day of the month.

As an example, if you want to specify a semi-monthly payment stream beginning on January 1, 2019 with payments that fall on the 1st and 15th of each month for 24 payments, the object should look something like this:

{
  "PmtStreams" : [
    {
      "Begin" : "2019-01-01",
      "Term" : "24",
      "PPY" : "24",
      "SemimonthlyDay" : "15"
    }
  ]
}

🔹 Data.PmtStreams[].Term

The term field indicates the the number of payments to be made at the specified payment frequency (see PmtStream.PPY above), after which the payment stream is completed. The default value is 1. If the value of the PmtStream.Begin field is not a valid date, then the value of this field is ignored, unless it is a replacement payment using the NNNN-00-00 date format.

🟦 Data.Premiums[]

Fields: 🔸Date, 🔹Freq, 🔹LastDay, 🔸Prem, 🔹Term

Objects: None

Only loans that have premiums occurring on dates not equal to the payment dates should use this element for expressing the premium. In the case of TruStage, for example, premiums are paid monthly on the same day of the month, regardless of when payments are made. In this case, please use the Premiums array for specifying loan premiums.

🔸 Data.Premiums[].Date

This field contains the date on which this premium stream begins. All dates must be in the form of YYYY-MM-DD, and be 10 characters long.

🔹 Data.Premiums[].Freq

The frequency of premiums expressed as a number of premiums per year.

🔹 Data.Premiums[].LastDay

Was the premium intended for the last day of the month?

🔸 Data.Premiums[].Prem

The Premium amount.

🔹 Data.Premiums[].Term

The number of premiums in the stream.

🟦 Data.UnitPeriod

If this object is not present in the request, then the SCE will compute the unit period. Including this element instructs the SCE to use the unit period specified by the calling application.

As an example, if you wanted to specify a biweekly unit period, then you would include the following in the request:

{
  "UnitPeriod" : {
    "Period" : "Week",
    "Multiple" : "2"
  }
}

Similarly, if you wanted to specify a quarterly unit period, then you would include the follwing in the request:

{
  "UnitPeriod" : {
    "Period" : "Month",
    "Multiple" : "3"
  }
}

Fields: 🔹Multiple, 🔹Period

Objects: None

🔹 Data.UnitPeriod.Multiple

This field's value defines the integral number of standard unit periods in the defined unit period.

🔹 Data.UnitPeriod.Period

This field defines the standard unit period. The unit period will be some integral multiple of this standard unit period, as specified by the Multiple field above.

🟦 Data.UsRuleOpts

This object is only relevant if the APR Method specified is UsRule. The fields of this object allow the calling application to configure the parameters of the US Rule APR calculation.

Fields: 🔹Calendar, 🔹CalendarOption, 🔹Divisor, 🔹PremBeforePmt

Objects: None

🔹 Data.UsRuleOpts.Calendar

Actual day, unit period, and Federal calendars are supported with US Rule interest accrual.

🔹 Data.UsRuleOpts.CalendarOption

True360 means that each month is assumed to have 30 days in all respects. Typically, a loan computes the actual number of days from the Advance to the first payment to compute the Term Factor to the first payment.

True365 means that February 29th is not allowed, both in counting days and assessing the days per year divisor.

Midnight366 only applies to Actual/366 calendars, and means that a day is the time from midnight of one day to midnight of the other. The number of days between December 19th 2007 and January 19th 2008 would be 13 Days in a 365 year plus 18 days in a 366 day year, resulting in a Term Factor of 13/365+18/366. An Actual/366 calculation not using the Midnight366 setting would compute the term factor as 12/365+19/366.

🔹 Data.UsRuleOpts.Divisor

Choose the divisor, or number by which to divide the day count to produce term factors.

360 means take the computed days to the first payment and divide them by 360 to compute the term factor.

365 means take the computed days to the first payment and divide them by 365.

366 is understood to mean 366 only in a leap year. Any days accruing interest in a non-leap year use a 365 divisor. This setting may only be used with ActualDay calendars.

PerPeriod means 360 for monthly and bimonthly periods, 364 for weekly multiples, Quarterly, and SemiAnnual repayments, and 365 for annual loans.

VarDPY is understood to mean that the computed days to the first payment are divided by the number of days in the month of the transaction date, multiplied by twelve.

365_25 means take the computed days to the first payment and divide them by 365.25 to compute the term factor. This setting may only be used with ActualDay calendars.

🔹 Data.UsRuleOpts.PremBeforePmt

Are premiums processed before or after payments? true means premiums are amortized before payments, false means payments are processed before premiums.