Disbursement Element

Policy and Client level activities can be configured to create disbursements that move money out of the OIPA system. A disbursement is created through the <Disbursement> element. It is part of the Activity’s Math section and in many places references the Activity’s math variable or field data. It has the following characteristics:

• Disbursements are created as Unapproved and Pending status.

• There are 2 system provided disbursement types: EFT and ACH. Configuration may add custom disbursement types as needed. There is a corresponding CheckEFTInformation business rule which defines the default disbursement type and limits an applicable electronic transfer type to either EFT or ACH. The distinction between these two types may be important to downstream disbursement processing.

• An amount is associated with each disbursement. Associated with each amount can be a taxable amount.

• The goal of the Disbursement configuration is to create a disbursement for an amount of money to be paid to a payee. The payee must be a Client in OIPA and is identified through the Policy’s or Segment’s Role or by processing a Client level activity on the intended payee.

• Each disbursement may contain dynamic fields to hold additional information about the disbursement. This information will be presented on the Disbursement tab of the Activity.

• All disbursements are created in a Pending status. A disbursement should not be updated to Active status until a check is generated or money transferred out of the business’s control. An external process must initiate this update.

• During creation, disbursements may be immediately approved by the configuration and bypass presentation on the Disbursement Approval screen. Such a disbursement is immediately available for the extract to a downstream system.

• Disbursement data may contain Withholding information by including the <WithholdingFields> element within the <Disbursement> element's structure and the <Withholding> higher level Transaction element. The value of the <Withholding> transaction element must be Activity.

• Disbursements that are not immediately approved can be displayed on the OIPA Disbursement Approval screen.

• A Recoverable attribute will turn on and off the disbursement recovery functionality.

  • By default, disbursement recovery is off. When the activity that creates the disbursement is reversed or recycled and the disbursement has an Active status, the disbursement is considered completely recovered and moves to a Recovered status. When the activity that creates the disbursement is reversed or recycled and the disbursement has a Pending status, the disbursement does not need to be recovered and moves
    to a Pending Shadowed status.

  • When disbursement recovery is turned on, a disbursement can move to Recoverable status when the disbursement is Active, and the disbursement activity is reversed. If the disbursement is Pending as the disbursement activity is reversed the disbursement does not
    need to be recovered and moves to a Pending Shadow status.

  • When recoverable amounts are present and a subsequent disbursement is being created by an activity, the system determines a recovered amount and a disbursement amount from the disbursement data that the activity is attempting to create. There are two methods to determine the updates to disbursement: Unbalanced and Balanced.

Unbalanced Recovery Method

• If the activity attempts to create a disbursement that exceeds the system’s current recoverable amount, recovery is fully reconciled, and the excess is paid out as a disbursement.

• If the activity attempts to create a disbursement that is equal to the system’s current recoverable amount, recovery is fully reconciled, and no amount is paid out as a disbursement.

• If the activity attempts to create a disbursement that is less than the system’s current recoverable amount, the disbursement reduces the system’s current recoverable amount, and no amount is paid out as a disbursement.

Balanced Recovery Method

• If the activity attempts to create a disbursement that exceeds the system’s current recoverable amount, recovery is fully reconciled, and the excess is paid out as a disbursement.

• If the activity attempts to create a disbursement that is equal to the system’s current recoverable amount, recovery is fully reconciled, and no amount is paid out as a disbursement.

• If the activity attempts to create a disbursement that is less than the system’s current recoverable amount, the system establishes a negative pending disbursement for the difference between the activity’s disbursement and the system’s current recoverable amount and reduces the current recoverable amount to 0.

• Future disbursements must continue to pay down pending negative disbursement amounts and establish new pending negative disbursement amounts representing what is left to pay.

• When all pending negative disbursements are paid off, the system can start paying out disbursements.

• The user may forgive pending negative disbursements by modifying the disbursement status to Active. A client cannot be paid active negative disbursements.

