Merge branch 'version-14' into supplier_payment

agritheory · Mar 26, 2024 · ea8189e · ea8189e
2 parents 8b34e83 + 843a8b5
commit ea8189e
Show file tree

Hide file tree

Showing 38 changed files with 1,633 additions and 311 deletions.
diff --git a/README.md b/README.md
@@ -2,57 +2,30 @@
 
 An application with electronic payments utilities for ERPNext.
 
-[TODO: create version-14 branch]
-
 ### Installation Guide
 
-First, set up a new bench and substitute a path to the python version to use. Python should be 3.8 latest for V13 and 3.10 latest for V14. These instructions use [pyenv](https://github.com/pyenv/pyenv) for managing environments.
+First, set up a new bench and substitute a path to the python version to use. Python should be 3.10 latest for `version-14`. These instructions use [pyenv](https://github.com/pyenv/pyenv) for managing environments.
 ```shell
-# Version 13
-bench init --frappe-branch version-13 {{ bench name }} --python ~/.pyenv/versions/3.8.12/bin/python3
-
-# Version 14
-bench init --frappe-branch version-14 {{ bench name }} --python ~/.pyenv/versions/3.10.3/bin/python3
+bench init --frappe-branch version-14 {{ bench name }} --python ~/.pyenv/versions/3.10.13/bin/python3
 ```
 
 Create a new site in that bench
 ```shell
 cd {{ bench name }}
 bench new-site {{ site name }} --force --db-name {{ site name }}
+bench use {{ site name }}
 ```
 
-Download the ERPNext app
+Download apps
 ```shell
-# Version 13
-bench get-app erpnext --branch version-13
-
-# Version 14
 bench get-app payments
 bench get-app erpnext --branch version-14
-```
-**Important note for benches installed with Python 3.10 or later:**
-
-If you created a bench using Python 3.10 or later, you must make the following manual fix to the Authorize.net package. The current state of the package does NOT support Python 3.10 ([see GitHub issue](https://github.com/AuthorizeNet/sdk-python/issues/154)) and the timing for this to be resolved is unknown.
-```
-# Activate the bench environment:
-source env/bin/activate
-
-# Install authorizenet package
-pip install authorizenet
-```
-Open the file `env/lib/python3.10/site-packages/pyxb/binding/content.py` and change line 799 from `import collections` to `import collections.abc as collections` and save your changes.
-
-Download the Electronic Payments application
-```shell
-bench get-app electronic_payments [email protected]:agritheory/electronic_payments.git 
+bench get-app electronic_payments --branch version-14 [email protected]:agritheory/electronic_payments.git 
 ```
 
 Install the apps to your site
 ```shell
-bench --site {{ site name }} install-app erpnext electronic_payments
-
-# Optional: Check that all apps installed on your site
-bench --site {{ site name }} list-apps
+bench --site {{ site name }} install-app erpnext payments electronic_payments
 ```
 
 Set developer mode in `site_config.json`
@@ -63,7 +36,7 @@ nano sites/{{ site name }}/site_config.json
 
 ```
 Install pre-commit:
-```
+```shell
 # ~/frappe-bench/apps/electronic_payments/
 pre-commit install
 ```
@@ -73,14 +46,14 @@ Add the site to your computer's hosts file to be able to access it via: `http://
 bench --site {{site name}} add-to-hosts
 ```
 
-Launch your bench (note you should be using Node.js v14 for a Version 13 bench and Node.js v16 for a Version 14 bench)
+Launch your bench (note you should be using Node.js v18)
 ```shell
 bench start
 ```
 
 Optional: install a [demo Company and its data](./exampledata.md) to test the Electronic Payments module's functionality
 ```shell
-bench execute 'electronic_payments.test_setup.before_test'
+bench execute 'electronic_payments.tests.setup.before_test'
 ```
 
 To run the Stripe mock, start the docker container:
@@ -90,7 +63,6 @@ docker run --rm -it -p 12111-12112:12111-12112 stripe/stripe-mock:latest
 The endpoint should be configured in the Electronic Payments Settings with the following values:
 ```json
 # values here / TBD
-
 ```
 
 To run `mypy` locally:

diff --git a/docs/assets/electronic_payment_settings.png b/docs/assets/electronic_payment_settings.png
diff --git a/docs/assets/ep_add_portal_payment_method.png b/docs/assets/ep_add_portal_payment_method.png
diff --git a/docs/assets/ep_adding_payment_method_dialog.png b/docs/assets/ep_adding_payment_method_dialog.png
diff --git a/docs/assets/ep_customer_portal_pmt_methods.png b/docs/assets/ep_customer_portal_pmt_methods.png
diff --git a/docs/assets/ep_desk_dialog.png b/docs/assets/ep_desk_dialog.png
diff --git a/docs/assets/ep_desk_ep_button.png b/docs/assets/ep_desk_ep_button.png
diff --git a/docs/assets/ep_edit_payment_method.png b/docs/assets/ep_edit_payment_method.png
diff --git a/docs/assets/ep_edit_remove_in_table.png b/docs/assets/ep_edit_remove_in_table.png
diff --git a/docs/assets/ep_journal_entry_workflow.png b/docs/assets/ep_journal_entry_workflow.png
diff --git a/docs/assets/ep_payment_entry.png b/docs/assets/ep_payment_entry.png
diff --git a/docs/assets/ep_payment_entry_gl_entries.png b/docs/assets/ep_payment_entry_gl_entries.png
diff --git a/docs/assets/ep_portal_discount.png b/docs/assets/ep_portal_discount.png
diff --git a/docs/assets/ep_portal_home.png b/docs/assets/ep_portal_home.png
diff --git a/docs/assets/ep_portal_payment_terms.png b/docs/assets/ep_portal_payment_terms.png
diff --git a/docs/clearing.md b/docs/clearing.md
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,3 +1,32 @@
-# Electronic Payments Configuration
+# Electronic Payments Configuration and Settings
 
-TO COME
+One Electronic Payment Settings document may be created for each Company in ERPNext. This document stores the Provider information (including API keys) and account information that's used in the chosen accounting workflow. Authorize.net requires both an API Key and a Transaction Key, whereas Stripe requires only the API Key. The keys should be the **testing/sandbox** values when testing the functionality of the application, and only updated to live keys when using the application in production.
+
+![Screen shot showing the fields in the Electronic Payment Settings document.](./assets/electronic_payment_settings.png)
+
+See below for information and default values for each field:
+
+- **Company:** (required) the company in ERPNext to apply all settings to - only one Electronic Payment Settings document may exist per company
+- **Provider:** Authorize.net or Stripe
+- **Merchant ID:** (optional) the company's ID associated with the provider
+- **API Key:** the company's API key with the given provider. These should be the sandbox key (Authorize.net) or the test keys (Stripe, the account should also be in test mode) when testing the application, and the live keys when in production
+- **Transaction Key:** (Authorize.net only) the company's transaction key with Authorize.net
+- **Automatically Create a Portal Payment Method when Electronic Payment Profile is Saved:** (default checked) when checked, if a desk user clicks the Electronic Payment button for an Order or Invoice, then enters payment information via the dialog box and selects to save the payment method, this automatically creates a Portal Payment Method for the party. When visiting the party's page, Portal Payment Methods are viewable and editable in the Electronic Payments tab
+
+**Accounts: Accepting Payments**
+- **Deposit Account:** the account that receives deposits from the provider after customer payments settle
+- **Provider Fee Account:** the account to hold any provider fees associated with transactions
+- **Payment Discount Account:** the account to net any payment discounts given to a customer (this field fetches the default payment discount account specified in Company Settings but is editable)
+- **Use Clearing Account:** (default Use Journal Entry and Clearing Account) whether to account for a successful electronic payment via a Journal Entry and Clearing account, or a Payment Entry. The differences between the two workflows is detailed on the [Electronic Payments Permissions and Workflows page](./permissions.md)
+- **Clearing Account:** account to use when the Use Journal Entry and Clearing Account option is selected. The accounting entries for an example transaction using a clearing account can be found on the [Electronic Payments Permissions and Workflows page](./permissions.md)
+
+**Accounts: Sending Payments**
+
+This feature is coming soon!
+<!-- uncomment and update screen shot when feature is merged  
+- **Enable Sending Electronic Payments:** (default unchecked) activate the ability for the given company to make electronic payments
+- **Withdrawal Account:** the account that sends payments to the provider after supplier payment transactions settle
+- **Payment Discount Account:** the account to net any payment discounts given to the company (this field fetches the default payment discount account specified in Company Settings but is editable)
+- **Provider Fee Account:** the account to hold any provider fees associated with transactions
+- **Clearing Account:** account to use when the Use Journal Entry and Clearing Account option is selected. The accounting entries for an example transaction using a clearing account can be found on the [Electronic Payments Permissions and Workflows page](./permissions.md)
+-->
diff --git a/docs/index.md b/docs/index.md
@@ -1,20 +1,60 @@
 # Electronic Payments Documentation
 
-The Electronic Payments application extends ERPNext[^1] with the capability to make electronic payments via several vendors directly in the system. The current supported vendors are [Authorize.net](www.authorize.net) and [Stripe](stripe.com).
+The Electronic Payments application extends ERPNext[^1] with the capability to send and receive electronic payments via several vendors directly in the system. The current supported vendors are [Authorize.net](www.authorize.net) and, with some limitations (see Provider Limitations section for details), [Stripe](stripe.com).
 
 ## Installation, Configuration, Settings, and Permissions
 
-There is some required prerequisite setup to get the Electronic Payments application up and running on your ERPNext site. See the following pages for details on installation, configuration, settings, and permissions:
+There are a few prerequisite steps to get the Electronic Payments application up and running on your ERPNext site. See the following pages for details on installation, configuration, settings, and permissions:
 
 - [Installation Guide](../README.md)
-- [Configuration](./configuration.md)
-- [Electronic Payments Settings](./settings.md)
-- [Default Permissions and Workflows](./permissions.md)
+- [Configuration and Settings](./configuration.md)
+- [Default Permissions and Accounting Workflows](./permissions.md)
+- Refer to the [Example Data page](./exampledata.md) for instructions around installing fictitious demo data to experiment with using the Electronic Payments app
 
-## Additional Electronic Payments Features
+## App Feature Overview
 
-Follow the links below for more information about features in the Electronic Payments application:
+Once the app is installed and configured, you can begin utilizing its features.
 
-- [Example Data: Experimenting with Electronic Payments Using Demo Data](./exampledata.md)
+Electronic Payments is set up to allow portal users to log in and add credit card (Stripe and Authorize.net) and ACH (Authorize.net only) payment methods associated with their account. Note that the payment method details are never saved on your system at any point. The app immediately passes the data to the provider API and, if the API successfully creates a payment method, it only saves the provider's token and last few account or card digits to identify that payment method.
+
+![Screen shot of the portal home screen for a customer, with the links to Manage Payment Methods page highlighted.](./assets/ep_portal_home.png)
+
+![Screen shot of the Manage Payment Method page with an empty table and the + New Payment Method button highlighted. The table has columns for Payment Type, Reference, Default, and Service Charge. There are two empty columns to the right, if a payment method is in the table, those would be to Edit or Remove it.](./assets/ep_add_portal_payment_method.png)
+
+![Screen shot of the dialog box to add payment method details - the shown fields will differ between a credit card and ACH account.](./assets/ep_adding_payment_method_dialog.png)
+
+The portal also allows the customer to remove or edit a saved payment method. When making changes to an existing method, they must re-enter all information, since it's not stored in ERPNext and providers don't allow requests for payment method details.
+
+![Screen shot showing the same Manage Payment Methods page but the table now shows a credit card available for use. There are now Edit and Remove options.](./assets/ep_edit_remove_in_table.png)
+
+There's an important consideration regarding the Electronic Payment Settings and payment methods being added via the portal. As noted in the [Configuration and Settings page](./configuration.md), Electronic Payment Settings are specified on a per-company basis. When a portal user adds a payment method, there's no way to associate it to a company, so the app uses the *default company* set in ERPNext to find the provider and API keys to use. This will link the payment method to the default company's provider account. For this reason, an Electronic Payments Settings document should always exist for the default company.
+
+In the desk view, stored payment methods are visible on the Electronic Payments tab in that party's page.
+
+![Screen shot showing a new tab on a Customer page for Electronic Payments. There's a table with one payment saved, which has a mode of payment of Credit Card, a label of Card-9711, the Default box checked, and the Subject to Credit Limit and Service Charge boxes unchecked.](./assets/ep_customer_portal_pmt_methods.png)
+
+Some payment method details may be edited from this view - if the party is subject to a credit limit, or if there are service charges that should be added when the party uses that payment method, those are configurable in the table.
+
+![Screen shot showing the edit detail of the payment method table in a Customer's page.](./assets/ep_edit_payment_method.png)
+
+When the customer is logged into the portal and has one or more payment methods set up, they can make a payment on an Order or Invoice directly from the portal. The app automatically integrates with the payment schedule defined on the Terms tab of the document, and will display payments spit out by payment term and showing any valid discounted amounts and due dates as necessary.
+
+If the provider accepts the payment and returns a success message, the app creates a Journal Entry or Payment Entry (depending how the Electronic Settings are configured) and updates the payment schedule.
+
+![Screen shot of the portal view of an invoice showing two payment terms, one is already paid and the other has a button to make a payment for that term's amount.](./assets/ep_portal_payment_terms.png)
+
+The app also allows a desk user to make an advance payment on a Sales Order or a payment on a Sales Invoice on a customer's behalf. The document's page will show an Electronic Payment button which launches a dialog box to put the payment through.
+
+![Screen shot showing the Electronic Payment button at the top of a Sales Invoice page in the desk view.](./assets/ep_desk_ep_button.png)
+
+![Screen shot showing the dialog box to make a payment using a saved payment method. The Mode of Payment is Saved Payment Method: Card 0002 and the Card Number is **** **** **** 0002.](./assets/ep_desk_dialog.png)
+
+## Provider Limitations
+
+There are some limitations with using Stripe as a provider. First, only credit card payment methods (not ACH ones) are configurable. Stripe uses its own mandate workflow (to verify that the customer allows making a charge to their bank account) that is currently not supported by the app. Second, given that sending payments to suppliers is only possible via an ACH payment method, that feature isn't available for Stripe.
+
+## Adding a Provider
+
+The Electronic Payments app maintainers welcome contributions to expand provider options beyond Stripe and Authorize.net. To be considered, a provider should have a comparable feature set to those of Authorize.net, including receiving credit card payments and sending and receiving ACH payments. Feature requests and pull requests can be made on the [app's GitHub repository](https://github.com/agritheory/electronic_payments).
 
 [^1]: [ERPNext](https://erpnext.com/) is an open-sourced Enterprise Resource Planning (ERP) software that provides a wide range of business management functionality. Its core features include support for accounting, inventory, manufacturing, customer relationship management (CRM), distribution, and retail.