Building an Amnis-Xero Integration: A Technical Deep Dive

How we connected international payments with accounting – and what the process actually looked like.

The problem: two systems that don’t talk

Swiss SMEs dealing with international suppliers and customers face a familiar pain: Amnis handles multi-currency payments beautifully, Xero manages the books with precision, but the two systems don’t talk to each other.

The result? Finance teams manually entering transactions, reconciling payments by hand, and spending hours on work that software should handle automatically.

We set out to build a proper Amnis-Xero integration — not a hacky workaround, but a robust, production-grade connector that could handle multi-currency complexity, scale across multiple clients, and fail gracefully when things go wrong.

Understanding the APIs

Both Amnis and Xero expose REST APIs with OAuth 2.0 authentication, but they behave quite differently in practice.

The Amnis API is well-documented and straightforward. The key endpoints we needed were:

• Transactions endpoint – fetches completed payments, incoming transfers, card expenses 
• Accounts endpoint – provides multi-currency balances and IBAN details
• FX rates endpoint – for accurate historical conversion tracking. 

Token management was required from day one since the API uses refresh tokens.

Xero’s API is more mature but also more complex. We focused on: 

• Bank Transactions – creating spend and receive transactions
• Bank Accounts – mapping Amnis accounts to Xero bank accounts
• Contacts – matching or creating supplier/customer records
• Tracking Categories – cost center  and project allocation

The main gotcha: Xero tokens expire after 30 minutes, which makes robust refresh handling critical – especially for background processes.

Bridging two different data models

This is where things got genuinely interesting. Amnis and Xero model financial data differently across the board.

We needed a translation layer that could map between these models while preserving data integrity and handling edge cases – not just the happy path.

Development approach: AI-assisted API mapping

One of the more useful aspects of this project was using AI automation to accelerate the API mapping work – something that would normally eat days of a developer’s time.

We fed both API specifications into Claude and asked it to identify matching fields between the two systems, required transformations (data types, formats, enums), edge cases and potential data loss points, and missing fields that would need default values or user input.

This gave us a solid first-pass mapping in hours rather than days.

For the repetitive work of writing transformation functions, we used AI assistance to generate initial implementations. The key was treating AI output as a starting point, not a finished product – every generated function still went through code review, edge case testing, and production hardening.

Architecture: background workers and a consistent pipeline

Real-time sync wasn’t practical here. Amnis transactions take time to settle, Xero has rate limits, and we needed clean failure handling. A background worker architecture made more sense.

Each sync run follows the same six-step pipeline:

1. Fetch – pull new transactions from Amnis since last sync
2. Transform – convert to Xero format, resolve contacts, map accounts
3. Validate – check for data completeness, flag anomalies
4. Push – create transactions in Xero via API
5. Confirm – verify creation, store Xero transaction IDs
6. Log – record sync results, timing, any issues

Idempotency was critical throughout. Running the same sync twice can’t create duplicate transactions. We handled this through: 

• Transaction fingerprinting – each Amnis transaction gets a deterministic hash
• Sync state tracking – we record which transactions have been successfully pushed
• Xero reference matching before creating anything new

Error handling: designing for reality

Things go wrong. APIs time out, tokens expire, data is malformed, rate limits get hit. We classified errors into four categories that each trigger a different response:

For transient errors, we use exponential backoff with jitter: 1 minute, then 5, then 30, then 2 hours. After four failures, the transaction is marked as failed and flagged for manual review.

Notifications run across three channels – Slack for real-time critical alerts and daily sync summaries, email digests for non-urgent weekly reports, and in-app dashboard alerts for tenant admins.

Multi-tenant management frontend

Since this tool integration needed to serve multiple clients from a single interface, we built a management frontend to handle configuration and monitoring across all tenants.

Tenant onboarding covers: 

• OAuth connection flows for both Amnis and Xero, 
• Account mapping (which Amnis accounts map to which Xero bank accounts)
• Default categorisation rules
• Contact matching preferences

The monitoring dashboard surfaces: 

• Sync status – last successful sync, pending transactions, error count
• Transaction volume – daily/weekly/monthly transaction counts and values
• Health indicators like API connectivity, token status and processing latency 

Each tenant also gets configurable settings: 

• Sync frequency – how often to pull new transactions
• Categorisation rules based on counterparty or description patterns
• Notification preferences – who gets alerted and when
• Manual review thresholds for large or unusual transactions

Every action is logged — configuration changes, manual interventions, sync runs, errors and resolutions. This audit trail turned out to be essential, not just for debugging but for clients who need to explain their accounting processes to auditors.

Lessons learned

API documentation lies sometimes

Both APIs had cases where actual behaviour differed from documentation. We learned to trust integration tests over documentation and build in defensive checks for unexpected responses.

Currency is genuinely hard

What happens when a EUR payment arrives in a CHF account? Which FX rate do you use – Amnis’s or Xero’s? What about timing differences between transaction date and value date? We spent significant time getting this right, and the edge cases kept coming.

Observability is worth the investment

When something goes wrong at 2am, you want to diagnose it from logs without reproducing the issue. We log every API call, every transformation decision, every error – with enough context to understand what happened. This paid off repeatedly.

Users have existing workflows

The integration doesn’t exist in isolation. Finance teams have approval processes and reporting requirements that predate your connector. Understanding those workflows and fitting into them – rather than disrupting them – is as important as the technical implementation.

Results

The integration now handles thousands of transactions per month across multiple tenants. Key outcomes include: 

• Time savings – finance teams report saving 5–10 hours per week on manual data entry
• Error reduction – reconciliation discrepancies dropped to near-zero, compared to a 3–5% error rate with manual entry
• Real-time visibility – books are current within 15 minutes of payment completion
• Scalability – adding a new tenant takes minutes, not days

What’s next

We’re continuing to improve the integration with smarter categorisation (using transaction history patterns for automatic account assignment), predictive alerts for unusual transactions, and extended reconciliation that matches Amnis transactions with Xero invoices for automatic payment allocation.

If you’re dealing with disconnected business tools and manual data entry between systems, this kind of integration is exactly what we build. Check out our Tools Integration Services to see how we approach connecting platforms like Amnis and Xero – and what that could look like for your setup.