Auto-reconcile GoCardless payouts in Xero and post to Slack

When GoCardless notifies us that a payout has been paid into our bank account (the GoCardless payout paid webhook event), automatically reconcile that payout in Xero and let the finance team know. Each GoCardless payout lands in our bank as a single net figure (customer collections minus GoCardless fees and any refunds), so the goal is to break that one deposit back into its parts and record a clean, balanced accounting entry that matches the bank statement line.

Start from the payout referenced in the webhook. Call GoCardless Get Payout to retrieve the payout's net amount, currency, payout reference, and payout date. Remember that GoCardless returns every monetary amount as an integer in the smallest currency unit (pence or cents), not as a decimal.

Then call GoCardless List Payout Items to pull the full itemized breakdown of what the payout covers, paging through every item. Sort the items into three buckets: gross customer collections (the payments that were successfully collected), refunds (money returned to customers), and GoCardless fees (transaction fees plus any app fees or scheme charges). Sum each bucket. A correct payout satisfies gross collections minus refunds minus fees equals the net amount from Get Payout, so use that identity as your integrity check.

Convert every amount from the smallest currency unit into the decimal amount Xero expects (for pound, euro, or dollar payouts, divide by 100). Then record the reconciliation in Xero with Create Manual Journals, posting a single balanced journal: credit the gross customer collections to our GoCardless clearing account (or the sales or debtors account we use), debit the GoCardless fees to a bank fees or merchant fees expense account, debit any refunds to the clearing or refunds account, and debit the net amount to the bank account the payout landed in so the imported statement line reconciles cleanly. Because net equals gross minus fees minus refunds, the total debits (net plus fees plus refunds) equal the total credits (gross), so the journal balances. If we prefer, the same entry can instead be recorded with Create Bank Transactions against the bank account using matching split lines.

Before posting anything, confirm the debits and credits are exactly equal and that the buckets tie back to the payout's net amount. If the numbers do not reconcile, or Xero rejects the journal, do not force a broken entry: skip posting and raise it for a human instead.

Finally, post a short summary to our finance Slack channel using the Slack bot's Send a Message action, showing the payout reference, gross collections, GoCardless fees, refunds, and net amount as human-readable currency, plus a note confirming the Xero journal was posted and is ready to reconcile against the bank line. Use Slack formatting for a tidy, scannable message. If reconciliation could not be completed automatically, post a clear heads-up in the same channel so finance can handle it manually.