Xero Integration for Payout Platforms: Bills, Payments and Reconciliation

Keep accounting and payout execution separate#

Your contractor asks whether a payment arrived. Finance asks which obligation was cleared and why the bank movement differs from the bill. A good integration can answer both, but the answers come from different records. Xero holds the accounting document; the payout provider and bank supply execution evidence.

Decide the legal payer and Xero organisation before mapping contacts. A contractor working for several platform entities may need distinct accounting relationships. Include the organisation or tenant in every integration key so one entity’s bill cannot be posted or marked paid in another’s books.

Assign one owner to each record#

A one-way export is often easier to operate initially: the platform sends approved obligations and payment evidence, while finance owns documented accounting corrections. Two-way sync is justified only when both systems need a defined change flow. Never let edits compete silently; send a mismatch to an owner when the same field changes on both sides.

Map events to accounting actions#

Xero’s Payments API applies accounting payments to approved AR or AP invoices. The payment account must be a bank account or have payment functionality enabled. Store the returned PaymentID and InvoiceID; these identify accounting objects, not the external transfer.

Choose the accounting event with finance. A provider debit can justify a clearing-account movement while beneficiary receipt is still pending. If you use a different recognition or cash-posting policy, record it in the mapping so support labels and bill balances do not imply more than the evidence establishes.

Follow one bill through clearing and bank reconciliation#

Here is a simplified USD example with taxes and FX omitted. A contractor earns 1,000, and the payer bears a 10 transfer fee. The bill records 1,000 of contractor expense and 1,000 of AP. Once the documented payout-account movement meets the posting policy, a 1,000 payment clears AP against the chosen clearing account.

The bank then shows a 1,010 debit. Finance matches 1,000 to clearing and 10 to the transfer fee, leaving the clearing balance at zero for this item. That reconciles the payer’s cash and obligation accounting. It does not establish beneficiary credit; the payout system still follows the provider’s recipient-level status and any later return.

For a batch of fifty contractors, retain fifty item mappings even if the provider or bank shows one aggregate debit. Compare the item sum, fees and batch movement. If one item fails, do not mark all bills paid because the batch was accepted.

Recover an uncertain Xero write#

Store the intended accounting action, payload version, Xero organisation, business ID and API request key before dispatch. A local transaction can commit that work and its deduplication marker together. It cannot make an external Xero write and your database update one atomic operation.

Xero’s idempotency guidance, checked October 3, 2026, describes a six-minute key-retention window for mutating requests. Same-key replay is a transient recovery tool, not a permanent uniqueness guarantee. Keep the request identical when replaying under that contract.

If the response is missing or a cached error persists, inspect the resource before creating another write. Read back by known Xero IDs and supported references, then reconcile the expected amount, bill and account. An ordinary reference field may help find a record but is not itself a unique constraint. If you cannot determine the outcome, hold the export item for review.

For example, a payment entry might have been created before a worker crashed. Retrying with a fresh key after the retention window can create another payment. Recover the original PaymentID and commit its mapping locally instead. Keep the payout executor isolated: retrying an accounting export must never trigger another contractor transfer.

Make webhook and polling recovery durable#

For any provider or accounting events you consume, authenticate the event and store durable intake before acknowledging it. Process downstream changes with the event marker and local effect in one transaction. Account for duplicates and out-of-order updates, and use resource readback where an event does not establish current state.

Maintain a poll or reconciliation path for missing events. Retention and replay windows belong to each service; do not promise that every historical event can be retrieved indefinitely. Your saved operation and accounting lineage should outlive those transport windows.

Keep returns and adjustments visible#

A returned payout does not erase the original send or its accounting history. Link the return to the original attempt, determine where the money returned, and have finance choose the appropriate reversal or adjustment. Preserve the contractor obligation when it remains owed. A new payout should be a separately approved attempt after the original is resolved.

If an item is already reconciled or in a closed period, do not silently delete or overwrite its payment record. Use the permitted accounting correction procedure and retain the relationship to the original. This lets finance explain both the operational history and the close.

Approve a small, representative integration slice#

• Confirm organisation, contact and account mapping with finance, including currency treatment.
• Trace one normal bill, one partial or aggregate payment, and one fee-bearing bank movement.
• Recover a remote-success/local-crash case without a duplicate accounting entry.
• Simulate a failed recipient item inside a successful batch.
• Trace a return through the obligation, payment record and subsequent adjustment.

Expand only after an operator can choose one contractor and follow the same identifiers through earning lines, Xero, provider records and bank reconciliation. That trace is more useful than an export-complete badge or a generic comparison of card-processing fees.