Reconcile payout confirmations against expected obligations

Where reconciliation fits

Reconciliation compares a locked Allocora calculation run with payout confirmation evidence from the system that actually paid sellers, affiliates, partners, or other payees. Expected obligations use included settled amounts from the same immutable settlement snapshot that produced the payment-ready files.

• Run and review the calculation in Allocora first.
• Execute payment movement in the external payout, bank, or accounting workflow.
• Import the paid-out confirmation file back into the locked run.
• Use the reconciliation page to compare expected obligations with confirmed paid rows.

Payment boundary

A payout confirmation import is evidence. It does not trigger payment movement, change the locked calculation output, or replace the downstream payout system.

• Keep bank transfer, payout rail, tax, and KYC status in the system that owns those workflows.
• Use Allocora to preserve calculated obligations, imported evidence, match decisions, and variance context.
• Resolve mismatches before treating a payout period as fully reconciled.

Download a payout confirmation workbook

A locked calculation run can provide a prepared XLSX with the positive payment-ready obligations from its frozen settlement snapshot. Owner and Admin users can generate or download it from the payout confirmation section of the run.

• A workbook is prepared automatically when you lock a run. For an existing locked run, choose Generate confirmation workbook and wait for preparation to finish.
• Choose Download workbook when it is ready. If preparation fails or the stored file is unavailable, use Retry workbook generation.
• The Payout Confirmations sheet contains the frozen payee details, expected amount and currency. Only paid_amount, paid_at, payment_reference and note are editable; these four fields start blank.
• The Instructions and Metadata sheets describe the workbook and summarize obligations excluded because of a hold, threshold or non-positive amount. Later payee-control edits do not change the frozen obligations.
• Use the workbook to prepare and record payments made outside Allocora. Downloading or editing it does not perform or confirm a payment.
• After recording external payments, upload the completed workbook to the same locked run and review its preview before choosing Record verified payments.

Prepare the remaining payout

After clearing a hold or recording a partial payment on a retained obligation, an Owner or Admin opens the original locked calculation and chooses Review payout release for the active payee’s remaining payable amount.

• Enter a reason and review the frozen payable amount, recorded payments, and unpaid remainder before confirming.
• Create the payout CSV or confirmation workbook from the confirmed review. Each file covers only that source obligation and its reviewed remainder.
• After a partial payment, review the remaining amount again before creating another payment file. All confirmations reduce the same original obligation.
• If the payee or payment evidence changes, prepare a fresh review. Payment evidence from an earlier valid workbook remains recordable.
• The original calculation, statement, and settlement amounts stay available as historical evidence.

Reconcile a payment against retained royalties

Import an actual payment into its original locked run. An Owner or Admin reviews the evidence against the current retained obligation, including when the amount is still below threshold in the original period.

• The affected retained amount is blocked from new payout preparation until the evidence is reconciled.
• If USD 30 below threshold is paid before the next period, reconcile it on the original run before calculating the next period. A later USD 25 then remains below a USD 50 threshold.
• For USD 30 transferred into a later threshold balance of USD 40, reconciling the original USD 30 payment leaves USD 10 retained. The older statements keep their original period amounts.
• A payment above the provable unpaid remainder stays a conflict for review. Repeating the same confirmed evidence does not reduce the balance again.
• An inactive payee retains financial history and may still have a payment that already occurred recorded and reconciled.

Import a completed Allocora workbook

Allocora checks the original workbook and its frozen obligations before accepting payment evidence. A recognized Allocora workbook does not need column mapping. Files from a payment provider continue to use the existing mapping and preview flow.

