Xero: Payment Synchronization

Contents

• Overview
• Synchronization Logic
• Base Currency Payment Synchronization
• Non-Base Currency Payment Synchronization
• Payment Allocation Scenarios
• Overpayment Handling
• Exchange Rate Handling
• Integration Mapping
• Examples

Overview

Ordway synchronizes payments to Xero based on the payment currency, invoice currency, and payment application details.

Because Xero Batch Payments support only an organization's base currency, Ordway uses different synchronization methods for base-currency and non-base-currency transactions.

This behavior ensures that fully applied payments, partial payments, and overpayments are synchronized correctly and reflected accurately in Xero.

Synchronization Logic

Ordway determines how payments are synchronized to Xero based on:

• Payment currency
• Invoice currency
• Applied amount
• Unapplied amount
• Organization base currency

Base Currency Payment Synchronization

When a fully applied payment is allocated to invoices in the Xero organization's base currency, Ordway synchronizes the payment to Xero using the Batch Payment process. 

Supported Scenarios

• One payment applied to one invoice
• One payment applied to multiple invoices
• Multiple payments applied to invoices

Result

A Batch Payment record is created in Xero.

Non-Base Currency Payment Synchronization

When a payment is applied to invoices in a non-base currency, Ordway creates standard Payment records in Xero instead of creating an Overpayment.

Conditions

• Payment currency is not the Xero base currency.
• Invoice currency matches the payment currency.
• Payment amount is applied to one or more invoices.

Result

Ordway creates one or more Payment records using the Xero Payments API.

This behavior prevents fully applied non-base currency payments from being incorrectly represented as Overpayments in Xero.

Payment Allocation Scenarios

One Payment Applied to One Invoice

Example

Result

• A Payment record is created in Xero and the invoice is marked as paid.
• No Overpayment record is created.

One Payment Applied to Multiple Invoices

A single Ordway payment can be allocated across multiple invoices.

Example

Result

Ordway creates separate Payment records for each invoice allocation.

Each payment record references the same Ordway payment.

Multiple Payments Applied to One Invoice

Multiple payments can be applied to a single invoice.

Example

Result

• Ordway creates separate Payment records in Xero for each payment application.
• Each payment remains independently traceable.

Overpayment Handling

Ordway creates an Overpayment in Xero when a payment has an unapplied amount remaining after invoice allocations.

When a payment contains both applied and unapplied amounts:

1. The applied amount is synchronized to the associated invoice allocations.
2. The unapplied amount is synchronized to Xero as an Overpayment.

Example

Result

• Payment records are created for the EUR 1,000 applied amount.
• An Overpayment record is created for the remaining EUR 200.

Fully applied non-base currency payments are synchronized as standard Payment records and are not created as Overpayments.

Exchange Rate Handling

For non-base currency payments, Ordway sends the exchange rate associated with the payment transaction to Xero.

• When a single payment is allocated across multiple invoices, each Xero payment record uses the same exchange rate from the originating Ordway payment.
• When multiple payments are applied to the same invoice, each payment may use its own exchange rate based on the payment transaction.

Integration Mapping

To support payment synchronization scenarios where a single Ordway payment creates multiple Xero payment records, Ordway stores integration mappings between Ordway and Xero transactions. 

Integration mappings are maintained for:

• Invoices
• Credits
• Payments
• Refunds

These mappings are used to track relationships between Ordway transactions and Xero payment records.

Examples

Fully Applied Non-Base Currency Payment

Ordway

Xero Result

• Payment created
• Invoice paid
• No Overpayment created

Payment with Unapplied Amount 

Ordway

Xero Result

• Payment created for EUR 1,000
• Overpayment created for EUR 200

Summary

Ordway synchronizes payments to Xero using different methods based on currency and payment application status:

• Fully applied base-currency payments are synchronized as Batch Payments.
• Fully applied non-base-currency payments are synchronized as standard Payment records.
• Payments with unapplied amounts create Overpayments for the remaining balance after invoice allocations.
• Overpayments are not created for fully applied non-base-currency payments.