From 323fff264113646598a5d6e2220c88fc3e14bdbf Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 3 Aug 2026 09:20:09 +0000 Subject: [PATCH] docs: document Wise payment-time errors and balance checks Update expense payment documentation for recent frontend/API changes: - Host-only Expense payment error activity on expense timeline - Upfront insufficient-balance check that keeps expense approved - Cross-link troubleshooting between Wise payment guides Co-authored-by: Benjamin Piouffle --- .../handling-payment-errors-through-wise.md | 12 +++++++++++- .../expense-payment/paying-expenses-with-wise.md | 12 ++++++++---- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/fiscal-hosts/expense-payment/handling-payment-errors-through-wise.md b/fiscal-hosts/expense-payment/handling-payment-errors-through-wise.md index b7db66f..f91c627 100644 --- a/fiscal-hosts/expense-payment/handling-payment-errors-through-wise.md +++ b/fiscal-hosts/expense-payment/handling-payment-errors-through-wise.md @@ -13,13 +13,23 @@ Many of our Fiscal Hosts use a third-party payment processor called Wise for pro If Wise encounters a problem, it may post a message saying that the expense has not been paid due to a certain error. You should be able to find these messages by checking your Fiscal Host's Wise dashboard. [There are some examples on the Wise website of the types of errors that may appear.](https://cw.wise-sync.com/support/solutions/36000125935) +When a payment fails at the time you try to pay an expense through Wise, Open Collective also records an **Expense payment error** entry in the expense activity timeline. This entry is **only visible to Fiscal Host admins** — it is not shown to the expense submitter or Collective admins, and it does not trigger a notification to the payee. Open the expense from **Dashboard > Outgoing Money** and scroll to the activity section to see the error message and troubleshoot. + Alternatively, the expense submitter may contact the Fiscal Host independently to inform them that they have not yet received the funds. +### Insufficient Wise balance + +Before creating a transfer on Wise, Open Collective checks that your connected Wise account holds enough funds in the payout currency. If the balance is too low, payment is blocked immediately with a message such as: + +> Insufficient balance in USD to cover this expense amount, you need 101.14 USD and you currently have 50 USD. Please add funds to your Wise USD account. + +In this case the expense **stays approved** (it is not marked as “Error”). Add funds to your Wise account and try paying again from **Dashboard > Outgoing Money > Pay Disbursements**. + ### Resolving payment errors -The expense may be marked with the status “Error” due to an automated payment error, or it can be given this status manually by a Fiscal Host if they discover it has not been paid. +For other payment-time failures (for example, invalid payout details or Wise API errors), the expense may be marked with the status “Error” due to an automated payment error. A host-only **Expense payment error** activity is added to the expense timeline with the details. You can also give an expense this status manually if you discover it has not been paid. {% hint style="info" %} If the expense submitter informs you independently that the expense has not been paid, you can manually change its status by clicking on the green “Paid” button to the right of the expense in question, and clicking “Mark as Unpaid”. diff --git a/fiscal-hosts/expense-payment/paying-expenses-with-wise.md b/fiscal-hosts/expense-payment/paying-expenses-with-wise.md index 110ea54..a397bb8 100644 --- a/fiscal-hosts/expense-payment/paying-expenses-with-wise.md +++ b/fiscal-hosts/expense-payment/paying-expenses-with-wise.md @@ -76,7 +76,11 @@ In order to reduce risks related to having an active API token that is able to c 2. Keep just enough balance in Wise to pay your expenses. * This can be achieved by calculating the amount needed for the current payment cycle and transferring it beforehand. -## Troubleshooting - -* `Unable to fund transfer` - * Double-check if you have enough funds in your Wise balance, you'll be using the balance with the same currency of your OpenCollective account. +## Troubleshooting + +* **Insufficient balance** + * Before creating a transfer, Open Collective checks your Wise balance in the payout currency. If funds are too low, payment is blocked with a clear message and the expense stays approved — add funds to Wise and try again. See [Handling Payment Errors Through Wise](handling-payment-errors-through-wise.md) for details. +* **`Unable to fund transfer`** + * Double-check if you have enough funds in your Wise balance. You'll be using the balance with the same currency as your Open Collective account. +* **Other payment failures** + * If Wise rejects a transfer for another reason, the expense is marked as “Error” and a host-only **Expense payment error** entry appears in the expense activity timeline. See [Handling Payment Errors Through Wise](handling-payment-errors-through-wise.md).