Payroll-ready 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, then import the payroll response as a JSON acknowledgement so the app knows what was paid. There is no live payroll connector: the file and the acknowledgement are the whole exchange, and your payroll process decides how the amounts are taxed and paid.

Before you start

• The settlement must be Frozen or Posted. See Settle commission.
• Every line of the settlement must use the Payroll Export payment method.
• You need the finance-all security scope and export permissions, for example through the Bitta Commission Payroll and AP permission set.

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, and shows a message.

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, and hand it to payroll.

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

What the file contains

The CSV 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 the acknowledgement must quote.
employeeReference	The payment target frozen on the settlement line.
earningCode, payPeriod	The earning code COMMISSION and the pay period.
grossCommission, currency	The amount and its currency code.
component, adjustment, traceKey	Component and adjustment detail, and the frozen settlement line hash.

Batches with lines paid in another currency or with a minimum guaranteed pay top-up add 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 view aggregated by payee. The per-line file stays the contract for the acknowledgement.

Review the export

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.
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 imported acknowledgement.

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 every batch and offers Download export file too.

Import the payroll acknowledgement

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 identifies every exported line exactly once:

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

The import enforces these rules:

• Accepted plus rejected equals the exported amount of the line, and the actual paid amount cannot exceed the accepted amount.
• currencyCode is required and must match the line. Copy it from the currency column of the CSV.
• A paid line needs a payment reference and a pay date in YYYY-MM-DD format.
• Rejected or unpaid commission needs a difference reason.
• An export version is acknowledged only once. Importing the same acknowledgement again returns the original result.

The actual paid amount moves from Payable to Settled. When accepted payments cover the settlement, it becomes Paid.

Resend rejected lines

If payroll rejected or did not pay some lines, choose Create rejected-line resend on the acknowledged export. The app creates the next immutable batch for the 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.

Accounting for payroll

The export posts nothing. Post the accrual with an accounting proposal. Once the lines are exported or paid, Post payroll clearing journal on the posted proposal moves the liability of payroll-paid lines to the payroll clearing account through a standard general journal. See Commission accruals. For what the payroll integration does not do, see Known limitations.

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 lineReference against the CSV.
• Every acknowledgement line currency must match its frozen payroll line. Fill currencyCode from the CSV currency column.
• This export version already has a committed acknowledgement. Create a resend instead.
• BAA-PAY-NO-PAYABLE. The settlement has no payable commission to export.
• BAA-PAY-SUPPLEMENT-PENDING. Acknowledge every earlier payroll output before a supplement.

What's next

Pay vendors and agents: Pay through Payables.