[Payment due @mananjadhav] Add the Xero currency conversion fee account picker

[ishpaul777]

Explanation of Change

When a company covers the currency conversion cost on a cross-border reimbursement, its bank is debited more than the employee receives. We post that extra cost to Xero as a spend money transaction, and it needs an expense account to book it to. This adds the picker that nominates it, on the Xero advanced page next to the existing bill payment and invoice collections rows.

The list comes from a new expenseAccounts collection on the Xero connection data, holding profit and loss accounts only. The bank account list Xero ships today would park the cost on the balance sheet where it never reaches the P&L.

The row and the selector are both gated on the globalReimbursementFX beta and on the workspace reimbursing through Expensify, since that is the only setup where this cost arises. That condition lives in useCanConfigureCurrencyConversionFees so every surface exposing these settings agrees on it. The row also sits inside the reimbursed report sync accordion, because paying a Xero bill is what posts the cost.

Fixed Issues

$ https://github.com/Expensify/Expensify/issues/672453
PROPOSAL: N/A, internal

Tests

Automated coverage: tests/unit/PolicyUtilsTest.ts for the account list mapping, tests/actions/connections/Xero.test.ts for the optimistic write, the failure rollback, and the missing policy ID case.

Manual:

1. Connect a workspace to Xero and sync it, with Workflows > Payments set to pay through Expensify.
2. Go to Workspace > Accounting > Xero > Advanced.
3. Turn on Sync reimbursed reports.
4. Confirm a "Xero currency conversion fee account" row appears under the bill payment account row.
5. Tap it and confirm the list holds expense accounts.
6. Pick one, confirm it saves and the row shows the account name.
7. Reopen the selector and confirm that account is the selected one.
8. Type in the search box and confirm the list filters.
9. Turn off Sync reimbursed reports and confirm the row is hidden with the rest of the accordion.
10. Set Workflows > Payments back to paying outside Expensify and confirm the row is gone.

• Verify that no errors appear in the JS console

Offline tests

1. Go offline.
2. Pick a different account.
3. Confirm the row updates optimistically and greys out.
4. Go back online and confirm the choice sticks.

QA Steps

Same as tests. Requires a Xero connected workspace on the globalReimbursementFX beta that reimburses through Expensify.

• Verify that no errors appear in the JS console

PR Author Checklist

• I linked the correct issue in the ### Fixed Issues section above
• I wrote clear testing steps that cover the changes made in this PR
  • I added steps for local testing in the Tests section
  • I added steps for the expected offline behavior in the Offline steps section
  • I added steps for Staging and/or Production testing in the QA steps section
  • I added steps to cover failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
  • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
  • I tested this PR with a High Traffic account against the staging or production API to ensure there are no regressions (e.g. long loading states that impact usability).
• I included screenshots or videos for tests on all platforms
• I ran the tests on all platforms & verified they passed on:
  • Android: Native
  • Android: mWeb Chrome
  • iOS: Native
  • iOS: mWeb Safari
  • MacOS: Chrome / Safari
• I verified there are no console errors (if there's a console error not related to the PR, report it or open an issue for it to be fixed)
• I followed proper code patterns (see Reviewing the code)
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I followed the guidelines as stated in the Review Guidelines
• I tested other components that can be impacted by my changes (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar are working as expected)
• If a new CSS style is added I verified that:
  • A similar style doesn't already exist
  • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG))
• If new assets were added or existing ones were modified, I verified that:
  • The assets are optimized and compressed (for SVG files, run npm run compress-svg)
  • The assets load correctly across all supported platforms.
• If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
• If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
• If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
• If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
  • I verified that all the inputs inside a form are aligned with each other.
  • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
• I added unit tests for any new feature or bug fix in this PR to help automatically prevent regressions in this user flow.
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.

Screenshots/Videos

Android: Native

Android: mWeb Chrome

iOS: Native

iOS: mWeb Safari

MacOS: Chrome / Safari

Screen.Recording.2026-08-23.at.4.06.20.PM.mov

[melvin-bot]

Hey, I noticed you changed src/languages/en.ts in a PR from a fork. For security reasons, translations are not generated automatically for PRs from forks.

