Document FreeAgent bank feeds transaction direction

cspell.json

@@ -242,6 +242,7 @@
     "XLSB",
     "Xero's",
     "Xero",
+    "Xfer",
     "YNAB",
     "Yundt",
     "yzth",

docs/bank-feeds/pushing-transactions.md

@@ -18,6 +18,8 @@ Collect transaction data within your own application and map it to Codat's [Bank
 
 :::caution Transaction signs
 Make sure the transaction `amount` signs align with the `transactionType`. Codat issues a warning for inconsistencies, such as a `Debit` transaction with a positive amount.
+
+Some accounting platforms take the direction of a transaction from its `transactionType` rather than the sign of the `amount`. FreeAgent works this way for some types, and Codat adjusts transfers to honor the sign you send. See [Write bank transactions to FreeAgent](/integrations/bank-feeds/freeagent-bank-feeds/freeagent-bank-feeds-push-bank-transactions).
 :::
 
 ## Write bank transactions

docs/integrations/bank-feeds/freeagent-bank-feeds/freeagent-bank-feeds-push-bank-transactions.md

@@ -0,0 +1,45 @@
+---
+title: "Write bank transactions to FreeAgent"
+sidebar_label: Write bank transactions
+description: "Learn how to write your SMB users' bank transactions via our FreeAgent Bank Feeds integration"
+---
+
+When an SMB user has set up a bank feed connection, you can write bank transactions for source bank accounts to FreeAgent. Write them using the [Create bank transactions](/bank-feeds-api#/operations/create-bank-transactions) endpoint, as described in [Write transactions](/bank-feeds/pushing-transactions).
+
+## Prerequisites
+
+- Your SMB user has an authorized FreeAgent connection and has [established a bank feed](/bank-feeds/mapping/overview).
+
+## Transaction direction can come from the type
+
+In Codat's bank transactions schema, the sign of the `amount` determines the direction of a transaction: positive is money in, negative is money out. The `transactionType` describes the kind of transaction.
+
+For some transaction types, FreeAgent takes the direction from the `transactionType` and overrides the sign of the `amount`. `Xfer` is one of these types: FreeAgent always treats a transfer as money out.
+
+Written as sent, a transaction with `amount: 1.60` and `transactionType: Xfer` would be £1.60 out in FreeAgent, while integrations that use the sign, such as Xero and QuickBooks Online, record £1.60 in.
+
+## Codat converts a positive transfer
+
+To keep the direction consistent with the `amount` you send, Codat writes a positive `Xfer` transaction to FreeAgent as `OTHER`. FreeAgent uses the sign for `OTHER` in both directions, so the transaction is recorded as money in, matching the sign of the `amount`.
+
+A negative `Xfer` isn't converted, because the type and the sign already agree.
+
+### The type appears in the description
+
+FreeAgent includes the transaction type in the description that the SMB user sees against the bank transaction. A transaction sent as `Xfer` reads as `//XFER/`, followed by the amount:
+
+```text
+your-transaction-description//XFER/£1.60
+```
+
+Because a positive `Xfer` is written as `OTHER`, the SMB user sees `//OTHER/` instead:
+
+```text
+your-transaction-description//OTHER/£1.60
+```
+
+### SMB users explain the transfer themselves
+
+Because the transaction arrives as `OTHER` rather than `Xfer`, FreeAgent doesn't suggest a transfer when your SMB user explains it.
+
+They can still explain it as a transfer exactly as they do now, using the **Transfer from Another Account** option. They select it themselves instead of FreeAgent proposing it.

docs/integrations/bank-feeds/freeagent-bank-feeds/freeagent-bank-feeds.md

@@ -0,0 +1,27 @@
+---
+title: "FreeAgent Bank Feeds"
+displayed_sidebar: integrationsBankFeeds
+description: "Learn about our FreeAgent Bank Feeds integration"
+---
+
+Our FreeAgent Bank Feeds integration allows you to set up a bank feed from a bank account in your application (the source bank account) to an account within FreeAgent (the target bank account). After a feed connection is established, you can write bank transactions from the source account to the target account.
+
+Bank feeds functionality is part of our existing [FreeAgent accounting integration](/integrations/accounting/freeagent/accounting-freeagent).
+
+## Supported data types and operations
+
+Bank feeds are represented as streams of [Bank account transactions](/bank-feeds-api#/schemas/BankTransactions) written to Codat in chronological order. Target bank accounts are represented as [Bank feed accounts](/bank-feeds-api#/schemas/BankFeedAccount).
+
+## How it works
+
+1. [Create a company and a data connection](/bank-feeds/create-account) using the `fbrh` platform key.
+
+2. Your SMB users authorize the connection with FreeAgent using our [Link auth flow](/auth-flow/overview).
+
+3. Your SMB users create account mappings and feed connections. See [Establish a bank feed](/bank-feeds/mapping/overview).
+
+4. Using the [Create bank transactions](/bank-feeds-api#/operations/create-bank-transactions) endpoint, you write bank transactions to Codat for authenticated users. See [Write bank transactions to FreeAgent](/integrations/bank-feeds/freeagent-bank-feeds/freeagent-bank-feeds-push-bank-transactions).
+
+## Read next
+
+[Write bank transactions to FreeAgent](/integrations/bank-feeds/freeagent-bank-feeds/freeagent-bank-feeds-push-bank-transactions)

docs/integrations/bank-feeds/overview.md

@@ -18,7 +18,7 @@ Read more about our [Bank Feeds](/bank-feeds/overview) solution.
 - [Xero](/integrations/bank-feeds/xero-bank-feeds/)
 - [NetSuite](/integrations/bank-feeds/netsuite-bank-feeds/netsuite-bank-feeds-setup)
 - [Exact Online (NL)](/integrations/accounting/exact-online/accounting-exact-online)
-- [FreeAgent](/integrations/accounting/freeagent/accounting-freeagent)
+- [FreeAgent](/integrations/bank-feeds/freeagent-bank-feeds/)
 
 ## Relevant solutions
 

sidebars/bank-feeds.js

@@ -82,7 +82,7 @@ module.exports = [
   },
   {
     type: "link",
-    href: "/integrations/accounting/freeagent/accounting-freeagent",
+    href: "/integrations/bank-feeds/freeagent-bank-feeds",
     label: "FreeAgent",
   },
   {

sidebars/integrations-bank-feeds.js

@@ -72,8 +72,16 @@ module.exports = [
     label: "Exact Online (NL)",
   },
   {
-    type: "link",
-    href: "/integrations/accounting/freeagent/accounting-freeagent",
+    type: "category",
     label: "FreeAgent",
+    collapsed: true,
+    items: [
+      {
+        type: "doc",
+        label: "Overview",
+        id: "integrations/bank-feeds/freeagent-bank-feeds/freeagent-bank-feeds",
+      },
+      "integrations/bank-feeds/freeagent-bank-feeds/freeagent-bank-feeds-push-bank-transactions",
+    ],
   },
 ];