Limitations and troubleshooting

What Mercury Banking for ERPNext does not do, and the errors and alerts it raises, with their causes and fixes.

Updated2026-10-26

On this page

Limitations

One company. Mercury Settings has a single Company. Every Bank Account, GL code and Journal Entry the app creates belongs to it.
US dollars only. Bank Transactions are created in USD, the invoicing gateway accepts only USD, and automatic journal entries post amounts without exchange rates.
GL codes are uploaded by hand. Mercury's API cannot create GL codes, so you export them from ERPNext and upload the file in Mercury after adding or renaming accounts. See Export your accounts as GL codes.
GL coding sends no event. Mercury sends no event when a transaction gets a GL code, and the hourly sync re-reads only the last 3 days. A transaction coded later is booked by the daily sweep, which costs one Mercury API call per unreconciled transaction in its window. Its Journal Entry is dated on the transaction's date, so a long backlog can post into a closed period.
Attachments are copied only with an automatic journal entry. A transaction that the app does not book keeps its receipts in Mercury.
Reconciled transactions are not changed. When Mercury changes the amount or status of a transaction whose Bank Transaction is already reconciled, the app sends an alert instead of changing it.
No webhooks in the sandbox. Mercury's sandbox has none, so events arrive only through the 15-minute poll there.
No ACH pulls. Mercury cannot debit a customer's account, so the customer pays from the pay page, with reminders when overdue.
Invoice emails with Mercury as sender. In ERPNext 16.51 a Payment Request submitted from the desk sends ERPNext's own email whatever the gateway answers, so with Invoice Email Sender set to Mercury the customer gets two emails. See Who emails the customer.
Card payments are matched by estimate. Card payouts arrive with the fee taken off, and the deposit is matched to its invoice within an estimated fee range. Leave Accept Credit Card off until you have checked a real settlement.
Ambiguous matches are never guessed. A deposit that fits several paid invoices, or a transfer with several candidate counter sides, is left for you to reconcile.
Internal transfers are paired by account number. The app finds the other side from the last four digits at the end of the counterparty name Mercury gives each side. Two Mercury accounts whose numbers end in the same four digits cannot be told apart.
Payouts are ACH only, from one funding account for payroll and one for suppliers.
Mercury's 24-hour duplicate rule. Mercury refuses a payment to the same payee, from the same account, for the same amount within 24 hours. The app marks it Blocked - Duplicate and allows a new attempt after 24 hours.

Troubleshooting

Errors shown in the desk are quoted as the app writes them; {0} stands for the name or value filled in. Alerts are emails to the Alert Recipients, with a subject that starts with [Mercury], and most failures are also in the Error Log.

Settings and bank sync

You see	Cause	Fix
"Mercury API token validation failed: {0}"	Saving with Enabled ticked, Mercury refused the token or could not be reached.	Check the token, and that Use Sandbox matches it (a sandbox token goes in Sandbox API Token).
"Mercury API Token is not set in Mercury Settings" (or "Mercury Sandbox API Token …")	The token for the chosen environment is empty.	Enter it and save.
"Mercury Integration is disabled"	An action that calls Mercury ran while Enabled was unticked.	Tick Enabled and save.
"Please setup a Bank account group in the Chart of Accounts for company {0} before syncing Mercury accounts"	Sync Accounts had to create a GL account and found no Bank group account.	Add a group account with the account type Bank under the company's assets, then sync again.
"Mercury did not return a webhook signing secret"	Mercury created the webhook without a secret.	Choose Register Webhook again.
Alert "Webhook verification failed"	The webhook is registered, but Mercury's test event did not reach the site.	Check that the site is reachable from the internet over HTTPS. The 15-minute poll covers events in the meantime.
Alert "Webhook was auto-disabled and has been reactivated"	Mercury turned the webhook off after failed deliveries; the daily check turned it on.	Check the site's availability. No event is lost: the poll picks them up.
Alert "Webhook is disabled and could not be reactivated"	As above, but turning it back on failed.	Choose Register Webhook again.
Alert "Bank Transaction {0} needs manual review"	Mercury changed the amount or status of a transaction whose Bank Transaction is reconciled.	Unreconcile it, then cancel or amend it by hand to match Mercury.
A Mercury account's transactions do not appear	Its Bank Account is disabled or has no Mercury Account ID, or Automatic Transaction Sync is off.	Run Sync Accounts, tick Automatic Transaction Sync, or use Backfill Transactions.
An Integration Request with status Failed	Processing an event raised an error, shown on the record and in the Error Log.	Fix the cause, then choose Replay Events for a period that covers it.