• For each payment, enter a positive paid_amount with no more than three decimal places, paid_at as YYYY-MM-DD or an Excel date, and a payment_reference. The note is optional.
• Keep every original sheet, column heading and frozen obligation row. Do not change the fixed payee details, expected amounts, currency or workbook identifiers, and do not enter formulas.
• For split payments in Excel, choose Review > Unprotect Sheet, insert a row beneath the payment, and copy the complete source row into it. Fill only paid_amount, paid_at, payment_reference and note, using a distinct payment_reference for each paid copy. Keep the fixed details unchanged.
• Rows with all four payment fields blank are ignored. At least one complete payment row is required; partially filled payment rows must be corrected before confirmation.
• Review the paid amounts, partial payments, overpayments and remaining obligations, then choose Record verified payments to preserve the evidence.
• Each ordinary calculation run accepts one generated-workbook confirmation. Each reviewed payout release has its own workbook confirmation context for the same original obligation. Uploading the same workbook with the same payments shows the recorded result without creating a duplicate, even if the file was renamed or saved again.
• After confirmation, changed payment values or another generated workbook cannot replace that evidence. Use the existing provider-file import for later external payments and open reconciliation to review the cumulative result.

Optional payment evidence

Provider files can include structured payment evidence alongside the paid amount. Map only values explicitly present in the source and review the Evidence column before confirming. Blank fields remain unknown, and older confirmations are not filled from notes, filenames, import timestamps or current provider settings.

• Use payment_provider: bank, stripe, paypal, wise, tipalti, trolley or payoneer. Use payment_status: completed, pending, failed, cancelled or reversed. Codes are case-insensitive; unsupported nonblank values must be corrected.
• A completed status requires a positive paid amount that fits three-decimal precision; extra trailing zeroes are accepted, but a value that would round is rejected. Other statuses require a zero paid amount and cannot include paid_at, fees or FX. Their reconciliation bucket can still be partial or underpaid: the source payment status and the remaining obligation describe different things.
• For failed payments, payment_status_reason can be bank_rejected, compliance, insufficient_funds or account_closed. For cancelled payments, use duplicate, customer_cancelled or compliance. For reversed payments, use returned, refunded or chargeback. Omit a reason for completed, pending or unknown status.
• Provider paid_at values must be real YYYY-MM-DD dates in years 0001–9999. In Excel provider files, keep these cells as text. Dates, fees and FX require a positive paid amount that fits three-decimal precision even when payment_status is omitted.
• Supply fee_amount and fee_currency together. Fees can be zero and have at most three decimal places. Supply fx_rate, fx_source_currency and fx_rate_source together; the rate must be positive with at most nine decimal places. FX also requires a nonblank mapped row currency, different from the source currency and equal to the locked run currency. Rate-source codes are provider, bank or ecb. Fee and FX source currencies must be supported Allocora currency codes.
• Fees and FX preserve source evidence only. They do not change the paid amount, convert currencies, recalculate obligations or update the run’s FX reporting snapshot.
• Malformed or contradictory evidence blocks the whole file confirmation. Correct the row identified in the preview, then refresh the preview. The server checks the source again when you confirm.
• The generic status, transfer_status and status_note headers keep their note mapping. Only payment_status automatically maps to the typed status; manually mapping another header applies the same validation. These optional fields are not added to the generated Allocora workbook.
• Payment evidence is an optional Payee Portal permission, switched off by default in Payee Portal Access. Enabling it authorizes confirmed payment details for the selected payee summary statements; a delegate also needs that permission from the principal. Product statements do not receive payee-wide payment evidence. Authorized payees can open a summary statement to view its Payment evidence timeline. It shows recorded amounts, provider and payment status, source-supplied paid dates, fees and FX details when available. Confirmation recorded is the time the confirmation was recorded, not a substitute for an unknown paid date. Missing values are shown as Not recorded; an empty timeline does not mean a payment failed or is unpaid. The timeline shows 10 recorded events per page and the permitted event range.
• The confirmation summary compares the frozen Payment-ready amount with Recorded confirmations and shows the Remaining to confirm. It includes all eligible confirmations, independent of the selected timeline page. States distinguish no recorded confirmation, partial confirmation, full confirmation and amounts above expected. When neither a payment-ready amount nor a confirmation exists, it shows No payment expected. If the underlying evidence cannot support a reliable total, it shows Confirmation summary unavailable instead of guessed amounts. These states describe recorded evidence: Allocora does not move money, and missing confirmation does not prove that a payment was not made.

