# New Project Payments - Impact Analysis

## TL; DR;

From my findings, it does not seem that this will be a huge developement undertaking, the bulk of the work will definitely be regresion testing.

The dev work will be mostly isolated to a couple of scopes and methods under the `Project` and `ProjectPayment` models in addition to updating a couple of pages in Nitro so we start displaying the new payment methods. Some of the UI work can be potentially delegated to the teams owning the affected areas (at the moment mostly x-men).

## Frontend Views:

**Must regression test:**

- "Old" project payments page: Review payments information;
- Finance page: Review any payment-related and loan application information;
- New **Financials App** (x-men - currently behing a feature toggle / permission it seems): Review all payment-related information;
- Loan Application pages: Review financed amount to make sure it is accounting for the new payment types used as down payment, affecting the project balance to be financed;
- Project track tasks bound to payments or project balance: Need to confirm with Kraig which workflows need regression, the ones I found so far are all related to third party funding which should not be impacted by this work but we can smoke test to be safe;

**Must be updated:**

- Edit payment: This functionality will need to "talk" to Run Payments for payments created via their API;
- Void payment: This functionality will need to "talk" to Run Payments for payments created via their API;


- Finance project page: Needs to handle the new payment types;
- Project payments listing page (after project is submitted): Must now handle the new payment types (down payments via cc_token, ach_token, and pay at install payments);
- Financials app: Must now handle the new payment types (down payments via cc_token, ach_token, and pay at install payments). This is techincally x-men real so we need to see what the best way forward is.
- Installation crew appointments app: Must now handle the new payment types (down payments via cc_token, ach_token, and pay at install payments). This is techincally x-men real so we need to see what the best way forward is.

## Backend Logic:

**Must regression test:**

- When finance projects are created, Nitro may automatically create a loan application and apply for the financed amount. This amount needs to account for the new payment types being added so Nitro applies for the correct amount;

**Must be updated:**

It seems that updating the methods/scopes below will allow Nitro to successfully compute the project balance and generate project documents accounting for the new payment methods:

- [ProjectPayment.checks_or_credit scope](https://github.com/powerhome/nitro-web/blob/master/components/core_models/app/models/project_payment.rb#L89): This ActiveRecord scope is mostly used to query downpayments collected as credit cards or check. We need to update this so it can account for the new payment methods, e.g. `ach_token` and `cc_token`;
I'd recommend deprecating this scope in favor of a new one that aggregates all kinds of payment methods available for down payments (`down_payment_methods` for example). This would allow for a gradual migration, eventually allowing us to remove the deprecated scope while having a new abstraction that can capture the idea of down payments regardless of how they were captured, making it easier to add new payment methods in the future.
- [ProjectPayment#project_amendment_text](https://github.com/powerhome/nitro-web/blob/master/components/core_models/app/models/project_payment.rb#L234): This method is mostly used to generate project documents and it needs to account for the new payment methods `ach_token` and `cc_token`. We should check with UX and the business what label we want to show to users when listing these payments to them. For reference, Nitro currently only shows `Credit` and `Check`;
- [Project#current_payments](https://github.com/powerhome/nitro-web/blob/master/components/core_models/app/models/project.rb#L1573): Needs to account for the new payment methods `ach_token` and `cc_token`. This method is used to compute the monthly payment for [proposed loan plan](https://github.com/powerhome/nitro-web/blob/master/components/projects/app/graphql/projects/graphql/proposed_loan_plan_type.rb#L27) during the new payment intent flow and [estimates](https://github.com/powerhome/nitro-web/blob/master/components/core_models/app/models/estimate.rb#L666);
- When we start charging customers for `pay at install` payments Nitro will have to account for this new **payment_type** when computing the project's balance. These payments will not be included in that math until this change is made since they are not considered down payments.

## Project Documents:

**Must regression test:**

Any project document that deals with payments and project balance. Here're a few we know of:

- Sales Aggrements
- Project Amendment

Handling the backend logic described above should take care of the project documents and ensure they display info about the new payment methods correctly.

**NOTE:** will ping Kraig and our ninjas to get a little more insight around documents.

## Open Questions

1. When loans are created and RTPed by Nitro, are pay at install amounts being taken into consideration in order to compute the amount to be financed?
- No, Finance will always be the full project total (minus any down payment). We do not factor in pay at install amount into how much we are approving for financing.

2. For pay at install + finance projects, when the installation completes and we charge customers for the pay at install amount, at this point are we just updating the amount used on the loan application to account for the collected pay at install?
- The finance amount is currently automatically updating based on how much has already been captured. So as long as the it is looking at the new payment type, it will automatically factor that into how much financing will be used.
3. When we implement payment refund via RunPayments, will we have to keep loan applications in sync regarding the amount used or will the workflow prevent refunds by the time we fund the loan?
- In the current world, I believe voiding a payment will also automatically adjust the finance amount because that "captured" amount will no longer be factored.