docs: update for billed as agreed, settings, workflows

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:

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)
+-->

docs/index.md

@@ -1,20 +1,28 @@
 # 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 receive electronic payments via several vendors directly in the system. The current supported vendors are [Authorize.net](www.authorize.net) and [Stripe](stripe.com).
+
+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 not 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. The Electronic Payments tab on the Customer page for that party shows a table with any stored payment methods.
+
+<!-- TODO: add screen shot to add a portal payment method -->
+
+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 provide accepts the payment and it successfully goes through, the app 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)
 
 ## 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:
 
 - [Installation Guide](../README.md)
-- [Configuration](./configuration.md)
-- [Electronic Payments Settings](./settings.md)
+- [Configuration and Settings](./configuration.md)
 - [Default Permissions and Workflows](./permissions.md)
-
-## Additional Electronic Payments Features
-
-Follow the links below for more information about features in the Electronic Payments application:
-
-- [Example Data: Experimenting with Electronic Payments Using Demo Data](./exampledata.md)
+- Refer to the [Example Data page](./exampledata.md) for instructions around installing fictitious demo data to experiment with using the Electronic Payments app
 
 [^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.

docs/permissions.md

@@ -1,3 +1,36 @@
-# Electronic Payments Permissions
+# Electronic Payments Permissions and Workflows
 
-TO COME
+## Permissions
+
+The Electronic Payments app integrates with ERPNext's existing documents and workflows. The app doesn't introduce any new roles or permission changes, but leverages the existing setup.
+
+- Users with the Role of System Manager may create and edit the Electronic Payments Settings for a company
+- Users with access to Sales Orders and Sales Invoices (and soon Purchase Orders and Purchase Invoices) will see an "Electronic Payments" button on those documents, enabling them to make a payment on behalf of a customer or to a supplier
+- Users with access to Customers or Suppliers are able to see that party's associated Portal Payment Methods on the Electronic Payments tab
+- Users with the Role of Customer or Supplier are able to add credit cards (and ACH accounts for Authorize.net) as payment methods via their portal access, and apply those payment methods on outstanding orders or invoices
+
+## Workflows
+
+As noted in the [Configuration and Settings page](./configuration.md), there are two distinct methods for posting an electronic payment - using a Journal Entry with a Clearing Account, or using a Payment Entry. The major difference between the two options is when the electronic payment reflects against the deposit account (for accepting payments) or the withdrawal account (when sending payments). With a Journal Entry and clearing account, when the electronic payment successfully clears, the balance amount moves off the accounts receivable or accounts payable associated with the party and onto the clearing account. Only after transactions settle would the user make the entries to offset the cash transfers to/from the provider against the clearing account. With a Payment Entry, when the electronic payment successfully clears, the transaction immediately reflects against the deposit or withdrawal account - there is no intermediate step with a clearing account.
+
+The following descriptions apply when accepting a payment from a customer, with differences noted when the transaction is for sending a payment to a supplier:
+
+**Journal Entry with Clearing Account**
+- When a payment successfully clears with the given provider, the system saves and submits a new Journal Entry for the individual transaction
+    - Accepting payments: the balance moves off of the Accounts Receivable account associated with the party. The paid amount (balance net any discounts and fees) is debited against the clearing account. Any fees the customer pays are credited against the fee account and any discounts (per terms in the order or invoice's payment schedule) are debited against the payment discount account. The clearing account, fee account, and payment discount account are specified in the Electronic Payment Settings document
+    - Sending payments: the balance moves off of the Accounts Payable account associated with the party. The paid amount (balance net any discounts and fees) is credited against the clearing account. Any fees the company pays are debited against the fee account and any discounts (per terms in the order or invoice's payment schedule) are credited against the payment discount account. The clearing account, fee account, and payment discount account are specified in the Electronic Payment Settings document
+- The app automatically integrates with the payment schedule and updates it when a payment successfully clears
+
+![Screen shot showing the debits and credits in a Journal Entry for an electronic payment of a sales invoice made by a customer. There is a credit to Accounts Receivable for the invoice total of $64.65, a debit to the clearing account for $64.94 (invoice total less a valid 2% discount for paying early of $1.29, plus fees of $1.58), a credit to the fee account for $1.58, and a debit to the payment discount account for $1.29.](./assets/ep_journal_entry_workflow.png)
+
+- When the provider settles transactions and transfers cash into the deposit account (or out of the withdrawal account, both specified in the Electronic Payment Settings document), the user can reconcile them against the clearing account
+
+**Payment Entry**
+- When a payment successfully clears with the given provider, the system saves and submits a new Payment Entry for the individual transaction
+    - Accepting payments: the References table logs the Order or Invoice with the balance amount. Any fees paid by the customer show in the Advance Taxes and Charges table and are associated with the fee account. If the reference document had a valid discount in its payment schedule, the discount amount shows in the Payment Deduction of Loss table and is associated with the payment discount account. The deposit account is used to receive the payment. The provider's transaction ID is stored in the Reference No. field. The deposit account, fee account, and payment discount account are specified in the Electronic Payment Settings document
+    - Sending payments: the References table logs the Order or Invoice with the balance amount. Any fees paid by the company show in the Advance Taxes and Charges table and are associated with the fee account. If the reference document had a valid discount in its payment schedule, the discount amount shows in the Payment Deduction of Loss table and is associated with the payment discount account. The withdrawal account is used to clear the payment. The provider's transaction ID is stored in the Reference No. field. The withdrawal account, fee account, and payment discount account are specified in the Electronic Payment Settings document
+- The app automatically integrates with the payment schedule and updates it when a payment successfully clears
+
+![Screen shot showing the generated Payment Entry against a Sales Invoice for $81.96 when the customer applied an electronic payment method. The Advance Taxes and Charges table shows the card fees paid by the customer of $2.01 and the Payment Deductions or Loss table reflects a valid 2% discount of $1.64 for paying early.](./assets/ep_payment_entry.png)
+
+![Screen shot showing the general ledger entries for an electronic payment made on a sales invoice. The invoice had payment terms of 2% discount if paid within 10 days, which the customer took advantage of. There's a credit to Accounts Receivable of $81.96 (total of the invoice), a debit to the deposit account of $82.33 (total less the discount amount plus fees), a debit to Sales (the payment discount account) of $1.64, and a credit to the fee account of $2.01](./assets/ep_payment_entry_gl_entries.png)