Automatic journal entries and transfers

You see	Cause	Fix
Alert "Auto journal skipped for {0}" saying "GL code … matches no account name in …"	No enabled ledger account of the company has that exact Account Name.	Rename the account, or fix the GL code in Mercury. Export and upload the GL codes again.
The same alert saying the GL code "is ambiguous"	Two or more accounts share the name.	Rename one of them.
The same alert saying the account "needs a party"	The GL code is a Payable or Receivable account and the Mercury counterparty is not linked to an Employee or Supplier.	Link the payee with Match Mercury Contact (see Payouts).
The same alert saying "GL allocations total … but the transaction is …"	Part of the transaction has no GL code in Mercury.	Code every split in Mercury.
The same alert saying the account "which a bank transaction cannot post against"	The GL code names an Asset account.	Use a Liability, Income, Expense or Equity account.
The same alert saying "Mercury Settings has no Company set"	Company is empty.	Set it.
Alert "Auto journal entry failed for {0}"	ERPNext refused the Journal Entry, for example a closed accounting period or a missing accounting dimension.	Read the Error Log entry, fix the cause, and let the daily sweep book it.
Alert "Daily backfill skipped {0} transaction(s)"	The daily sweep found coded transactions it could not book. Each is listed with its reason.	Fix each reason as above. The digest repeats daily until they are booked or reconciled.
A coded transaction is not booked and no alert came	It has no attachment and Require Attachment is ticked, it is above Maximum Amount, or it is already reconciled.	Attach the receipt in Mercury, raise the limit, or book it by hand.
Alert "Ambiguous internal transfer for {0}"	More than one transfer on the other account fits.	Reconcile both sides in the Bank Reconciliation Tool.
Alert "Internal transfer auto-reconcile failed for {0}"	Booking the Bank Entry raised an error.	Read the Error Log entry and reconcile the pair by hand.
"Enable Mercury Settings → Auto Journal Entries before applying"	The `reevaluate_unreconciled` command ran with `"dry_run": false` while the setting is off.	Tick Enable Auto Journal Entries, or run a dry run.
"Enable Mercury Settings → Auto Reconcile Internal Transfers before applying"	The `reconcile_existing_transfers` command ran with `"dry_run": false` while the setting is off.	Tick Auto Reconcile Internal Transfers, or run a dry run.
"Some accounts cannot be exported"	Export GL Codes found account names that are shared or contain a comma, quotation mark or line break.	Rename the listed accounts if you want them as GL codes.
"No accounts are eligible for export."	The company has no enabled Liability, Income, Expense or Equity ledger account, or Company is empty.	Set the Company and check its chart of accounts.

Invoicing

You see	Cause	Fix
"Please select another payment method. Mercury does not support transactions in currency '{0}'"	The Payment Request is not in USD.	Use another gateway for that currency.
Alert "Invoice creation failed for {0}"	Creating the Mercury invoice failed on submit; the Error Log has the reason.	Fix the reason below; the hourly retry or Recreate Mercury Invoice then creates it.
"Customer {0} needs an email address before Mercury invoicing"	Neither the Payment Request's To nor the Customer has an email address.	Add one, then choose Recreate Mercury Invoice.
"Mercury AR invoicing requires a Customer party on the Payment Request"	The Payment Request's party is not a Customer.	Mercury invoices are for customers only.
"Mercury Settings: the AR destination Bank Account has no Mercury Account ID; run Sync Accounts first"	The Destination Bank Account is not linked to Mercury.	Run Sync Accounts, or pick a Mercury Bank Account.
"The Mercury AR gateway is disabled in Mercury Settings"	A Mercury invoice was requested while Enable AR Gateway is off.	Tick it and save.
"Mercury invoice {0} is {1}; money is in flight. Settle or refund it in Mercury before cancelling this Payment Request."	You cancelled a Payment Request whose invoice is processing or paid.	Settle or refund the payment in Mercury first.
Alert "Settlement failed for {0}"	The invoice is paid in Mercury but the Payment Entry could not be made.	Read the Error Log entry, fix the cause (often the reference document), and the next poll tries again.
Alert "Mercury invoice cancelled upstream for {0}"	Someone cancelled the invoice in Mercury.	Nothing to fix; raise a new Payment Request if the customer still owes the amount.
Alert "Ambiguous AR funding match for {0}"	A deposit fits more than one paid invoice.	Reconcile the deposit in the Bank Reconciliation Tool.
Alert "Card fee account missing for {0}"	A card deposit matched an invoice, but Card Fees Account is empty.	Set it, then reconcile the deposit by hand.
Alert "Final reminder sent for {0}"	The Payment Request has had Maximum Reminders reminders.	Follow up with the customer yourself.