Element	Parent Element	Attribute	Description	Value
<Disbursement>	<Math>		The start and end elements are used to enable Disbursement functionality.
	<Disbursement>	APPROVALSTATUS	Optional: This attribute sets the initial value of the disbursement's approval.  Appropriate values are defined by AsCodeDisbursementApproval.  The default value is Unapproved.	math variable | field
	<Disbursement>	APPROVAL	Required: This attribute designates the disbursement records that can be displayed on the Disbursement Approval screen.	Yes | No
	<Disbursement>	CheckEFTInformation	Optional: This attribute provides a further definition of processing EFTs and checks through the CheckEFTInformation business rule.  The default value is No.	Yes | No (default)
	<Disbursement>	DisbursementType	Required: This attribute provides the type of disbursement that will be created.  Appropriate values are contained in AsCodeDisbursementType.	code value
	<Disbursement>	METHOD	Optional: This attribute allows outstanding disbursement adjustments to existing because of reversal/recycle processing of the activity containing this disbursement creation.  A value of Balanced means reversal/recycle processing has not resulted in disbursement adjustment.  A value of Unbalanced means an outstanding disbursement adjustment exists because of reversal/recycle processing.	Balanced | Unbalanced
	<Disbursement>	RECOVERABLE	Optional: This attribute will allow the disbursement to be recoverable.  The default behavior does not recover the disbursement. Note:  Unlike the recovery processing for a Policy where the shadowed disbursements on Roles of a Policy are summed, shadowed disbursements for a Client will be summed.	Yes | No
	<Disbursement>	TAXABLEAMOUNT	Optional: This attribute provides the taxable amount that is being disbursed.  The default is the disbursement amount.	math variable | field
<AddressDisplay>	<Disbursement>		Required: This element will contain the identification of the address for the disbursement.	math variable | field
<DisbursementRole>	<Disbursement>		Optional: This element identifies the payee by the Policy’s RoleGUID.  The element is ignored if configured on a client level activity and is required in policy level transactions.  The element cannot coexist with the <DisbursementClient> element.	math variable | field
	<DisbursementRole>	TYPE	Required: This attribute describes the <DisbursementRole>'s value.  GUID is the only valid value.	GUID
	<DisbursementRole>	DISBURSEMENTAMOUNT	Required: This is the amount of disbursement.	math variable | field
<DisbursementClient>	<Disbursement>		Optional: This element identifies the payee by ClientGUID.  The element is ignored if configured on policy level transactions and is required on client level transactions.  An error will be generated if this element is not part of a client-level activity.  The element cannot coexist with the <DisbursementRole> element.	math variable | field
	<DisbursementClient>	DISBURSEMENTAMOUNT	Required: This is the amount of disbursement.	math variable | field
<WithholddingFields>	<Disbursement>		Optional: The element allows the persistence of withholding amounts.  Any number of values may be defined in a comma delimited list of variables or fields valued with desired amounts that are considered withholding values.	comma delimited list of variables or fields
<DisbursementFields>	<Disbursement>		Optional: This is the opening of a structure to provide value to a disbursement's dynamic fields.
<DisbursementField>	<DisbursementFields>		Required, Repeatable: This will define the value to populate in a single dynamic field.
<From>	<DisbursementField>		Required: This element identifies the source of the data value for a dynamic field.	math variable | field
<To>	<DisbursementField>		Required: This element identifies the name of the dynamic field that is the target of the source data.	literal
<DataType>	<DisbursementField>		Required: This element identifies the data type of the disbursement's dynamic field.	Combo | Date | Decimal | Integer | Money | Text | TextArea

XML Schema

<Disbursement APPROVALSTATUS="[variable | field]" APPROVAL="[Yes | No]" CheckEFTInformation="[Yes | No]" DisbursementType="[variable | field]" METHOD="[Balanced | Unbalanced]" RECOVERABLE="[Yes | No]" TAXABLEAMOUNT="[variable | field]">
    <AddressDisplay>[variable | field]</AddressDisplay>
    <DisbursementRole TYPE="GUID" DISBURSEMENTAMOUNT="[variable | field]">[variable | field]</DisbursementRole>
    <DisbursementClient DISBURSEMENTAMOUNT="[variable | field]">[variable | field]</DisbursementClient>
    <WithholdingFields>[list]</WithholdingFields>
    <DisbursementFields>
        <DisbursementField>
            <From>[variable | field]</From>
            <To>[name]</To>
            <DataType>[Combo | Date | Decimal | Integer | Money | Text | TextArea]</DataType>
        </DisbursementField>
        <DisbursementField>...</DisbursementField>
    </DisbursementFields>