Partial-payment match ledger

Payout Confirmation Reconciliation V2 separates imported confirmation rows from immutable match facts. A single expected obligation can be satisfied by multiple confirmation rows, and a single confirmation row can leave a residual amount that remains open for review.

• Preview and stored rows include match status, match strategy, variance status, matched amount, residual amount, and match group key.
• Many-to-one payment rows are grouped by matched payee, so expected totals are counted once while paid rows remain individually auditable.
• Confirmed files are cumulative for the same locked settlement: a later batch starts from prior confirmed paid amounts and can close the remaining obligation without counting the expected amount twice.
• The encrypted preview, confirmed batch, stored row, and immutable match fact bind to the exact settlement snapshot or settlement line used for the expected amount.
• Stored confirmation batches create append-only reconciliation match facts; confirmed batch, row, and fact records are immutable.
• Finance exports include expected amount, paid amount, matched amount, residual amount, match strategy, and variance status.

FX reporting context

Locked calculation runs store an FX reporting snapshot for display and close-package context. The current implementation records identity-rate context for same-currency reporting and preserves the boundary that calculations remain single-currency.

• The snapshot captures source currency, organization calculation currency, reporting currency, rate, rate date, provider, and conversion lineage.
• FX context is display-only and does not change calculation outputs, statement math, reconciliation math, or payout exports.
• Mixed-currency calculations remain unsupported; split source data by organization currency before calculation.

Payout Ops Review

The Payout Ops Review block previews payee controls before lock. Locking freezes those decisions and run-scoped canonical obligations into the versioned settlement snapshot used by statements, payout exports, journals, close packages, and reconciliation. Later payee edits do not rewrite locked close evidence.

• Included positive obligations are rounded once in aggregate at the currency exponent using half-up; residual minor units go to the largest fractional remainders, then immutable payee UUID ascending for ties.
• Excluded positive obligations are withheld because they were on hold or below their minimum payout threshold at freeze, while their canonical liability remains visible in evidence.
• Zero obligations are recorded but omitted from payment files; a negative obligation prevents the settlement snapshot from freezing.
• Settlement rounding never carries into another period.
• Current workspace statements, statement ZIPs, and Payee Portal downloads require verified publication for the locked run's latest settlement snapshot; re-locking withdraws those current downloads until a replacement is published. Previously issued share and Evidence Center links keep their original verified PDF, subject to expiry, revocation, and file availability.
• An older Evidence Center link still shows current reconciliation totals, counting each published run once. Its historical PDF does not add an older obligation or payment confirmation again. Until a re-locked run has a new publication, that run contributes no current reconciliation totals.
• Production settlement requires PostgreSQL so persisted financial decimals remain exact; unsupported database drivers fail before freeze or snapshot resolution.
• Use the block before exporting payout files so downstream payment tools receive only eligible payees.
• Built-in payment-ready export presets include Generic Payout CSV, PayPal MassPay CSV, Wise Batch CSV, Tipalti Payables Mapping CSV, and Generic AP / Bank Payment CSV.
• Close Package V1 includes payment-ready preset files plus payee totals, import quality, reconciliation, statement, rule, and audit evidence for the locked run.
• Close Package payment-ready files omit obligations affected by a current hold, inactive payee, recorded payment, or unresolved retained-payment evidence. The package README and manifest list each omitted obligation with its reason, the payout CSV preview shows the same lines as excluded under Current payout controls or payment evidence, and the export record keeps the omitted list. Historical amounts stay in the close evidence. A previous package with payment instructions that are no longer current must be generated again; use a reviewed payout release to prepare a remaining payment.