Payroll export

For participants paid through payroll, Bitta Commission produces a payroll-ready CSV file from a frozen settlement. You load the file into your payroll process, and then import the payroll system's response as an acknowledgement so that Bitta Commission knows what was actually paid. Every export is an immutable, hashed batch.

Each payroll-ready export is an immutable batch with its acknowledgement totals.

Bitta Commission does not connect to a payroll provider directly. The file and the acknowledgement are the exchange, and your payroll team decides how the amounts are taxed and paid.

Before you start

• The settlement must be Frozen. See Settlements and pay groups.
• The lines must use the Payroll Export payment method, and each participant needs an Employee No. on the participant version. Vendor-routed settlements are refused.
• You need finance-wide access and a role with settlement output rights, such as Bitta Commission Payroll and AP. The Participant and Auditor roles cannot create exports.

Create the export

1. Open the frozen settlement on Commission Settlement.
2. Choose Validate export readiness. The app checks that the frozen snapshot is intact and has payable commission. Fix any message before you continue.
3. Choose Create payroll-ready export. The app writes an immutable export batch and opens Commission Payroll-ready Export.
4. Choose Download export file to save the CSV.

A settlement has exactly one initial payroll export. Later outputs are versioned resends or supplements, described below.

What the file contains

The file has a header row and one row per export line:

Column	Content
batchReference, payloadVersion	The export batch and its version.
lineReference	The unique line reference that the acknowledgement must quote.
employeeReference	The payment target frozen on the settlement line.
earningCode, payPeriod	The earning code and pay period of the line.
grossCommission, currency	The amount and its currency.
component, adjustment, traceKey	Component and adjustment detail and a key back to the calculation.

When a batch contains lines paid in another currency or with a minimum guaranteed pay top-up, extra columns are added: paymentAmount, paymentCurrency, paymentExchangeFactor, paymentRateDate, guaranteeTopUp and guaranteeTopUpPayment. Local-currency batches keep the basic layout.

For consolidated payee pay groups, Download consolidated payee CSV gives a derived view aggregated by payee reference. The per-line file remains the contract for the acknowledgement.

Review the export

Commission Payroll-ready Export shows:

Field	What it shows
Provider	PAYROLL-CSV for a payroll-ready export, GENERIC-CSV for a generic payment file.
Payload Version No. / Predecessor Export Batch ID	The version and the batch it follows, for resends and supplements.
Line Count, Payload Hash, Snapshot Hash	The size of the batch and the hashes that bind it to the frozen settlement.
Accepted amount, Rejected amount, Actual paid amount, Difference amount	Totals from the acknowledgement, once imported.

The Payroll-ready Export Lines part lists each line with the participant, payment target, earning code, pay period, gross commission, amount, currency and trace key. Commission Payroll-ready Exports lists all batches, and Download export file is available there too.

Import the payroll acknowledgement

After payroll has processed the file, import its response as a JSON file.

1. On Commission Payroll-ready Export, choose Import payroll acknowledgement and select the JSON file.
2. The app validates every line, the totals and the identifiers before it applies anything.

The JSON must identify every exported line exactly once:

{
  "acknowledgementId": "PAYROLL-ACK-0001",
  "idempotencyKey": "PAYROLL-ACK-0001",
  "lines": [
    {
      "lineReference": "COPY-THE-lineReference-FROM-THE-EXPORT-FILE",
      "currencyCode": "",
      "acceptedAmount": 1250.00,
      "rejectedAmount": 0,
      "actualPaidAmount": 1250.00,
      "paymentReference": "RUN-2026-10",
      "actualPayDate": "2026-10-31",
      "differenceReason": ""
    }
  ]
}

Rules the import enforces:

• Accepted plus rejected must equal the exported amount of each line, and the actual paid amount cannot exceed the accepted amount.
• A paid line needs a payment reference and a pay date. Dates use the YYYY-MM-DD format.
• Rejected or unpaid commission needs a difference reason.
• Each line currency must match the frozen line.
• An export version can be acknowledged only once. Importing the same acknowledgement again returns the original result.

Accepted amounts move from Payable to Settled. Rejected amounts return to Payable, and the export itself is kept. When accepted payments cover the settlement, it becomes Paid.

Resend rejected lines

If payroll rejected some lines, choose Create rejected-line resend. The app creates the next immutable batch for the retryable rejected or unpaid amounts only. The original batch and its acknowledgement stay intact. Acknowledge the resend the same way.

Supplements

Create export supplement on the settlement creates the next payroll output version for commission that is payable on the settlement but not covered by an earlier output. Every earlier payroll output must be acknowledged first (BAA-PAY-SUPPLEMENT-PENDING). This is how a posted adjustment on a payroll-paid settlement line reaches payroll through the original settlement line's payroll documents.

Accounting for payroll

The export does not post anything. Post the accrual with an accounting proposal, and after payroll has paid, use the payroll clearing journal on the posting proposal to relieve the commission liability. See Accounting and posting.

Export evidence

Exports and other governed outputs, including reports and API reads, are recorded on Commission Export Evidence with the requester, row count, control amount, the filter and security scope hashes, and an output hash chained over every emitted row. Use it to prove what left the system and when.

Troubleshooting

• "Payroll output requires a frozen settlement." Freeze the settlement first.
• "The acknowledgement must identify every frozen payroll line exactly once." A line is missing or repeated. Check the lineReference values against the export file.
• "Accepted and rejected amounts must allocate the exported amount." The amounts on a line do not add up.
• "This export version already has a committed acknowledgement." Create a resend for the rejected amounts instead.
• BAA-PAY-NO-PAYABLE. The settlement has no payable commission to export, for example because every line is deferred or carried forward.

Related pages

• Settlements and pay groups
• Vendor payments through Payables
• Multi-currency
• Audit and security