This page covers the CII ApplicableHeaderTradeSettlement section of the invoice: the Go structs that model it, the newSettlement function that converts GOBL data into CII XML, and the goblNewPaymentDetails function that parses CII XML back into GOBL. Settlement encompasses payment terms, payment means, monetary summation, tax amounts, prepaid advances, referenced preceding documents, and the payee party.
For header-level allowances and charges embedded within the settlement element, see Allowances and Charges. For line-level tax mappings, see Tax Processing and Mapping. For party structs used in the payee field, see Party Processing.
The Settlement struct in settlement.go17-29 is the root of several nested types, all of which map directly to CII XML elements within ram:ApplicableHeaderTradeSettlement.
Settlement Struct Hierarchy
Sources: settlement.go17-110
The following table shows how each Go struct field maps to its CII XML element path under ram:ApplicableHeaderTradeSettlement.
| Go Field | XML Element | Notes |
|---|---|---|
CreditorRefID | ram:CreditorReferenceID | Direct debit creditor reference |
Currency | ram:InvoiceCurrencyCode | ISO 4217 currency code |
Payee | ram:PayeeTradeParty | Only name and ID fields populated |
PaymentMeans | ram:SpecifiedTradeSettlementPaymentMeans | Slice, but typically one element |
Tax | ram:ApplicableTradeTax | One element per tax rate |
Period | ram:BillingSpecifiedPeriod | From inv.Delivery.Period |
AllowanceCharges | ram:SpecifiedTradeAllowanceCharge | Header-level only |
PaymentTerms | ram:SpecifiedTradePaymentTerms | One element per due date |
Summary | ram:SpecifiedTradeSettlementHeaderMonetarySummation | Required |
ReferencedDocument | ram:InvoiceReferencedDocument | From inv.Preceding[0] |
Advance | ram:SpecifiedAdvancePayment | Parsed only; not emitted on convert |
Sources: settlement.go17-29
newSettlementThe newSettlement function in settlement.go112-259 takes a *bill.Invoice and produces a *Settlement. It is called from newInvoice during the forward conversion pass.
newSettlement Conversion Flow
Sources: settlement.go112-259
Payment terms are sourced from inv.Payment.Terms. The function handles two cases:
Terms element is emitted containing only the notes string as Description.Terms element is emitted per DueDate. Each element may include a Description (the global notes, optionally joined with per-date notes), a DueDateDateTime, and a PartialPaymentAmount if the due amount differs from the total payable.The Mandate field on Terms is populated from inv.Payment.Instructions.DirectDebit.Ref during the payment means processing step, not during the terms step. If no PaymentTerms exists yet when a direct debit is encountered, a new single-element PaymentTerms slice is created just to carry the mandate.
newTaxes in settlement.go292-304 iterates over inv.Totals.Taxes.Categories and produces one *Tax per rate within each category. Each *Tax is constructed by newTax in settlement.go306-326
The Tax struct fields populated during this conversion:
| Tax Field | Source |
|---|---|
CalculatedAmount | rate.Amount.Rescale(2) |
TypeCode | category.Code (e.g. "VAT") |
BasisAmount | rate.Base |
CategoryCode | rate.Ext[untdid.ExtKeyTaxCategory] |
RateApplicablePercent | rate.Percent (defaults to "0") |
ExemptionReasonCode | rate.Ext[cef.ExtKeyVATEX] (if present) |
Sources: settlement.go292-326
newSummary)newSummary in settlement.go261-290 maps from *bill.Totals to *Summary.
| Summary Field | Source in bill.Totals | Condition |
|---|---|---|
LineTotalAmount | totals.Sum | Always set |
TaxBasisTotalAmount | totals.Total | Always set |
GrandTotalAmount | totals.TotalWithTax | Always set |
DuePayableAmount | totals.Payable or totals.Due | Due overrides Payable if non-nil |
TaxTotalAmount.Amount | totals.Tax | Always set |
TaxTotalAmount.Currency | currency parameter | Always set |
Charges | totals.Charge | Omitted if nil |
Discounts | totals.Discount | Omitted if nil |
TotalPrepaidAmount | totals.Advances | Omitted if nil |
RoundingAmount | totals.Rounding | Omitted if nil |
Sources: settlement.go261-290
If inv.Preceding is non-empty, newSettlement takes the first element (inv.Preceding[0]) and emits a single ReferencedDocument with IssuerAssignedID (formatted as Series-Code) and FormattedIssueDateTime.
This is used primarily for correction invoices and credit notes. See Document Type Variations for how document types affect the wider invoice structure.
The newPayee helper in settlement.go328-342 wraps newParty but limits the output to only Name and ID fields (and GlobalID if ID is present), following CII rules CII-SR-352 through CII-SR-364.
The billing period is sourced from inv.Delivery.Period (not inv.Payment). Both Start and End dates are formatted using documentDate.
The PaymentMeans element is only emitted if inv.Payment.Instructions is non-nil. The conversion requires the untdid-payment-means extension key to be set on the instructions; without it getPaymentMeansCode returns a validation error.
Payment Means assembly logic:
Sources: settlement.go193-252
goblNewPaymentDetailsgoblNewPaymentDetails in settlement_parse.go26-88 is the reverse-direction entry point. It accepts a *Settlement and returns a *bill.PaymentDetails.
goblNewPaymentDetails Parsing Flow
Sources: settlement_parse.go26-88
goblNewTerms)goblNewTerms in settlement_parse.go90-138 converts each Terms element:
term.Description values are concatenated into pay.Terms.Notes (joined with ". ").term.DueDate becomes a pay.DueDate entry. If term.Amount is set, it is used directly; otherwise if term.Percent is set, it becomes dd.Percent.nil if no due dates, notes, key, or extensions are present.Sources: settlement_parse.go90-138
goblNewInstructions)goblNewInstructions in settlement_parse.go140-184 reads only stlm.PaymentMeans[0] (the first element). It constructs a *pay.Instructions with:
Key: resolved via goblPaymentMeansCode from paymentMeansMapExt: always sets untdid.ExtKeyPaymentMeans to the raw type code stringDetail: from pm.InformationCard: last 4 digits of pm.Card.ID, cardholder name from pm.Card.NameCreditTransfer: IBAN, Name, Number from pm.Creditor; BIC from pm.CreditorInstitutionNote: direct debit details (Debtor.IBAN, mandate) are not reconstructed into pay.Instructions on parse.
Sources: settlement_parse.go140-184
goblNewPaymentDetails handles advances in two modes settlement_parse.go50-78:
SpecifiedAdvancePayment elements: Each Advance in stlm.Advance is converted to a pay.Advance with amount and optional date.TotalPrepaidAmount: If no Advance elements are present but stlm.Summary.TotalPrepaidAmount is non-empty, a synthetic pay.Advance with only the amount is created. This ensures that totals recalculate correctly in GOBL even when the CII document did not include explicit advance payment records.paymentMeansMap in settlement_parse.go15-24 maps UNTDID 4461 codes to GOBL pay.MeansKey values. The getPaymentMeansCode function (forward direction) reads the code from the untdid-payment-means extension; goblPaymentMeansCode (reverse direction) looks up the GOBL key from this map.
| CII TypeCode | GOBL pay.MeansKey |
|---|---|
10 | pay.MeansKeyCash |
20 | pay.MeansKeyCheque |
30 | pay.MeansKeyCreditTransfer |
42 | pay.MeansKeyDebitTransfer |
48 | pay.MeansKeyCard |
49 | pay.MeansKeyDirectDebit |
58 | pay.MeansKeyCreditTransfer + pay.MeansKeySEPA |
59 | pay.MeansKeyDirectDebit + pay.MeansKeySEPA |
Any code not in the map resolves to pay.MeansKeyAny in the parse direction. In the convert direction, if the extension is missing entirely, getPaymentMeansCode returns a validation error referencing untdid-payment-means: required.
Sources: settlement_parse.go15-24 settlement.go344-355
This diagram bridges the GOBL bill.Invoice fields to CII XML elements through the settlement structs and functions.
Settlement Field Mapping: GOBL ↔ CII XML
Sources: settlement.go112-259 settlement_parse.go26-88 test/data/convert/en16931/out/invoice-de-de.xml114-138
The tests in settlement_test.go12-64 cover the main conversion scenarios:
| Test case | What is verified |
|---|---|
invoice-de-de.json | Currency, payment terms description and due date, all Summary fields including rounding |
correction-invoice.json | ReferencedDocument.IssuerAssignedID, IssueDate format code 102 |
invoice-complete.json | Payment means type code, IBAN, mandate, debtor IBAN, card ID and holder |
| Extension errors | Missing untdid-payment-means extension produces a structured validation error |
The error message produced when the extension is absent is: instructions: (ext: (untdid-payment-means: required.).).
Sources: settlement_test.go12-64
Refresh this wiki