Fee Structures
Overview
In the Canopy system, fees are applied based on predefined configurations and policies. These fees can be associated with specific product plans and promotional offers, allowing flexibility in fee customization. Additionally, lenders have the option to create and configure their own custom fees, either individually or as part of a fee group.
You can select from a predefined set of events or triggers that determine when fees will be assessed. There are no restrictions on the number of fees that can be created, providing lenders with the ability to tailor fee structures to their specific needs. For instance, a lender may choose to assess a fee for every completed purchase or impose a late fee if the minimum payment is not received by the due date.
Having the ability to customize fee calculations and grace periods helps you optimize your fee management processes, ensure accurate and fair fee assessments, and maintain compliance with regulatory guidelines. It allows lenders to design fee structures that are transparent, consistent, and aligned with their business goals, ultimately leading to improved operational efficiency and borrower satisfaction.
Fee Relations
Events
Lenders can associate fees with specific events, such as fee surcharge, late payment, or recurring fees. The Canopy system supports recurring fees with interval configurations. For example, you can set these intervals to fire every month.
Line Items
Various types of fee line items are available to represent different fees, including origination fees, late fees, recurring fees, and manual fees. Fee line items provide details such as total amounts and specific parameters for fee calculation. The Canopy system will also provide information related to the payment status for fees. Here is a line of the fee line items we support today:
Fee Payment Pouring
While there are regulations for how much of a payment can pour into fees, the default behavior for the Canopy payment pouring logic is: fees, interest, and principal (respectively). However, Canopy will work with enterprise customers to customize fees with the support of our Client Delivery team.
Late Fee Grace Period
The Canopy system offers the ability to customize and control fee calculations related to loan cycles. This includes setting the grace period for late fees.
This flexibility is important because it controls how fees are calculated and applied to borrowers. You can set the grace period for late fees as the number of days after a payment is late. If a payment is not made to satisfy the minimum expected payment, then the account will move into a suspended-delinquent status.
Waiving Fees
In the Canopy system, you have the capability to waive fees by referencing the line item ID of the original fee that needs to be waived (Waive a fee for an account).
Waiving fees can be beneficial in cases where you want to provide exceptions, demonstrate goodwill, or address unique circumstances faced by borrowers. Additionally, the ability to waive fees can also help in managing compliance and regulatory requirements.
Webhooks
The Canopy system utilizes webhooks for real-time notifications on line item creation, line item updates, and account updates.
This helps you stay informed and receive immediate notifications about critical events and changes in the system. It also enables you to automate workflows and trigger specific actions based on the received notifications. For example, upon receiving a line item creation notification, you can automatically initiate certain processes or send notifications to internal teams or borrowers. Similarly, with line item updates or account update notifications, you can proactively respond to changes, take necessary actions, or update their internal systems.
Fee Types and Configuration
Understanding how fees function within the Canopy system will help you effectively configure, manage, and customize fee structures according to your lending program's specific needs. It allows you to optimize fee assessment, revenue generation, and overall borrower experience.
| Type | Description |
|---|---|
| AM_FEE | A subset of recurring fee -- amortized for installments |
| CREDIT_OFFSET_FEE | Line item fee can be configured to trigger after processing a credit offset |
| FEE | A subset of recurring fee -- amortized for revolving |
| LATE_FEE | Configured during the account creation request via late_fee_cap_percent |
| MANUAL_FEE | A manual fee can be created in the CanopyOS UI or via an API endpoint |
| MONTH_FEE | monthly_fee_cents can be configured during the account creation request |
| ORIG_FEE | Configured during the account creation request via the following parameters: origination_fee_cents origination_fee_percent is_origination_fee_lesser_value is_origination_fee_amortized |
| ORIG_FEE_FOR_AM | |
| PAYMENT_REVERSAL_FEE | Line item fee can be configured to trigger after processing a payment reversal. This fee is configured during the account creation request via payment_reversal_fee_cap_percent |
| RECURRING_FEE | recurring_fees parameter allows you to set the interval, total amount in cents, any initial delay offsets, fee interval flooring and a label to describe the recurring fee |
| RETURN_CHECK_FEE | Line item fee can be configured to trigger after a check has been returned |
| YEAR_FEE | annual_fee_cents can be configured during the account creation request |
Retroactive Processing
A payment reversal, charge reversal, or fee waiver could result in additional fees given the new state of the account. For example, if a payment reversal was executed, this could cause the account to be in a suspended - delinquent state with fees generate. This would reflect the updated account state as if the payment was never made.
Additionally, you can use the Preview feature to see what types of fees would be incurred if a payment reversal was made to the account.
Step-by-Step Guide
Here is a sample request and response for creating an account - inclusive of what fees you could include during the account creation process:
Sample Request
{
"effective_at": "2016-11-27T13:19:56+00:00",
"account_id": "31mNprzLd2bKl6koVna68ARM",
"product_id": "31mNprzLd2bKl6koVna68ARM",
"partner_entity_id": "1234",
"external_fields": [
{
"key": "Umbrella Corporation",
"value": "22445702-a389-431f-927d-07b8d0750787"
}
],
"payment_processor_config": {
"ach": {
"payment_processor_name": "REPAY",
"repay_config": {
"repay_check_type": "PERSONAL",
"repay_account_type": "CHECKING",
"repay_transit_number": "999999992",
"repay_account_number": "987654321",
"repay_name_on_check": "Lucille Bluth"
},
"dwolla_config": {
"dwolla_plaid_token": "processor-sandbox-161c86dd-d470-47e9-a741-d381c2b2cb6f"
},
"modern_treasury_config": {
"name": "Lucille Bluth",
"account_number": "987654321",
"account_type": "CHECKING",
"routing_number": "999999992",
"plaid_processor_token": "processor-987654321"
},
"canopy_nacha_config": {
"bank_routing_number": "999999992",
"bank_account_number": "987654321",
"bank_account_type": "CHECKING"
},
"stripe_config": {
"customer_id": "cus_4QE4bx4C5BVSrC",
"source_id": "string",
"external_fields": {}
},
"galileo_config": {
"plaid_processor_token": "processor-production-35cd43b-adfc-d8aa-b331-c9ba0fdha881"
}
},
"debit_card": {
"payment_processor_name": "REPAY",
"repay_config": {
"repay_card_number": "4622941000000005",
"repay_exp_date": "0619",
"repay_name_on_card": "John Doe",
"repay_street": "1234 Main Street",
"repay_zip": "85281"
},
"authorize_net_config": {
"card_number": "4622941000000005",
"expiry_month": "string",
"expiry_year": "string",
"cvv": "string"
}
},
"credit_card": {
"payment_processor_name": "CHECKOUT",
"checkout_config": {
"source_id": "cus_6artgoevd77u7ojah2wled32s",
"card_token": "string",
"card_number": "string",
"expiry_month": "string",
"expiry_year": "string",
"cvv": "string"
}
},
"autopay_enabled": true,
"autopay_configs": {
"autopay_method": "TOTAL_BALANCE",
"autopay_fixed_amount_cents": 2500
},
"default_payment_processor_method": "ACH"
},
"disbursements_config": {
"disbursement_source_payout_entity_id": 1009,
"disbursement_split_percentages": {
"principal": [
{
"payout_entity_id": 1009,
"split_percent": 25
}
]
}
},
"payouts_config": {
"payout_split_percentages": {
"principal": [
{
"payout_entity_id": 1009,
"split_percent": 25
}
],
"interest": [
{
"payout_entity_id": 1009,
"split_percent": 25
}
],
"fee": [
{
"payout_entity_id": 1009,
"split_percent": 25
}
]
}
},
"cycle_type": {
"first_cycle_interval": "11 days",
"late_fee_grace": "2 days"
},
"discounts": {
"prepayment_discount_config": {
"loan_discount_cents": 800000,
"loan_discount_at": "2018-03-20T09:12:28+00:00"
}
},
"summary": {
"credit_limit_cents": 400000,
"max_approved_credit_limit_cents": 400000,
"late_fee_cents": 2900,
"payment_reversal_fee_cents": 2900,
"origination_fee_cents": 2000,
"origination_fee_percent": 2.34,
"is_origination_fee_lesser_value": false,
"is_origination_fee_amortized": false,
"annual_fee_cents": 1000,
"monthly_fee_cents": 500,
"recurring_fees": [
{
"recurring_fee_interval": "1 month",
"recurring_fee_amount_cents": 10000,
"initial_delay_offset": "12 days",
"is_fee_interval_floored": false,
"recurring_fee_label": "Quarterly Fee"
}
],
"initial_principal_cents": 400000,
"late_fee_cap_percent": 12.5,
"payment_reversal_fee_cap_percent": 6.2,
"interest_accrual_interval": "1 day",
"interest_grace_method": "NONE",
"min_pay_applicable_credit_type": "ALL"
},
"promo_overview": {
"promo_len": 500,
"promo_min_pay_type": "PERCENT_PRINCIPAL",
"promo_min_pay_floor_cents": 500,
"promo_purchase_window_len": 500,
"promo_min_pay_percent": 100,
"promo_impl_interest_rate_percent": 6.2
},
"post_promo_overview": {
"post_promo_impl_interest_rate_percent": 6.2,
"post_promo_len": 48
},
"associated_entities": {
"merchant_name": "Acme Corporation",
"lender_name": "Globex Lending Corp"
},
"plaid_config": {
"plaid_access_token": "access-sandbox-614910f9-3754-4c40-9f9b-9c8aecb36bca",
"plaid_account_id": "Rpb6w775kaSr89z3RgxpSWvnjwKKPWizmkAN4",
"check_balance_enabled": true
},
"assign_customers": [
{
"customer_id": "31mNprzLd2bKl6koVna68ARM",
"customer_account_role": "SECONDARY",
"customer_account_external_id": "4465220133024156",
"designation": "INDIVIDUAL"
}
],
"metro2_config": {
"bloom_metadata": {
"branch_identifier": "string",
"customer_designations": [
{
"customer_id": "string",
"designation": "INDIVIDUAL"
}
]
}
}
}
Sample Response
{
"account_id": "31mNprzLd2bKl6koVna68ARM",
"created_at": "2017-06-20T09:12:14+00:00",
"updated_at": "2019-02-20T09:12:14+00:00",
"effective_at": "2018-03-20T09:12:28+00:00",
"account_overview": {
"account_status": "SUSPENDED",
"account_status_subtype": "BANKRUPTCY",
"is_active_scra": "false"
},
"account_product": {
"product_id": "prod_4p1sc",
"product_overview": {
"product_name": "Blue Cash Express",
"product_color": "#0000FF",
"product_short_description": "Consumer credit card",
"product_long_description": "Student credit card.",
"product_time_zone": "America/Chicago",
"product_type": "REVOLVING"
},
"product_lifecycle": {
"late_fee_impl_cents": 2900,
"default_product_late_fee_cents": 2900,
"payment_reversal_fee_impl_cents": 2900,
"default_product_payment_reversal_fee_cents": 2900,
"origination_fee_impl_cents": 2000,
"origination_fee_percent": 12.34,
"is_origination_fee_lesser_value": false,
"is_origination_fee_amortized": false,
"annual_fee_impl_cents": 1000,
"monthly_fee_impl_cents": 500,
"recurring_fees": [
{
"recurring_fee_interval": "1 month",
"recurring_fee_amount_cents": 10000,
"initial_delay_offset": "12 days",
"is_fee_interval_floored": false,
"recurring_fee_label": "Quarterly Fee"
}
],
"loan_end_date": "2013-01-13T05:25:13.813+00:00"
},
"promo_overview": {
"promo_purchase_window_inclusive_start": "2013-01-13T05:25:13.813+00:00",
"promo_purchase_window_exclusive_end": "2013-01-13T05:25:13.813+00:00",
"promo_inclusive_start": "2013-01-13T05:25:13.813+00:00",
"promo_exclusive_end": "2013-01-13T05:25:13.813+00:00",
"promo_impl_interest_rate_percent": 6.2,
"default_product_promo_interest_rate": 6.2,
"promo_len": 6,
"default_product_promo_len": 6
},
"post_promo_overview": {
"post_promo_inclusive_start": "2013-01-13T05:25:13.813+00:00",
"post_promo_exclusive_end": "2013-01-13T05:25:13.813+00:00",
"post_promo_impl_interest_rate_percent": 6.2,
"default_product_post_promo_interest_rate": 6.2,
"post_promo_len": 48,
"default_product_post_promo_len": 48
},
"product_duration_information": {
"promo_len": 6,
"promo_purchase_window_len": 5
}
},
"external_fields": [
{
"key": "Umbrella Corporation",
"value": "22445702-a389-431f-927d-07b8d0750787"
}
],
"min_pay_due_cents": {
"statement_min_pay_cents": 160000,
"min_pay_cents": 160000,
"min_pay_due_at": "2019-10-18T23:04:48.321+00:00"
},
"additional_min_pay_details": {
"min_pay_fees_cents": 20000,
"current_min_pay_cents": 400000,
"unpaid_min_pay_cents": 400000
},
"additional_statement_min_pay_details": {
"statement_min_pay_charges_principal_cents": 100000,
"statement_min_pay_interest_cents": 30000,
"statement_min_pay_am_interest_cents": 200,
"statement_min_pay_deferred_cents": 10000,
"statement_min_pay_am_deferred_interest_cents": 200,
"statement_min_pay_fees_cents": 20000,
"statement_payments_cents": 20000,
"previous_statement_min_pay_cents": 400000,
"statement_current_min_pay_cents": 400000,
"statement_unpaid_min_pay_cents": 400000
},
"payment_processor_config": {
"ach": {
"payment_processor_name": "REPAY",
"repay_config": {
"ach_token": "string",
"last_four": "string"
},
"dwolla_config": {
"ach_token": "string",
"last_four": "string"
},
"modern_treasury_config": {
"ach_token": "string",
"last_four": "string"
},
"canopy_nacha_config": {
"bank_routing_number": "999999992",
"bank_account_number": "987654321",
"bank_account_type": "CHECKING"
},
"stripe_config": {
"customer_id": "cus_4QE4bx4C5BVSrC",
"source_id": "string",
"external_fields": {}
},
"galileo_config": {
"plaid_processor_token": "processor-production-35cd43b-adfc-d8aa-b331-c9ba0fdha881"
}
},
"debit_card": {
"payment_processor_name": "REPAY",
"repay_config": {
"card_token": "string",
"last_four": "string"
},
"authorize_net_config": {
"customer_profile_id": "527262",
"customer_payment_profile_ids": [
"86"
]
}
},
"credit_card": {
"payment_processor_name": "CHECKOUT",
"checkout_config": {
"source_id": "cus_6artgoevd77u7ojah2wled32s",
"card_token": "string",
"last_four": "string",
"expires_on": "string"
}
},
"autopay_enabled": true,
"autopay_configs": {
"autopay_method": "TOTAL_BALANCE",
"autopay_fixed_amount_cents": 2500
},
"default_payment_processor_method": "ACH"
},
"disbursements_config": {
"disbursement_source_payout_entity_id": 1009,
"disbursement_split_percentages": {
"principal": [
{
"payout_entity_id": 1009,
"split_percent": 25
}
]
}
},
"payouts_config": {
"payout_split_percentages": {
"principal": [
{
"payout_entity_id": 1009,
"split_percent": 25
}
],
"interest": [
{
"payout_entity_id": 1009,
"split_percent": 25
}
],
"fee": [
{
"payout_entity_id": 1009,
"split_percent": 25
}
]
}
},
"issuer_processor_details": {
"lithic": {
"account_token": "349e2031-20de-40c6-87a3-214895077522"
},
"galileo": {
"account_token": "406101000684"
}
},
"cycle_type": {
"first_cycle_interval": "11 days",
"late_fee_grace": "2 days"
},
"discounts": {
"prepayment_discount_config": {
"loan_discount_cents": 800000,
"loan_discount_at": "2018-03-20T09:12:28+00:00"
}
},
"summary": {
"total_balance_cents": 300000,
"principal_cents": 200000,
"interest_balance_cents": 60000,
"am_interest_balance_cents": 0,
"deferred_interest_balance_cents": 40000,
"am_deferred_interest_balance_cents": 0,
"fees_balance_cents": 0,
"initial_principal_cents": 200000,
"total_paid_to_date_cents": 40000,
"total_interest_paid_to_date_cents": 10000,
"credit_limit_cents": 400000,
"max_approved_credit_limit_cents": 400000,
"interest_rate_percent": 3,
"interest_accrual_interval": "1 day",
"interest_grace_method": "NONE",
"available_credit_cents": 100000,
"open_to_buy_cents": 5000,
"total_payoff_cents": 900000,
"pending_am_interest_balance_cents": 900000,
"late_fee_cap_percent": 12.5,
"payment_reversal_fee_cap_percent": 6.2
},
"associated_entities": {
"merchant_name": "Acme Corporation",
"lender_name": "Globex Lending Corp"
},
"plaid_config": {
"plaid_access_token": {
"valid_config": true
},
"plaid_account_id": {
"valid_config": true
},
"check_balance_enabled": true
},
"payout_entities": [
{
"payout_entity_id": "0x1234",
"payout_entity_type": "lender",
"payout_entity_name": "Wonka Industries",
"external_fields": [
{
"key": "Umbrella Corporation",
"value": "22445702-a389-431f-927d-07b8d0750787"
}
],
"parent_payout_entity_id": "31mNprzLd2bKl6koVna68ARM",
"bank_account_number": "1001001234",
"bank_routing_number": "012345678",
"bank_account_type": "CHECKING",
"company_identification": "X000100393",
"irs_tin": "203456789"
}
],
"cards": [
{
"spend_limit": 8000000,
"lithic": {
"token": "adccd28d-532e-480b-a063-a46a77a15570",
"card_program_token": "a5e38341-cc95-4a9b-a21c-751aeca67e9c",
"last_four": "0339",
"type": "UNLOCKED",
"state": "OPEN",
"memo": "Conference Event Card"
}
}
],
"customers": [
{
"address_line_one": "12 Strawberry Road",
"address_line_two": "Suite 101",
"address_city": "Atlanta",
"address_state": "GA",
"address_zip": "99999-1000",
"address_country_code": "US",
"name_prefix": "Dr.",
"name_first": "Miriam",
"name_middle": "Louise",
"name_last": "Trevino",
"name_suffix": "Jr",
"passport": {
"number": "string",
"country": "JP"
},
"customer_id": "31mNprzLd2bKl6koVna68ARM",
"created_at": "2017-06-20T09:12:14+00:00",
"updated_at": "2019-02-20T09:12:14+00:00",
"is_borrower_portal_user": true,
"customer_type": "person",
"is_active": true,
"verification_status": "verified",
"title": "CFO",
"phone_number": "+14105556789",
"ssn": "888888888",
"international_customer_id": "9999999999",
"email": "[email protected]",
"date_of_birth": "1985-06-20",
"customer_balances": {
"num_active_accounts": 2,
"total_balance_cents": 300000,
"principal_cents": 200000,
"interest_balance_cents": 60000,
"am_interest_balance_cents": 0,
"deferred_interest_balance_cents": 40000,
"am_deferred_interest_balance_cents": 0,
"fees_balance_cents": 0
},
"business_details": {
"business_legal_name": "Umbrella Corporation",
"doing_business_as": "Umbrella",
"business_ein": "888-888888",
"business_type": "llc",
"business_classification_id": "794D9D5E-B547-4B3B-8289-76484C1AFC5F",
"website": "https://example.com",
"controller": {
"address_line_one": "12 Strawberry Road",
"address_line_two": "Suite 101",
"address_city": "Atlanta",
"address_state": "GA",
"address_zip": "99999-1000",
"address_country_code": "US",
"name_prefix": "Dr.",
"name_first": "Miriam",
"name_middle": "Louise",
"name_last": "Trevino",
"name_suffix": "Jr",
"passport": {
"number": "string",
"country": "JP"
},
"title": "CFO",
"phone_number": "+14105556789",
"ssn": "888888888"
}
},
"metro2_config": {
"bloom_metadata": {
"address_type": "CONFIRMED",
"residence_type": "OWNS",
"account_designations": [
{
"account_id": "string",
"designation": "INDIVIDUAL"
}
]
}
}
}
],
"partner_entity": {},
"metro2_config": {
"bloom_metadata": {
"branch_identifier": "string",
"customer_designations": [
{
"customer_id": "string",
"designation": "INDIVIDUAL"
}
]
}
}
}
Related Articles
- API: Create a new account
- API: Create a manual fee for a specific account
- API: Waives a fee for an account
- Line Item Types
- Minimum Payments
- Account Status
- Webhooks
- Retroactive events for fee waivers
Updated over 1 year ago