Marmin Oman Documentation

The credit note object

See the right panel for the complete object definition and code examples.

Attributes

Core fields

All root-level attributes on the sales credit note. Nested fields are linked to their respective tables below for full attribute details.

Field	Type	Required	Source	Description	Validation
`id`	string	Required	System-generated	Primary identifier for the document (UUID). Automatically generated when the document is created.	Response-only; not accepted in requests.
`org_id`	string	Required	System-generated	Unique identifier of the organization that owns this credit note.	Set by backend from your organization; not part of the create request body.
`transaction_type`	string	Required	Client-provided	Credit note transaction type code.	Exactly 20 characters; each character `1` or `0` (bitmap) as per Transaction type rules.
`document_number`	string	Optional	Conditional (client-provided or system-generated)	The credit note number as displayed on the document.	Required for API-created credit notes; must be unique within the organization when provided.
`document_sequence`	number	Optional	System-generated	Sequential number for the credit note within your organization. Used for compliance and tracking.	Server-calculated sequence; do not send in create requests.
`status`	string	—	System-generated	Document lifecycle status. See Document status below.	Response-only. One of `ACTIVE` or `OBSOLETE`. Defaults to `ACTIVE` on create.
`issue_date`	string	Required	Client-provided	The date when the credit note was issued.	Format `yyyy-MM-dd`; must be a valid calendar date.
`issue_time`	string	Optional	Client-provided	The time when the credit note was issued.	If present, format `HH:mm:ss` (e.g. `10:30:00`).
`credit_note_type_code`	string	Required	Client-provided	The type of credit note.	For sales credit notes this code must be `381` or `81.
`discrepancy_response`	string	Required	Client-provided	Reason for issuing the credit note per OMN Tax Authority Cl-02-OM	Must be one of the allowed discrepancy codes (e.g. `CAN`, `VAT`, `VAL`, `QTY`, `OTH`).
`reason`	string	Optional	Client-provided	Free-text explanation or additional reason for the credit note.	Free text; often correlates with `discrepancy_response`.
`note`	string	Optional	Client-provided	Additional notes or terms displayed on the credit note.	Free text.
`tax_point_date`	string	Optional	Conditional (client-provided or system-generated default)	Tax point date per OMN VAT Law—when VAT liability arises.	If present: format `yyyy-MM-dd`; defaults to `issue_date` if omitted.
`document_currency_code`	string	Required	Client-provided	ISO 4217 alpha-3 currency code for all monetary amounts (e.g. `OMR`).	Must be a valid ISO 4217 currency (e.g. `OMR`).
`tax_currency_code`	string	Optional	Client-provided	ISO 4217 currency code for tax when it differs from document currency.	If present: valid ISO 4217 code; consistent with `document_currency_code` and requires `tax_exchange_rate` when different.
`accounting_cost`	string	Optional	Client-provided	Accounting cost center / project cost identifier (if applicable).	Free text.
`buyer_reference`	string	Optional	Client-provided	Buyer reference (customer reference) for the credit note.	Free text.
`invoice_period`	object	Optional	Client-provided	Period covered by the credited supply (start_date, end_date, description).	If present: `start_date` and `end_date` must be `yyyy-MM-dd`, with `start_date` ≤ `end_date`.
`order_reference`	object	Optional	Client-provided	Reference to the original order. See Order reference object below.	If present: `id` must be provided; `issue_date` as `yyyy-MM-dd` when used.
`billing_reference`	array	Optional	Client-provided	Billing references, typically including the original invoice being credited.	For API sales credit notes, at least one reference to the original invoice is effectively mandatory; each item requires `id` and optional `issue_date` in `yyyy-MM-dd`.
`despatch_document_reference`	object	Optional	Client-provided	Reference to despatch/delivery document. See Despatch document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`receipt_document_reference`	object	Optional	Client-provided	Reference to receipt document. See Receipt document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`statement_document_reference`	object	Optional	Client-provided	Reference to statement document.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`originator_document_reference`	object	Optional	Client-provided	Reference to originating document (when applicable).	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`contract_document_reference`	object	Optional	Client-provided	Reference to contract. See Contract document reference object below.	If present: `id` required; `issue_date` `yyyy-MM-dd` when provided.
`accounting_supplier_party`	object	Required	Conditional (usually system-generated from profile)	The supplier party issuing the credit note. See Party object below.	Typically derived from the supplier profile for sales credit notes; if sent, must be a valid Party.
`accounting_customer_party`	object	Required	Client-provided	The customer party receiving the credit note. See Party object below.	Must be a valid Party object; required in create requests.
`buyer_customer_party`	object	Optional	Client-provided	Additional buyer party if different from accounting customer. See Party object below.	If present, must be a valid Party; may be validated against profile.
`seller_supplier_party`	object	Optional	Client-provided	Additional seller party if different from accounting supplier. See Party object below.	If present, must be a valid Party.
`payee_party`	object	Optional	Client-provided	The party to whom payment/refund should be made, if different from the supplier. See Payee party object below.	If present, must be a valid Payee party object.
`tax_representative_party`	object	Optional	Client-provided	Party authorized to represent the supplier for tax purposes. See Tax representative party object below.	If present, must be a valid Party (correct tax scheme and address).
`delivery`	object	Optional	Client-provided	Where and when the goods or services related to the credit note were delivered. See Delivery object below.	If present: `delivery_location` and `address` must be populated; may be mandatory for exports.
`payment_means`	array	Optional	Client-provided	Payment method(s). See Payment means below.	Optional `0..n` in every scenario, including every `transaction_type`. When an item is sent, code `30` requires `payee_financial_account`; `54`/`55` require `card_account`; `49` requires `payment_mandate`.
`payment_terms`	object	Optional	Client-provided	Payment terms and conditions associated with the credit note. See Payment terms object below.	If present: date fields (e.g. `installment_due_date`, `due_date`) must be `yyyy-MM-dd`.
`charges`	array	Optional	Client-provided	Document-level charges that adjust the amount (e.g. freight charge adjustment). See Document-level charge object.	If present: each charge must have a valid reason and amount/rate; tax category rules apply.
`allowances`	array	Optional	Client-provided	Document-level discounts/allowances (e.g. discount on returned items). See Document-level allowance object.	If present: each allowance must have a valid reason and amount/rate; tax category rules apply.
`tax_exchange_rate`	object	Optional	Client-provided	Exchange rate when tax currency differs from document currency. See Tax exchange rate object below.	Required when `tax_currency_code` differs from `document_currency_code`; must include `source_currency_code`, `target_currency_code`, and `calculation_rate`.
`prepaid_amount`	number	—	Client-provided	Total prepaid amount applied to the credit note.	Optional numeric; typically non-negative.
`payable_rounding_amount`	number	—	Client-provided	Rounding adjustment applied to payable amount.	Optional numeric; may be positive or negative depending on rounding direction.
`tax_breakdown`	array	—	Calculated	Tax amounts grouped by tax category and rate.	Response-only, generated from per-line tax categories.
`allowance_total_amount`	number	—	Calculated	Total of all document-level allowances.	Response-only, calculated from document-level allowances.
`charge_total_amount`	number	—	Calculated	Total of all document-level charges.	Response-only, calculated from document-level charges.
`line_extension_amount`	number	—	Calculated	Sum of all line amounts before charges, allowances, and taxes. UBL 2.1 LineExtensionAmount.	Response-only, derived from line net amounts.
`tax_exclusive_amount`	number	—	Calculated	Line extension plus charges minus allowances, before tax. UBL 2.1 TaxExclusiveAmount.	Response-only, calculated.
`tax_amount`	number	—	Calculated	Aggregated VAT amount in document currency. UBL 2.1 TaxTotal.	Response-only, calculated from tax breakdown.
`tax_amount_in_omr`	number	—	Calculated	Total tax amount converted to OMR.	Response-only, calculated using tax exchange rate (if applicable).
`tax_inclusive_amount`	number	—	Calculated	Tax exclusive amount plus total tax. UBL 2.1 TaxInclusiveAmount.	Response-only, calculated.
`payable_amount`	number	—	Calculated	Final amount to be refunded/credited. UBL 2.1 PayableAmount.	Response-only, calculated as tax inclusive minus prepayments/rounding.
`payable_amount_in_omr`	number	—	Calculated	Final amount payable in OMR.	Response-only, calculated using exchange rates.
`total_item_allowances`	number	—	Calculated	Total of all line-level allowances.	Response-only, sum over line-level allowances.
`total_item_charges`	number	—	Calculated	Total of all line-level charges.	Response-only, sum over line-level charges.
`total_taxable_amount`	number	—	Calculated	Total taxable amount for the credit note.	Response-only, derived from taxable lines and charges/allowances.
`total_non_taxable_amount`	number	—	Calculated	Total non-taxable amount.	Response-only, derived from non-taxable lines.
`document_lines`	array	Required	Client-provided	Credit note line items. See Document line object below.	Must contain at least one line; each line must satisfy the Document line object validation rules.
`seller_uuid`	string	Optional	Client-provided or system-generated	Seller identity UUID (BTOM-004). Auto-generated if omitted. See Invoice QR Code and Seller UUID.	Valid UUID format.
`qr_code_base64`	string	Optional	Client-provided or System-generated	Base64-encoded PNG QR code per Oman SRA v1.0.2. See Invoice QR Code and Seller UUID.	Valid Base64 format.
`uuid`	string	—	System-generated	Peppol network document identifier (distinct from `id` and `seller_uuid`).	Response-only; used internally for Peppol transmission. See Peppol Transmission Status.
`meta_info`	object	—	System-generated	Peppol transmission metadata.	Response-only. See Peppol Transmission Status.
`meta_info.peppol_status`	object	—	System-generated	Nested status with `participant_status`, `ota_status`, `overall_status`, `validation_results`.	See Peppol Transmission Status.
`document_source`	string	—	System-generated	Source of the credit note: `WEB`, `API`, or `PEPPOL`.	Create via API/UI typically returns `API` or `WEB`. Documents received over Peppol (e.g. inbound self-billed) are stored as `PEPPOL`. `GET .../peppol-status` uses received-messages when source is `PEPPOL`, otherwise sent-messages.

Document status

The status field is the document lifecycle flag (distinct from Peppol transmission status in meta_info.peppol_status).

Value	Meaning
`ACTIVE`	The current version of the document. Created documents start as `ACTIVE`. List endpoints return active documents only.
`OBSOLETE`	A superseded version after edit and resubmit. The obsolete document keeps its original `uuid` and remains retrievable by id; it cannot be resubmitted again.

For convenience, the shared nested object structures are documented below.

Party object

The accounting_supplier_party, accounting_customer_party, buyer_customer_party, and seller_supplier_party fields are objects with the following attributes:

Field	Type	Required	Description	Validation
`name`	string	Required	Party name or display name.	Must be non-empty text.
`party_name`	string	Required	Legal name of the party.	Must be non-empty text.
`profile_id`	string	Optional	Business profile identifier when referencing a registered profile.	If provided, must match an existing business profile.
`postal_address`	object	Required	Postal address. Must include OMN emirate code where applicable. See standard address structure (street_name, city_name, postal_zone, country, country_code, country_subentity).	Required; all mandatory address fields must be non-blank.
`scheme_agency_id`	string	Optional	Scheme agency identifier.	If present, must be one of `CR`, `TIN`, `PASNUM`, `CID`, `OTHID`, `ICID`, `SZLN`.
`company_id`	string	Optional	Company or registration number.	Free-form registration number; may be validated per jurisdiction.
`party_tax_scheme`	object	Required	Tax scheme with TRN. Contains `company_id`, `tax_scheme`.	Required for OMN VAT; must include a valid TRN and `tax_scheme` (usually `VAT`).
`endpoint_id`	string	Optional	Peppol endpoint identifier.	If present, must be a valid Peppol endpoint for Phase 2 documents.
`endpoint_scheme_id`	string	Optional	Peppol endpoint scheme identifier.	If present, must be a valid Peppol scheme id.

Payee party object

The payee_party field is an object with the following attributes:

Field	Type	Required	Description	Validation
`party_identification`	object	Optional	Payee identification.	Optional; structure depends on your implementation.
`party_name`	string	Optional	Name of the payee.	If provided, must be non-empty text.
`financial_account`	object	Optional	Financial account details for payment.	If present, must contain valid account identifiers as required by your bank.

Tax representative party object

The tax_representative_party field is an object with the following attributes:

Field	Type	Required	Description	Validation
`party_identification`	object	Optional	Tax representative identification.	Optional; should uniquely identify the tax representative where used.
`party_name`	string	Optional	Name of the tax representative.	If provided, must be non-empty.
`postal_address`	object	Optional	Address of the tax representative.	If present, must follow the same rules as standard postal addresses.

Delivery object

The delivery field is an object with the following attributes:

Field	Type	Required	Description	Validation
`delivery_location`	object	Optional	Location where goods or services are delivered.	If present, must include an `address` with valid address fields; required for exports.
`party_name`	string	Optional	Party Name.	If provided, must be non-empty text.
`party_id`	string	Optional	Party ID.	If present, must be an valid party id.
`terms`	string	Optional	Incoterm code.	If present, must be an valid incoterm code from the incoterms codelist.
`actual_delivery_date`	string	Optional	Actual date of delivery.	If present, format `yyyy-MM-dd`.

Order reference object

The order_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Order number or identifier.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Order date.	If present, format `yyyy-MM-dd`.
`sales_order_id`	string	Optional	Sales order identifier.	Free-form identifier.

Billing reference object

Each element of the billing_reference array is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Referenced document number.	Must be non-empty when the entry is present.
`issue_date`	string	Optional	Referenced document date.	If present, format `yyyy-MM-dd`.
`uuid`	string	Required	Referenced document UUID.	Must be non-empty. For standalone credit notes, use the Dummy UUID(`00000000-0000-0000-0000-000000000000`).

Despatch document reference object

The despatch_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Despatch document number.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Despatch document date.	If present, format `yyyy-MM-dd`.

Receipt document reference object

The receipt_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Receipt document number.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Receipt document date.	If present, format `yyyy-MM-dd`.

Statement document reference object

The statement_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Statement document number.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Statement document date.	If present, format `yyyy-MM-dd`.

Originator document reference object

The originator_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Originating document number or identifier.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Originating document date.	If present, format `yyyy-MM-dd`.

Contract document reference object

The contract_document_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Contract number or identifier.	Must be non-empty when the object is present.
`issue_date`	string	Optional	Contract date.	If present, format `yyyy-MM-dd`.

Project reference object

The project_reference field is an object with the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Required	Project identifier.	Must be non-empty when the object is present.
`name`	string	Optional	Project name.	Free text.

Document line object

Each element of the document_lines array is an object with the following attributes:

Field	Type	Required	Description	Validation
`name`	string	Required	Line item name.	Must be non-empty.
`description`	string	Optional	Line item description.	Free text.
`unit_code`	string	Required	Unit of measure code (e.g. `EA`). See Unit of Measure Codes.	Must be a valid UN/ECE Recommendation 20 code (e.g. `EA`, `KGM`, `LTR`, `C62`).
`quantity`	number	Required	Quantity.	Must be a positive number.
`price`	object	Required	Price. On create/update: `base_amount`, `base_quantity`. Responses return `price_amount` (net) instead of `base_amount`.	Must include `base_amount` on create; `base_quantity` should be positive when provided.
`base_amount`	number	Optional	Calculated line base amount (quantity × unit price).	Response-only; distinct from `price.base_amount` on create.
`net_amount`	number	Optional	Net amount.	Response-only; calculated.
`total_amount`	number	Optional	Total including tax.	Response-only; calculated.
`tax_amount`	number	Optional	Tax amount for the line.	Response-only; calculated from line tax.
`classified_tax_category`	object	Required	Tax category. Contains string `id` (`S`, `E`, `O`, `Z`), `percent`, `tax_scheme`; for `E` also `tax_exemption_reason_code` / `tax_exemption_reason`; for `Z` also `zero_rated_reason_code` / `zero_rated_reason`. See Tax Categories.	`id` must be a valid tax category; fields must match category rules.
`additional_item_identification`	array	Conditional	Client-provided	Industrial classification entries (BGOM-06 / BTOM-033). See Additional item identification object below.	Required on each line unless `transaction_type` is simplified, import of goods, import service RCM, or profit margin (IBR-081-OM). When provided, each `nature_code` must exist in the nature-code master list (`GET /api/codelist/nature-codes`).
`item_specification_document_reference`	object	Conditional	Client-provided	Item specification reference for service type classification. See Item specification document reference object below.	Required on each line unless `transaction_type` is simplified. When provided, `commodity_code` and `item_type` must be valid per OMN codelists.
`commodity_classification`	object	Optional	Client-provided	Commodity classification (e.g. Harmonised System). See Commodity classification object below.	If present, `item_classification_code` and `item_classification_list_id` are required; `item_classification_code` must exist in the item-classification master list (`GET /api/codelist/item-classification-codes`).
`charges`	array	Optional	Line-item charges that increase the line net amount. See Line-item charge object.	If present, each charge needs a reason and an amount or a rate. Do not send `tax_category`. Line VAT uses `classified_tax_category`.
`allowances`	array	Optional	Line-item allowances that reduce the line net amount. See Line-item allowance object.	If present, each allowance needs a reason and an amount or a rate. Do not send `tax_category`. Line VAT uses `classified_tax_category`.

Additional item identification object

Each element of the additional_item_identification array is an object with the following attributes:

Field	Type	Required	Description	Validation
`nature_code`	string	Required	Industrial Classification Code (BTOM-033). Emitted in UBL as `AdditionalItemIdentification/cbc:ID[@schemeName='CC']`.	Must exist in MongoDB `nature_code` / `GET /api/codelist/nature-codes` (e.g. `493001`).

Item specification document reference object

The item_specification_document_reference field on a document line is an object with the following attributes:

Field	Type	Required	Description	Validation
`commodity_code`	string	Required	Service type classification code.	Must be a valid code from the service type codelist (e.g. `70000000`).
`item_type`	string	Required	Item type indicator.	Must be one of `G` (Goods) or `S` (Services).

Commodity classification object

The commodity_classification field on a document line is an object with the following attributes:

Field	Type	Required	Description	Validation
`item_classification_code`	string	Required	Commodity classification code.	Must exist in MongoDB `item_classification_codes` / `GET /api/codelist/item-classification-codes` (e.g. `500200000000` for HS).
`item_classification_list_id`	string	Required	Classification scheme identifier.	Must be a valid scheme code (e.g. `HS` for Harmonised System).
`item_classification_list_version_id`	string	Optional	Classification scheme version.	Defaults to `1.0` if omitted in responses.

Document-level charge object

Each element of the document charges array increases the document total outside the line net. The total is returned in charge_total_amount. VAT for the charge is calculated from tax_category.

Provide reason or reason_code (at least one). Provide amount, or both multiplier_factor_numeric and base_amount. If amount is omitted and both rate fields are present, the amount is base_amount × multiplier_factor_numeric / 100. If amount is sent, that value is used. Send multiplier_factor_numeric and base_amount together, or omit both.

Field	Type	Required	Description	Validation
`reason_code`	string	Conditional	UNCL 7161 charge reason code.	Required when `reason` is omitted. Must be a valid charge reason code (e.g. `FC`).
`reason`	string	Conditional	Free-text charge reason.	Required when `reason_code` is omitted.
`amount`	number	Conditional	Charge amount in document currency.	Required unless both `multiplier_factor_numeric` and `base_amount` are sent. Numeric, usually ≥ 0.
`multiplier_factor_numeric`	number	Conditional	Percentage used to calculate the amount.	Send together with `base_amount`, or omit both.
`base_amount`	number	Conditional	Base amount the percentage applies to.	Send together with `multiplier_factor_numeric`, or omit both.
`tax_category`	object	Required	Tax category applied to this charge. Same shape as a line `classified_tax_category`: `id` (`S`, `E`, `O`, `Z`), `percent`, `tax_scheme`; for `E` also `tax_exemption_reason_code` and `tax_exemption_reason`; for `Z` also `zero_rated_reason_code` and `zero_rated_reason`.	Must be a valid tax category and align with the document VAT rules.

Document-level allowance object

Each element of the document allowances array reduces the document total outside the line net. The total is returned in allowance_total_amount. VAT for the allowance is calculated from tax_category.

Reason and amount rules match the document-level charge object.

Field	Type	Required	Description	Validation
`reason_code`	string	Conditional	UNCL 5189 allowance reason code.	Required when `reason` is omitted. Must be a valid allowance reason code (e.g. `95`).
`reason`	string	Conditional	Free-text allowance reason.	Required when `reason_code` is omitted.
`amount`	number	Conditional	Allowance amount in document currency.	Required unless both `multiplier_factor_numeric` and `base_amount` are sent. Numeric, usually ≥ 0.
`multiplier_factor_numeric`	number	Conditional	Percentage used to calculate the amount.	Send together with `base_amount`, or omit both.
`base_amount`	number	Conditional	Base amount the percentage applies to.	Send together with `multiplier_factor_numeric`, or omit both.
`tax_category`	object	Required	Tax category applied to this allowance. Same shape as a line `classified_tax_category`.	Must be a valid tax category and align with the document VAT rules.

Line-item charge object

Each element of document_lines[].charges increases that line's net amount before VAT. Line net is (price.base_amount / price.base_quantity) × quantity + line charges − line allowances. VAT uses the line classified_tax_category. The total of these charges is returned in total_item_charges.

Do not send tax_category on a line-item charge. Reason and amount rules match the document-level charge object.

Field	Type	Required	Description	Validation
`reason_code`	string	Conditional	UNCL 7161 charge reason code.	Required when `reason` is omitted. Must be a valid charge reason code (e.g. `FC`).
`reason`	string	Conditional	Free-text charge reason.	Required when `reason_code` is omitted.
`amount`	number	Conditional	Charge amount in document currency.	Required unless both `multiplier_factor_numeric` and `base_amount` are sent. Numeric, usually ≥ 0.
`multiplier_factor_numeric`	number	Conditional	Percentage used to calculate the amount.	Send together with `base_amount`, or omit both.
`base_amount`	number	Conditional	Base amount the percentage applies to.	Send together with `multiplier_factor_numeric`, or omit both.

Fixed amount:

{
  "reason_code": "FC",
  "reason": "Freight",
  "amount": 15.0
}

Percentage. The calculated amount is 200.0 × 10 / 100 = 20.0:

{
  "reason": "Packaging",
  "base_amount": 200.0,
  "multiplier_factor_numeric": 10.0
}

Line-item allowance object

Each element of document_lines[].allowances reduces that line's net amount before VAT. VAT uses the line classified_tax_category. The total of these allowances is returned in total_item_allowances.

Do not send tax_category on a line-item allowance. Reason and amount rules match the document-level allowance object.

Field	Type	Required	Description	Validation
`reason_code`	string	Conditional	UNCL 5189 allowance reason code.	Required when `reason` is omitted. Must be a valid allowance reason code (e.g. `95`).
`reason`	string	Conditional	Free-text allowance reason.	Required when `reason_code` is omitted.
`amount`	number	Conditional	Allowance amount in document currency.	Required unless both `multiplier_factor_numeric` and `base_amount` are sent. Numeric, usually ≥ 0.
`multiplier_factor_numeric`	number	Conditional	Percentage used to calculate the amount.	Send together with `base_amount`, or omit both.
`base_amount`	number	Conditional	Base amount the percentage applies to.	Send together with `multiplier_factor_numeric`, or omit both.

Fixed amount:

{
  "reason_code": "95",
  "reason": "Discount",
  "amount": 10.0
}

Percentage. The calculated amount is 200.0 × 5 / 100 = 10.0:

{
  "reason": "Line discount",
  "base_amount": 200.0,
  "multiplier_factor_numeric": 5.0
}

Payment means

The payment_means array is optional and may be omitted in every scenario, including every transaction_type. When you send an item, payment_means_code is required on that item. Nested account fields are required only for the codes listed below.

Each item has the following attributes:

Field	Type	Required	Description	Validation
`id`	string	Optional	Payment instructions ID.	Free text.
`payment_means_code`	string	Required	Payment means code (e.g. `30` for credit transfer). Required on each item when `payment_means` is sent.	Must be one of: `1`, `10`, `20`, `21`, `30`, `49`, `54`, `55`, `68`.
`payment_id`	array	Optional	Remittance / payment reference identifiers.	Array of strings; may be used for reconciliation.
`card_account`	object	Conditional	Card details. See Card account below.	Required when `payment_means_code` is `54` or `55`.
`payee_financial_account`	object	Conditional	Payee bank/financial account. See Payee financial account below.	Required when `payment_means_code` is `30`.
`payment_mandate`	object	Conditional	Direct debit mandate. See Payment mandate below.	Required when `payment_means_code` is `49`.

Card account

Field	Type	Required	Description	Validation
`primary_account_number_id`	string	Required	Card primary account number (masked PAN).	Required when `card_account` is present.
`network_id`	string	Required	Card network identifier.	Required when `card_account` is present; required for codes `54` and `55`.
`holder_name`	string	Optional	Card holder name.	Free text.

Payee financial account

Field	Type	Required	Description	Validation
`id`	string	Optional	Account identifier (e.g. IBAN).	Free text.
`name`	string	Optional	Account name.	Free text.
`financial_institution_branch_id`	string	Optional	Financial institution branch identifier.	Free text.
`address`	object	Optional	Account address.	If present, must be a valid address.

Payment mandate

Field	Type	Required	Description	Validation
`id`	string	Optional	Mandate identifier.	Free text.
`payer_financial_account_id`	string	Optional	Payer financial account identifier.	Free text.

Payment terms object

The payment_terms field is an object with the following attributes:

Field	Type	Required	Description	Validation
`note`	string	Optional	Payment terms description.	Free text.
`due_date`	string	Optional	Payment due date.	If present, format `yyyy-MM-dd`.
`installment_due_date`	string	Optional	Installment due date.	If present, format `yyyy-MM-dd`.
`amount`	number	Optional	Amount due.	Must be numeric if provided.

Tax exchange rate object

The tax_exchange_rate field is an object with the following attributes:

Field	Type	Required	Description	Validation
`source_currency_code`	string	Required	Source currency (ISO 4217).	Must be a valid ISO 4217 code.
`target_currency_code`	string	Required	Target currency (ISO 4217).	Must be a valid ISO 4217 code and usually match `tax_currency_code`.
`calculation_rate`	number	Required	Exchange rate for tax calculation.	Must be a positive numeric rate.

Response meta_info object

The meta_info field is an object with the following attributes:

Field	Type	Required	Description	Validation
`peppol_status`	object	Optional	Peppol participant/OTA processing status.	Response-only; see Peppol status object below.

Peppol status object

The meta_info.peppol_status field is an object with the following attributes:

Field	Type	Required	Description	Validation
`participant_status`	string	Optional	Participant-level processing status.	May be `null` in early or failed stages.
`ota_status`	string	Optional	OTA submission/processing status.	May be `null` in early or failed stages.
`overall_status`	string	Optional	Overall Peppol processing status.	Must be one of `PENDING`, `APPROVED`, `REJECTED`, `VALIDATION_FAILED`.
`validation_results`	array	Optional	Validation details/errors returned during processing.	Response-only list; empty when there are no validation issues.

Client processing guidance

For the full client processing guidance on Peppol status fields, see Peppol Transmission Status.