Payouts

You see	Cause	Fix
"Mercury payouts are disabled in Mercury Settings"	Enable Payouts is off.	Tick it and save.
"No funding Bank Account configured in Mercury Settings for {0} payouts"	The Payroll Funding Bank Account or Vendor Funding Bank Account is empty.	Set it.
"Funding Bank Account {0} has no Mercury Account ID; run Sync Accounts"	The funding Bank Account is not linked to Mercury.	Run Sync Accounts, or pick a Mercury Bank Account.
"{0} {1} has no active Mercury recipient" (payout status `Failed`)	The Employee or Supplier is not an `Active` recipient.	Onboard them (see Payouts), then pay again.
"{0} {1} has no email address for the Mercury invite"	Send Mercury Invite found no email on the Employee or Supplier.	Add one, or use Enter Bank Details Directly.
"{0} {1} is already linked to Mercury contact {2}", "That Mercury contact is already linked to {0} {1}"	Match Mercury Contact would link a payee or contact twice.	Check which record should own the contact.
"No unmatched contacts"	Every active Mercury contact is already linked.	Send an invite to onboard a new payee.
"No submitted salary slips found for this Payroll Entry."	The Payroll Entry has no submitted salary slips.	Submit the salary slips first.
"Only supplier payments (type Pay) can be sent via Mercury"	The Payment Entry is not a payment to a Supplier.	Only supplier payments can be sent.
"Payment Entry has already cleared the bank"	The Payment Entry has a Clearance Date.	It has been paid already.
"Mercury's 24h duplicate guard is still active"	The document is `Blocked - Duplicate` and its last attempt was less than 24 hours ago.	Wait until 24 hours have passed, or check whether the first payment went through.
"payout already {0}"	The document already has a payout in progress or reconciled.	Nothing to send.
Alert "Payout failed for {0}" or "Payout blocked - duplicate for {0}"	Mercury refused the payment, or reported a sent payment as failed; the alert quotes Mercury's answer.	Fix the cause (often the token's scope or the IP allow list for `Direct Send`) and pay again.
Alert "Payout cancelled for {0}", "Payout reversed for {0}" or "Payout blocked for {0}"	Mercury cancelled, reversed or blocked the payment after it was sent; the alert quotes its reason. The status becomes `Failed`.	Fix the cause with the payee or in Mercury and pay again.
Alert "Payout rejected in Mercury for {0}" or "Payout cancelled in Mercury for {0}"	A Mercury user rejected or cancelled the approval request.	Pay again if the payment is still due.
Alert "Payroll payouts failed for {0}"	One or more salary slips failed; the alert lists them.	Fix each and use Pay via Mercury again; slips already paid are not ticked.
"Salary Slip {0} has a Mercury payout in flight (status: {1}). Wait for it to fail or reverse before cancelling."	You cancelled a salary slip whose payment is under way.	Wait for the payment to finish or fail, or cancel it in Mercury first.
A payout stays `Sent` or `Posted`	Its Bank Transaction has not landed, Auto Reconcile Payouts is off, or the payroll bank entry has not been made.	Sync transactions, tick Auto Reconcile Payouts, or use Make Bank Entry on the Payroll Entry; the daily job reconciles it.