Installment
API name: cpm__Installment__c
Description
The Installment object is central to FinDock payment management. It represents an amount that is collected or paid out. The amount can change over time (e.g. due to refunds, late fees and so forth) and have multiple transactions (partial payments).
All monetary transactions that go through FinDock are linked to an Installment record. The Installment record types are:
- Receivable: you collect the amount from the payer
- Payable: you disburse or pay out the amount to another party
- Gift Aid: tax relief collected from the UK government through the Gift Aid scheme
Installment generation
For one-time payments, the Installment record is created as part of the payment acceptance (payment intent processing). For recurring payments, installment generation depends on the source. If a source connector is used, then the industry solution, such as Nonprofit Cloud, determines when an installment is generated off the back of an industry-specific record, like Gift Transaction.
When FinDock is the source (FinDock Standalone), there are two possible installment generation modes for recurring payments. The installments are either generated via FinDock Heart Beat or generated by payment schedules.
Fields
The following table outlines key fields. Installments include several "custom" fields, like Custom 1, Custom 2, etc. that can be used for your own business purposes. Other custom fields, like Custom Account Number, Custom Payment Reference, etc. are used for specific override scenarios.
| Label | Type | Description |
|---|---|---|
| Amount | Currency(16,2) | The full amount to be collected or disbursed. For recurring payments, the amount comes from the source-specific object for recurring collections. |
| Collection Count | Number(3, 0) | The number payments received for the installment |
| Due date | Date | The date the amount should be collected or disbursed. For recurring payments, the date is determined by the source-specific object for recurring collections. |
| Last Collection Date | Date | The date money was last received (credit), based on the most recent related Payment record. |
| Last Paid Date | Date | For payable installments, this is the date money was last disbursed (debit), based on the most recent related Payment record. |
| Open Amount | Currency(16,2) | The remainder of the full amount still to be collected or disbursed. |
| Original Due Date | Date | The original, intended due date for the installment. This field remains unchanged when Due Date is updated. |
| Payment Method | Picklist | The payment method intended for collecting or disbursing the amount. For recurring payments, the method comes from the source-specific object for recurring collections. The payment method for a specific installment can be changed as needed. |
| ProcessingHub Id | Text(255) | External Id of the synced record on ProcessingHub. NOTE: If you clone an installment, this field must be cleared. If the field is not empty, the next ProcessingHub process fails with a cardinality violation error. |
| Source | Picklist | The source of payment data where business logic payments management is implemented (e.g. FinDock Standalone or Fundraising). When not FinDock Standalone, the source indicates the installment data is synced with a source-specific object record. |
| Status | Picklist | The current processing status of the installment (see below) |
Status and counters
Every installment record has a status. Each status is considered either ‘open’ or ‘closed’ (similar to NPSP Opportunity stages). In addition to the Status field itself, the Installment object has to other fields used to manage status changes.
- Last [Status] Date: this date is stored on insert of a payment for the installment. If the installment has Failed and Cancelled status, today's date is stored on the installment on status change instead of on insert of a payment.
- # of times [Status]: stores the number of times the installment has changed to the given status.
| Status | Explanation | Installment Date Field | Installment Status Counter |
|---|---|---|---|
| Cancelled | This installment is cancelled and no payment is expected. | Last Cancelled Date (cpm__Last_Cancelled_Date__c) | # of times Cancelled (cpm__of_times_cancelled__c) |
| Collected | The (receivable) installment is paid for the full amount or more. | Last Collection Date (cpm__Last_Collection_Date__c) | Collection Count (cpm__Collection_Count__c) |
| Failed | This installment could not be processed; check the Last Status Reason field for details. | Last Failed Date (cpm__Last_Failed_Date__c) | # of times Failed (cpm__of_times_failed__c) |
| New | This installment is ready for processing | Open status, therefore not applicable. | Open status, therefore not applicable. |
| Outstanding | This installment is awaiting payment, but there is no active process to collect the money. | Open status, therefore not applicable. | Open status, therefore not applicable. |
| Paid | The installment has been paid out. Used for installments with record type Payable, but can also be applied to Receivable installments through customization. | Last Paid Date (cpm__Last_Paid_Date__c) | # of times Paid (cpm__of_times_paid__c) |
| Partially paid | A payment was collected, but not for the full amount of the receivable installment, so the Open Amount field is not 0 (zero). Can also apply to Payable installment, in which case it means the disbursed amount is not the full amount. | Open status, therefore not applicable. | Open status, therefore not applicable. |
| Pending | This installment is currently in processing and a result (positive or negative) is expected | Open status, therefore not applicable. | Open status, therefore not applicable. |
| Pending Processing | This installment is currently in processing and a result (positive or negative) is expected (this status is used for specific payment processors only) | Open status, therefore not applicable. | Open status, therefore not applicable. |
| Pending recollection | This installment was reversed, but is now scheduled for re-collection at the next collection run. | Open status, therefore not applicable. | Open status, therefore not applicable. |
| Refunded | This installment was 'Paid back' to the debtor, and no new payment is expected | Last Refunded Date (cpm__Last_Refunded_Date__c) | # of times Refunded (cpm__of_times_refunded__c) |
| Rejected | This installment was never paid, but has been rejected by the payment processor; the reason is stated in the Last ReasonCode Received field. | Last Rejected Date (cpm__Last_Rejection_Date__c) | # of times Rejected (cpm__of_times_rejected__c) |
| Reversed | This installment was paid, but has been reversed, the reason is stated in the Last ReasonCode Received field. | Last Reversal Date (cpm__Last_Reversal_Date__c) | # of times Reversed (cpm__of_times_reversed__c) |
Installment GUIDs and payment references
Every installment that is processed through FinDock is automatically assigned a GUID (Globally Unique Identifier). These identifiers can be used when referencing the installment in a link for instance.
Each installment record has a payment reference. This reference can come from different sources, so three fields are used:
- Custom Payment Reference: optional field for customized reference value
- Final Payment Reference: the reference value used for the installment
- Generated Payment Reference: an auto-generated reference value for the installment