</Disbursement>

XML Example

<Disbursement APPROVAL="Yes" METHOD="Unbalanced" RECOVERABLE="No" DisbursementType="Activity:DisbursementMethod">
    <AddressDisplay>Activity:AddressGUID</AddressDisplay>
    <DisbursementClient DISBURSEMENTAMOUNT="DisbursementAmountMV">Activity:ClientGUID</DisbursementClient>
    <DisbursementFields>
        <DisbursementField>
            <From>FederalWithholdingMV</From>
            <To>TotalFederalWithholding</To>
            <DataType>Money</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>StateWithholdingMV</From>
            <To>TotalStateWithholding</To>
            <DataType>Money</DataType>
        </DisbursementField>
    </DisbursementFields>
</Disbursement> 

OR

<Transaction>
    <Withholding>Activity</Withholding>
    ...
    <Math>
        <MathVariables>
            ...
        </MathVariables>
        <Disbursement CheckEFTInformation="Yes" DisbursementType="DisbursementMethodMV" APPROVAL="Yes">
            <AddressDisplay>PayeeAddressGUIDMV</AddressDisplay>
            <DisbursementClient DISBURSEMENTAMOUNT="Activity:GrossAmount">Client:ClientGUID</DisbursementClient>
            <WithholdingFields>FederalWithholdingAmountMV, Activity:LocalAmountField, StateWithholdingMV</WithholdingFields>
        </Disbursement>
    </Math>
</Transaction>

OR

<Disbursement METHOD="Unbalanced" APPROVAL="Yes" DisbursementType="Activity:DisbursementTypeCode" TAXABLEAMOUNT="DisbursementTaxableAmountMV" RECOVERABLE="No">
    <AddressDisplay>Activity:PayeeAddressGUID</AddressDisplay>
    <DisbursementRole TYPE="GUID" DISBURSEMENTAMOUNT="DisbursementAmountAfterTaxesMV">Activity:RoleGUID</DisbursementRole>
    <DisbursementFields>
        <DisbursementField>
            <From>SurrenderChargesMV</From>
            <To>SurrenderCharges</To>
            <DataType>Money</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>EFTAccountNumberMV</From>
            <To>EFTAccountNumber</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>EFTRoutingNumberMV</From>
            <To>EFTRoutingNumber</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>EFTBankNameMV</From>
            <To>EFTBankName</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>EFTAccountTypeMV</From>
            <To>EFTAccountType</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>SpawnedByTransactionNameMV</From>
            <To>SpawnedByTransactionName</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>MVAAmountMV</From>
            <To>MVAAmount</To>
            <DataType>Money</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>FederalWithholdingTypeMV</From>
            <To>FederalWithholdingType</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>FederalWithholdingMV</From>
            <To>FederalAmount</To>
            <DataType>Money</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>FederalPercentMV</From>
            <To>FederalPercent</To>
            <DataType>Decimal</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>StateWithholdingTypeMV</From>
            <To>StateWithholdingType</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>StateWithholdingMV</From>
            <To>StateAmount</To>
            <DataType>Money</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>StatePercentMV</From>
            <To>StatePercent</To>
            <DataType>Decimal</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>DisbursementReasonMV</From>
            <To>DisbursementReason</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>AttentionMV</From>
            <To>Attention</To>
            <DataType>Text</DataType>
        </DisbursementField>
        <DisbursementField>
            <From>TaxYearMV</From>
            <To>TaxYear</To>
            <DataType>Integer</DataType>
        </DisbursementField>
    </DisbursementFields>
</Disbursement>