If you want to automatically generate translations for other locales, an Expensify employee will have to:

1. Look at the code and make sure there are no malicious changes.
2. Run the Generate static translations GitHub workflow. If you have write access and the K2 extension, you can simply click: [this button]

Alternatively, if you are an external contributor, you can run the translation script locally with your own OpenAI API key. To learn more, try running:

npx bun ./scripts/generateTranslations.ts --help

Typically, you'd want to translate only what you changed by running npx bun ./scripts/generateTranslations.ts --compare-ref main

[codecov]

Codecov Report

✅ Changes either increased or maintained existing code coverage, great job!

Files with missing lines	Coverage Δ
src/CONST/index.ts	91.22% <ø> (ø)
src/SCREENS.ts	100.00% <ø> (ø)
src/hooks/useCanConfigureCurrencyConversionFees.ts	100.00% <100.00%> (ø)
src/libs/API/types.ts	100.00% <ø> (ø)
...gation/linkingConfig/RELATIONS/WORKSPACE_TO_RHP.ts	100.00% <ø> (ø)
src/libs/Navigation/linkingConfig/config.ts	71.42% <ø> (ø)
src/libs/PolicyUtils.ts	80.36% <100.00%> (+0.02%)	⬆️
src/libs/actions/connections/Xero.ts	26.20% <100.00%> (+12.53%)	⬆️
src/pages/workspace/accounting/utils.tsx	14.21% <ø> (ø)
.../workspace/workflows/tabs/WorkflowsPaymentsTab.tsx	75.53% <100.00%> (ø)
... and 7 more
... and 8 files with indirect coverage changes

[melvin-bot]

@mananjadhav Please copy/paste the Reviewer Checklist from here into a new comment on this PR and complete it. If you have the K2 extension, you can simply click: [this button]

[mananjadhav]

Got this assigned today. Will pick this up tomorrow first thing.

[trjExpensify]

The list comes from a new expenseAccounts collection on the Xero connection data, holding profit and loss accounts only. The bank account list Xero ships today would park the cost on the balance sheet where it never reaches the P&L.

Out of curiosity, why do we need a new collection to limit this to expenseAccounts? For the list of chartOfAccounts that we show as categories imported Xero, those accounts have to have "Show in expense claims" checked on the account on the Xero side to show up in Expensify as categories - doesn't that achieve the same thing?

The row and the selector are both gated on the globalReimbursements and globalReimbursementFX betas, and the selector is also blocked unless reimbursed report sync is on, since that is the only path that pays a Xero bill and therefore the only path that posts the cost.

I understand the second beta, as that's this feature in development. What's with the globalReimbursements beta though. Isn't global reimbursement a feature available to everyone? 🤔

Outside of the world of beta lingo, is this feature in the accounting settings gated on a workspace with a bank account configured for global reimbursement?

CC: @heyjennahay for vis too.

[ishpaul777]

Out of curiosity, why do we need a new collection to limit this to expenseAccounts?

Two issues with reusing the categories list:

• It filters on Xero's Type field, which only counts plain EXPENSE accounts unless "Show in expense claims" is checked. Xero splits regular expenses from Direct Costs and Overheads as separate types, so those would be silently left out of the FX picker unless someone happened to check that box on them too.
• It also includes Revenue accounts , since those are needed for invoice collection. We don't want revenue accounts as an option for where to book a cost.

The new expenseAccounts list filters on Xero's ClassType instead, which is the broader P&L grouping that correctly includes Direct Costs and Overheads and excludes Revenue.

What's with the globalReimbursements beta though. Isn't global reimbursement a feature available to everyone?

this still exists on backend list of betas, and we only allow USD and AUD currency to bypass the beta

https://github.com/Expensify/Web-Expensify/blob/445a9f7ef5410f600179becdb036944f03c4a41f/lib/PolicyAPI.php#L5269-L5272

is this feature in the accounting settings gated on a workspace with a bank account configured for global reimbursement?

No, just the two account-level betas plus "Sync reimbursed reports" being on, so without a cross-border bank account would still see the row, it just would never end up posting anything since no FX fee would ever occur. Should we hide it in this scenario?

