Settlement report fields

A settlement report is one payout: a summary of totals and, underneath, one line per transaction that went into it. This page explains what those fields mean. The same data comes from three places — the CSV and PDF in the Kustom Portal, the same files over SFTP, and the Settlements API — and they don’t spell it identically:

	CSV report	Settlements API
Amounts	Decimals by default, 100.00	Always integers in minor units, 10000
Summary totals	total_sale_amount, total_fee_amount, …	totals.sale_amount, totals.fee_amount, …
Debt balance	opening_debt_balance, closing_debt_balance	totals.opening_debt_balance_amount, totals.closing_debt_balance_amount
Payout currency	settlement_currency	currency_code
A line’s currency	posting_currency	currency_code
VAT on Kustom’s fee, per line	tax_rate, tax_amount	vat_rate, vat_amount
The customer’s VAT, per line	tax_rate_1 … tax_rate_4, tax_amount_1 … tax_amount_4	consumer_vat, on SALE lines

The CSV’s format is yours to configure in the Portal: amounts in minor units instead of decimals, the decimal separator, minus signs on debit columns, and which columns appear at all. Know which settings your import expects before you change them, and never mix CSV and API amounts in one calculation — a decimal read as minor units is off by a factor of a hundred, and nothing will tell you.

How the settlement amount adds up

The payout is the sales less everything taken off them, plus everything added back. The API’s totals and the CSV’s are named alike but don’t hold quite the same numbers, so the sum is written differently for each.

From the API’s totals:

settlement_amount = sale_amount
                  − return_amount
                  − reversal_amount
                  − fee_amount − tax_amount        // fees and their VAT, before any refund
                  + fee_correction_amount          // fee refunds, with their VAT
                  − charge_amount
                  + credit_amount
                  − holdback_amount
                  + release_amount
                  − repay_amount
                  + deposit_amount
                  + corrections

From the CSV’s summary:

total_settlement_amount = total_sale_amount
                        − total_return_amount
                        − total_reversal_amount
                        − total_fee_amount − total_tax_amount   // already net of fee refunds
                        − total_charge_amount
                        + total_credit_amount
                        − total_holdback_amount
                        + total_release_amount
                        − total_repay_amount
                        + total_deposit_amount
                        + corrections

What trips up a recomputation:

• Fee refunds are counted once. The API’s fee_amount and tax_amount are before refunds, and the refunds come back in fee_correction_amount; tax_refund_amount is the VAT inside that, not something to add again. The CSV’s total_fee_amount and total_tax_amount are already net of refunds, and total_fee_correction_amount and total_fee_refund_amount both repeat that refund — add either one and you count it twice.
• Corrections have no total of their own. CREDITED_CORRECTION and CORRECTION_DISPUTE lines are part of the payout but appear in no summary field, so sum them from the lines.
• Some totals are always zero for Kustom payouts: commission_amount, and the API’s fee_refund_amount.
• tax_amount is VAT on Kustom’s fees, not the customer’s VAT on your goods.

When a payout would be negative

If returns, fees and charges in a period come to more than its sales, there is nothing to pay out, and the shortfall becomes debt you owe Kustom:

• deposit_amount is that shortfall — the increase in your debt this period. Adding it is what brings settlement_amount to zero rather than below it.
• opening_debt_balance is the debt carried in: the closing balance of your previous payout in the same currency.
• repay_amount is how much of that debt this payout paid off — the smaller of the opening balance and what the payout would otherwise have been.
• closing_debt_balance = opening_debt_balance − repay_amount + deposit_amount, and becomes the next payout’s opening balance.

Checking that each payout’s opening balance equals the previous one’s closing balance is the cheapest way to notice a missing payout. Include DEBT_STATEMENT payouts in that chain.

Summary fields

Field	What it holds
payment_reference	The payout’s unique id. It’s on the transfer in your bank statement, and it’s the key that joins bank, report and API
payout_date	When the payout was created. The API gives the full UTC timestamp; the CSV gives the date only
settlement_currency	You’re settled like-for-like in the currency you sold in, so expect one payout per currency
merchant_settlement_type	How the payout treats Kustom’s fees — see below
merchant_id	Who the payout is for
total_sale_amount	Captured orders
total_fee_amount	Kustom’s fees on those sales, excluding VAT
total_tax_amount	VAT on those fees
total_fee_correction_amount	Fees refunded to you
total_return_amount	Refunds you registered
total_reversal_amount	Amounts reversed on disputed orders, in the customer’s favor
total_holdback_amount	Money held back from this payout — see HOLDBACK below
total_release_amount	Held-back money released and paid to you
total_credit_amount, total_charge_amount	Other credits and charges; detailed_type on each line says what they are
total_repay_amount, total_deposit_amount, opening_debt_balance, closing_debt_balance	The debt balance, above

merchant_settlement_type takes four values:

Value	Meaning
NET	Kustom’s fees are deducted from the payout
GROSS	The payout carries your sales without fees deducted; the fees are settled separately
GROSS_FEE	That separate settlement: the fees on a GROSS account, collected by invoice rather than deducted
DEBT_STATEMENT	A settlement of debt moved onto a debt statement invoice

