A2X Payout Reconciliation and Document Archival (n8n)

1. **Create Webhook Trigger**: Add a 'Webhook Node' in n8n. Set the HTTP Method to `POST`. Copy the Production URL and paste it into your A2X 'Outgoing Webhooks' settings. 2. **Configure A2X Credentials**: Create a 'Header Auth' credential in n8n to store your A2X API Key for subsequent GET requests. 3. **Fetch Settlement Document**: Add an 'HTTP Request' node. Use the `settlement_id` from the webhook to call the A2X API and download the PDF/CSV summary. Set the 'Response Format' to `File`. 4. **Data Transformation (The Code Node)**: Use a 'Code' node to transform the A2X JSON array into the specific QBO `Line` object format. Ensure debits and credits balance to zero using an expression like `{{ $json.total.amount }}`. 5. **Check for Ledger Accounts**: Add a 'QuickBooks Online' node with the 'Resource: Account' and 'Operation: Get All'. Filter by name to ensure the account exists before posting. 6. **Create Journal Entry**: Add a 'QuickBooks Online' node. Set 'Resource: Journal Entry' and 'Operation: Create'. Map the expressions from your Code node to the 'Line' parameter. 7. **Map Currency**: Use the n8n expression `{{ $json.currency || 'USD' }}` to handle multi-currency settlements dynamically via the QBO `CurrencyRef` field. 8. **Upload PDF Attachment**: Add another 'QuickBooks Online' node. Select 'Resource: Attachable' and 'Operation: Create'. Reference the `JournalEntryId` from the previous step and the binary file from Step 3. 9. **Implement Error Handling**: Create a 'Sticky Note' and an 'Error Trigger' node. Connect the Error Trigger to a 'Slack' or 'Email' node to notify the accounting team if a settlement fails due to a mapping error.

| A2X Field | QBO Field | n8n Expression / Transformation | Required | | :--- | :--- | :--- | :--- | | `settlement_id` | `DocNumber` | `{{ $json["id"] }}` | Yes | | `total_sales` | `Line:Credit` | `{{ parseFloat($json["sales"]) }}` | Yes | | `total_fees` | `Line:Debit` | `{{ Math.abs($json["fees"]) }}` | Yes | | `currency` | `CurrencyRef` | `{{ $json["currency_code"] }}` | Yes | | `payout_date` | `TxnDate` | `{{ $now.format('yyyy-MM-dd') }}` | Yes | | `summary_pdf` | `Attachable` | `{{ $binary.data }}` (Binary Object) | No |

• **Memory Limits**: Processing large settlement CSVs in n8n can hit memory limits if self-hosted. Use the 'Split in Batches' node if you are processing line-by-line rather than a summary. • **Strict Balancing**: QBO API will reject any Journal Entry where total debits do not exactly equal total credits. Use a 'Code' node to calculate a rounding difference line if necessary. • **MinorVersion Errors**: If using Taxes, ensure the 'Custom Query Parameters' in the n8n QBO node includes `minorversion=50` or higher. • **Rate Limiting**: QuickBooks Online has a limit of 40 requests per minute. Use n8n's 'Wait' node or 'Execute Once' settings if processing several years of historical data at once.

- [ ] **Webhook Validation**: Send a test payload from A2X and verify the 'Webhook Node' in n8n receives the `settlement_id`. - [ ] **Balance Check**: Verify the Code node output shows total debits minus total credits equals zero. - [ ] **Dry Run**: Execute the workflow up to the Journal Entry node using the 'Test Step' button in n8n. - [ ] **QBO Verification**: Log into the QBO Sandbox and ensure the Journal Entry appears with the 'A2X' reference in the memo. - [ ] **Attachment Check**: Open the Journal Entry in QBO and verify the PDF from n8n is clickable and readable.