[trjExpensify]

It also includes Revenue accounts , since those are needed for invoice collection. We don't want revenue accounts as an option for where to book a cost.

Why do we want a revenue account to book an employee's expense to?

What's with the globalReimbursements beta though. Isn't global reimbursement a feature available to everyone?

this still exists on backend list of betas, and we only allow USD and AUD currency to bypass the beta

https://github.com/Expensify/Web->Expensify/blob/445a9f7ef5410f600179becdb036944f03c4a41f/lib/PolicyAPI.php#L5269-L5272

The globalReimbursements beta has * in Betaify, which means it's released to everyone and obsolete as a beta gate. So I think it needs to be killed in the code and not have more code written to be conditional on having it. CC: @madmax330 @joekaufmanexpensify

is this feature in the accounting settings gated on a workspace with a bank account configured for global reimbursement?

No, just the two account-level betas plus "Sync reimbursed reports" being on, so without a cross-border bank account would still see the row, it just would never end up posting anything since no FX fee would ever occur. Should we hide it in this scenario?

I don't think this accounting configuration should show on a workspace that is not even configured to do cross-border reimbursements, no. I think it will just confuse them. Curious to hear what @heyjennahay thinks about that too.

[ishpaul777]

Why do we want a revenue account to book an employee's expense to?

we dont thats why we cant reuse the categories list which has revenue accounts and this new list filters those out, so only real expense-type accounts (including Direct Costs and Overheads, which the categories list can also miss) show up as valid places to book the cost

The globalReimbursements beta has * in Betaify, which means it's released to everyone and obsolete as a beta gate. So I think it needs to be killed in the code and not have more code written to be conditional on having it.

okay good to know, then i think it no-op I'll make the change to remove it from here and later in some other PR from other code

[trjExpensify]

we dont thats why we cant reuse the categories list which has revenue accounts and this new list filters those out, so only real expense-type accounts (including Direct Costs and Overheads, which the categories list can also miss) show up as valid places to book the cost

Let me rephrase. Why would an expense, created by an employee and categorised, be okay to book to a revenue account - but is so egregious to show here to the point where we created a totally new coding import grouping for the list.

Basically on the one hand you're saying it's not okay to show revenue accounts in this selector because you shouldn't be able to book expenses to that account type, but on the other you're saying revenue accounts appear in the categories list for employees to book expenses to.

To me, it feels like there might be an opportunity to align the default lists used for the two instead of maintaining two separate.