Transaction fields

Field	What it holds
type	What kind of entry this is — see Transaction types
detailed_type	Why, more precisely — see Detailed types
order_id	The Kustom order. The recommended key for joining a line to your own order
short_order_id	The customer-facing order number
capture_id	The capture behind the line. On a reversal, the capture the dispute was raised on. On a return it’s empty in the CSV, while the API puts the refund’s id here
refund_id	The refund behind a RETURN line. Each partial refund has its own
reversal_reference	The dispute behind a REVERSAL line
merchant_reference1, merchant_reference2	The references you set when you created the order
merchant_capture_reference, merchant_refund_reference	The references you sent with the capture or refund
amount	The line’s amount
posting_currency	The currency the order was placed in
capture_date	When the entry was registered, in UTC. For a SALE, when you captured
sale_date	When the order was created, in UTC
purchase_country	The order’s purchase country, or your own country where the order had none
shipping_address_country	The country the order shipped to
initial_payment_method_type	The payment method the customer chose at checkout
initial_payment_method_number_of_installments	The number of installments chosen at checkout, where there was a plan
tax_rate, tax_amount	VAT on Kustom’s fee for this line — not the customer’s VAT
tax_rate_1 … tax_rate_4, tax_amount_1 … tax_amount_4	The customer’s VAT on your goods, one pair per rate, in basis points (2500 is 25%). Shown only when consumer VAT is turned on in your report settings, and left empty for an order with more than four rates
settlement_merchant_id	The merchant ID the line was settled under

Partial captures and partial refunds give one order several lines, so key a line on order_id together with capture_id or refund_id and type — never on order_id alone.

Transaction types

type	Meaning
SALE	A captured order
FEE	A Kustom fee. One sale can carry several
FEE_REFUND	A fee refunded to you
RETURN	A refund you registered
REVERSAL	An amount reversed on a disputed order, in the customer’s favor
CORRECTION	A manual correction
HOLDBACK	Money held back from the payout
RELEASE	Held-back money paid out to you
CREDIT	Another credit — see its detailed_type
CHARGE	Another charge — see its detailed_type
THIRD_PARTY_FEE	A fee charged by a third party, reported for information. It isn’t part of the payout amount

Detailed types

type	detailed_type	Meaning
SALE	PURCHASE	A captured order
FEE	PURCHASE_FEE_FIXED	The fixed fee on a captured order
FEE	PURCHASE_FEE_PERCENTAGE	The percentage fee on a captured order
FEE	AGE_VERIFICATION_FEE_FIXED, AGE_VERIFICATION_FEE_PERCENTAGE	The fee for an age-verified purchase
FEE	FX_FEE	Currency conversion
FEE	DISPUTE_FEE	The fee for a dispute on a captured order
FEE_REFUND	DISPUTE_FEE_REFUND	A dispute fee refunded, because the dispute went your way
FEE_REFUND	APPLICATION_FEE_REFUND	Another fee refunded to you
RETURN	PURCHASE_RETURN	A refund you registered
REVERSAL	REVERSAL	An amount reversed on a disputed order
CORRECTION	CREDITED_CORRECTION	A manual correction
CREDIT	CORRECTION_DISPUTE	A dispute correction credited to you. Counted with the corrections, not in credit_amount
CREDIT	INVOICE_CREDITED, GROSS_FEE_INVOICE_CREDITED, DEBT_STATEMENT_INVOICE_CREDITED	A credit against a Kustom invoice
CREDIT	CREDIT	A general credit, such as a correction, a released negative balance or a rounding adjustment
CHARGE	TRANSFER_FROM_LEGACY_INTEGRATION	Debt moved over from a legacy integration, in place of an invoice
CHARGE	CHARGE	A general charge, such as a correction, debt moved to a debt statement or a rounding adjustment
HOLDBACK, RELEASE	ROLLING_RESERVE	A share of funds held as collateral, and released after the agreed period
HOLDBACK, RELEASE	UNDER_REVIEW	A hold on all or part of your payouts while Kustom reviews your account and transactions, and its release
HOLDBACK	INSUFFICIENT_BANK_ACCOUNT_DETAILS	Money that couldn’t be paid out because your bank details are missing or wrong
THIRD_PARTY_FEE	THIRD_PARTY_PURCHASE_FEE	A third party’s fee on a purchase, for information

INSUFFICIENT_BANK_ACCOUNT_DETAILS is the one that needs you. Correct your bank details in the Kustom Portal under Settings → Bank account details. The amount stays held until they are.

Expect values this table doesn’t list, and expect null. The API’s enum is larger than what is booked into Kustom payouts, and new values are added. Some values the CSV prints — FX_FEE, APPLICATION_FEE_REFUND, the three *_INVOICE_CREDITED values and the bare CHARGE and CREDIT — currently arrive from the API as detailed_type: null. Store the raw type and detailed_type on every line, key your logic on type, and send a value you don’t recognize to someone to review instead of failing the import.

Related

• Settlements and getting paid — the payout schedule, and reconciling with the API
• Settlements API reference — every endpoint and field