I'm OOO now until next Tuesday, but I've asked Jenna to have eyes on this (if she hasn't already).

[madmax330]

The globalReimbursements beta has * in Betaify, which means it's released to everyone and obsolete as a beta gate. So I think it needs to be killed in the code and not have more code written to be conditional on having it.

Yeah agree, although here it's combines with the FX beta, so it doesn't matter.

[ishpaul777]

Sorry, I think I muddled this. Let me start over.

What this PR adds: one setting, the Xero expense account we post the company-paid conversion cost to. When the company covers the conversion its bank is debited more than the employee receives, and we post that difference to Xero as a spend money transaction. That line has to land on an expense account.

Why the lists we already have don't fit:

• bankAccounts, which the bill payment and invoice rows use, holds bank accounts only. Booking the cost there leaves it on the balance sheet and it never reaches the P&L.

• The chartOfAccounts list which is categories list has three problems:

  • It would be missing accounts. Every Xero account has a type, and several types are really expenses: Expense, Direct Costs, Overheads, Depreciation and Wages. Our category import only brings in plain Expense on its own. A customer who keeps their spend in Overheads accounts would open this picker and find it empty. Ticking "Show in expense claims" is one way to pull the other types in, but it is not required for an account to become a category (code), so we cannot rely on it being set.
  • It contains accounts a cost must not go to. Revenue accounts are in there for invoicing. We prefix them Invoice - on import precisely to keep them apart from expense accounts.
  • It is not really a list of Xero accounts. After import we merge it with the categories the workspace already had, including hand-typed ones with no Xero account behind them. An entry being in that list does not mean there is a live Xero account to post to.

It is not a new import. We already fetch every Xero account in one call and discard most of them. This is a second filter over the same response on ClassType == EXPENSE, Xero's own profit and loss expense grouping, which is what catches Direct Costs and Overheads and leaves revenue out

Let me know if I have misunderstood your question or got any of this wrong.

[mananjadhav]

Reviewing and waiting for this product discussion ^

[melvin-bot]

I could not review this diff, so I did not approve the workflow runs. An Expensify employee will review it and approve them manually.

[mananjadhav]

Yes. I am reviewing this again.

[mananjadhav]

I totally missed asking one question.

• Do we need to add FX_EXPENSE_ACCOUNT from [subscribedAdvancedSettings](https://github.com/Expensify/App/blob/d58c78efb4acd82154b74f1bae185d119b7b96ef/src/pages/workspace/accounting/utils.tsx#L229-L233), so a failed/offline save won’t brick-road Accounting → Advanced.

[mananjadhav]

@ishpaul777 Last few questions, rest I've started with the checklist.

[mananjadhav]

Reviewer Checklist

• I have verified the author checklist is complete (all boxes are checked off).
• I verified the correct issue is linked in the ### Fixed Issues section above
• I verified testing steps are clear and they cover the changes made in this PR
  • I verified the steps for local testing are in the Tests section
  • I verified the steps for Staging and/or Production testing are in the QA steps section
  • I verified the steps cover any possible failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
  • I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
• I checked that screenshots or videos are included for tests on all platforms
• I included screenshots or videos for tests on all platforms
• I verified that the composer does not automatically focus or open the keyboard on mobile unless explicitly intended. This includes checking that returning the app from the background does not unexpectedly open the keyboard.
• I verified tests pass on all platforms & I tested again on:
  • Android: HybridApp
  • Android: mWeb Chrome
  • iOS: HybridApp
  • iOS: mWeb Safari
  • MacOS: Chrome / Safari
• If there are any errors in the console that are unrelated to this PR, I either fixed them (preferred) or linked to where I reported them in Slack
• I verified proper code patterns were followed (see Reviewing the code)
  • I verified that comments were added to code that is not self explanatory
  • I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
  • I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
• If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
• I verified that this PR follows the guidelines as stated in the Review Guidelines
• I verified other components that can be impacted by these changes have been tested, and I retested again (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar have been tested & I retested again)
• If a new component is created I verified that:
  • A similar component doesn't exist in the codebase
  • All props are defined accurately
  • The component has a clear name that is non-ambiguous and the purpose of the component can be inferred from the name alone
  • The only data being stored in the state is data necessary for rendering and nothing else
  • The component has the minimum amount of code necessary for its purpose, and it is broken down into smaller components in order to separate concerns and functions
• If a new CSS style is added I verified that:
  • A similar style doesn't already exist
  • The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG)
• If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
• If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
• If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
• If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
• If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
  • I verified that all the inputs inside a form are aligned with each other.
  • I added Design label and/or tagged @Expensify/design so the design team can review the changes.
• For any bug fix or new feature in this PR, I verified that sufficient unit tests are included to prevent regressions in this flow.
• If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.
• I have checked off every checkbox in the PR reviewer checklist, including those that don't apply to this PR.

Screenshots/Videos

Android: HybridApp

android-xero-fx-fee.mov

Android: mWeb Chrome

mweb-chrome-xero-fx-fee.mov

iOS: HybridApp

iOS: mWeb Safari

mweb-safari-xero-fx-fee.mov

MacOS: Chrome / Safari

xero-fx-fee-account-picker.mov

xero-fx-disabled.mov

[mananjadhav]

@trjExpensify @ishpaul777 Two quick questions:

1. There's no option to unselect the item from the list or unset the option. May be expected or can be a follow up?

2. Items with long text are chipped off and can't be read. I think this is existing for all the providers.

[mananjadhav]

LGTM, ask 2 questions on the behavior but can be follow up.

[melvin-bot]

🎯 @mananjadhav, thanks for reviewing and testing this PR! 🎉

A payment issue will be created for your review once this PR is deployed to production.
E/E issue linked to the PR - https://www.github.com/Expensify/Expensify/issues/672453.

If payment is not needed (e.g., regression PR review fix etc), react with 👎 to this comment to prevent the payment issue from being created.

[melvin-bot]

I could not review this diff, so I did not approve the workflow runs. An Expensify employee will review it and approve them manually.

[ishpaul777]

Do we need to add FX_EXPENSE_ACCOUNT from subscribedAdvancedSettings, so a failed/offline save won’t brick-road Accounting → Advanced

fixed this one

There's no option to unselect the item from the list or unset the option. May be expected or can be a follow up?

i will follow up on this if we want to do this 👍

[github-actions]

🚧 madmax330 has triggered a test Expensify/App build. You can view the workflow run here.

[OSBotify]

✋ This PR was not deployed to staging yet because QA is ongoing. It will be automatically deployed to staging after the next production release.

[github-actions]

🧪🧪 Use the links below to test this adhoc build on Android, iOS, and Web. Happy testing! 🧪🧪
Built from App PR #98806.

Android 🤖	iOS 🍎
https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-android-Adhoc-ebf29ea-067d20d-ad4294a655742939f5d568b7bb94823c9a70b6a8/index.html	https://ad-hoc-expensify-cash.s3.us-east-1.amazonaws.com/rock-artifacts/ad-hoc/rock-ios-device-AdHoc-ebf29ea-067d20d-4dccfa43a839a15fee09635070195ccef1a2c453/index.html

Web 🕸️
https://98806.pr-testing.expensify.com

---

👀 View the workflow run that generated this build 👀

[OSBotify]

🚀 Deployed to staging by https://github.com/madmax330 in version: 9.4.78-0 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

[MelvinBot]

Yes — help site changes are required. Draft PR: #101137

The Xero currency conversion fee account row this PR adds isn't documented anywhere in docs/articles, and neither is the pre-existing QuickBooks Online equivalent whose visibility condition this PR changes.

What the docs PR changes:

File	Change
Configure-Xero.md	Adds a Xero currency conversion fee account bullet to the advanced settings list, between the bill payment account and invoice collections account bullets, matching the row order in XeroAdvancedPage.tsx
Configure-Quickbooks-Online.md	Adds the matching QuickBooks Online currency conversion fee account bullet, which was never documented, plus the new "pays through Expensify" condition

How the copy was verified

• Label text comes verbatim from src/languages/en.ts — xeroFxExpenseAccount: 'Xero currency conversion fee account' and qboFxExpenseAccount: '<integration> currency conversion fee account'.
• The described behavior ("posts that cost to this account in Xero as a spend money transaction") comes from fxExpenseAccountDescription in the same file.
• Visibility conditions come from useCanConfigureCurrencyConversionFees (workspace reimburses through Expensify) plus the row's placement inside the Sync reimbursed reports accordion in both XeroAdvancedPage.tsx and QuickbooksAdvancedPage.tsx. The globalReimbursementFX beta gate is intentionally not mentioned — help articles don't reference internal betas.
• Accounting, Workflows, and Payments were confirmed against the live web UI. The Xero Advanced page itself couldn't be opened in the test session because connecting Xero requires two-factor authentication, so those labels were taken from the source strings and the existing article.
• Both bullets match the surrounding list style, punctuation, and bolding in each article per HELPSITE_NAMING_CONVENTIONS.md and HELP_AUTHORING_GUIDELINES.md. No structural changes were made, so neither article's existing heading structure was touched.

I skipped the Currency conversion fees setting under Workflows > Payments — it's also undocumented, but it predates this PR, which only renamed the hook it uses.

@ishpaul777, please review the linked help site PR and confirm it reflects the current behavior. Then mark the linked help site PR Ready for review

---

view run · no recording available

[jponikarchuk]

Deploy Blocker #101166 was identified to be related to this PR.

[jponikarchuk]

This PR failing because of the issue #101166
This issue is reproducible in: All platforms

[OSBotify]

🚀 Deployed to production by https://github.com/luacmartins in version: 9.4.78-3 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

Bundle Size Analysis (Sentry):

• Android

[melvin-bot]

🤖 Payment issue created: #101258