---
title: "Adjust a transaction"
method: POST
path: "/v1/transactions/adjustment"
---

# Adjust a transaction

`POST /v1/transactions/adjustment`

Create an adjustment for a previously submitted transaction.

Adjustment (also known as partial credit note) must reference the original transaction.

Use /adjustment endpoint for credit a subset of transaction (one or more line items).

## Request body

- TransactionRequest
  - `accounting_entry_date` string — The date of the accounting entry for an Account payable (AP) invoice/transaction Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `activity_code` string — Activity code is a standard classification of productive economic activities. It can be used to represent EAC (Economic Activity code), a standard classification governed by ISIC and NACE (https://joinup.ec.europa.eu/collection/eu-semantic-interoperability-catalogue/solution/statistical-classification-economic-activities-european-community/about), or other similar concepts. e.g., 10.32 is Manufacture of fruit and vegetable juice Validations: - Maximum length: 20
  - `attachments` TransactionAttachmentRequest[] — Attachments to be included in the transaction. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `content` string, required — Base64 encoded content of the attachment. Validations: - Required property - Maximum length: 1398101 - Must be a valid base64 encoded string.
    - `kind` string, required — Attachment kind. One of the following values: REPORT Validations: - Required property - Values allowed are (letter case matters): REPORT
    - `name` string, required — Name of the attachment. Validations: - Required property - Maximum length: 255 - Must end with .xml when type is XML. - Must end with .json when type is JSON.
    - `type` string, required — Attachment type. One of the following values: XML, JSON Validations: - Required property - Values allowed are (letter case matters): XML, JSON
  - `business_location` BusinessLocation
    - `name` string — The name of the business location.
  - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code the transaction is taking place in. Validations: - Country code must be uppercase ISO 3166-1 alpha-2. - Required property - Customer's address country code and transaction's country code must be different when operation regime is EXPORT.
  - `country_subdivision_code` string — ISO 3166-2 uppercase code of the principal country subdivision (province, state, region) the transaction is taking place in. Validations: - Values allowed are (letter case matters): AB, BC, MB, NB, NL, NS, NT, NU, ON, PE, QC, SK, YT - Values allowed are (letter case matters): AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY, DC - Country subdivision code is only supported for US and Canada.
  - `currency_code` string, required — Primary currency code of the transaction represented as ISO 4217 3 letter uppercase currency code e.g. `USD`. Validations: - Currency must be one of ISO 4217 codes. - Required property
  - `customer` union — Customer (sometimes called buyer) in a transaction. Can be an individual or a business. Can be omitted for most jurisdictions depending on the transaction size. In self-billing regime the customer must be a pre-onboarded entity (TransactionOnboardedEntity). Validations: - Customer entity should be onboarded in case of self-billing. For more information about onboarding refer to the public documentation.
    - object
      - `external_id` string — External resource identifier provided by the customer. e.g., MY_EXTERNAL_ID_001 Validations: - Maximum length: 150
      - `id` string, required — Fonoa id representing a resource within the system. e.g., a7cc64422fc247069aa64d4fe8b387c5 Validations: - Exact length: 32 - Supplier reference must be provided. Either supplier.id or supplier.external_id must be provided.
    - object
      - `address` TransactionEntityAddress
        - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
        - `address_line_2` string — Validations: - Length between 0 and 450
        - `canton` string — Validations: - Length between 0 and 100
        - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
        - `city_code` string — Validations: - Length between 0 and 20
        - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
        - `district` string — Validations: - Length between 0 and 100
        - `neighbourhood` string — Validations: - Length between 0 and 100
        - `number` string — Validations: - Length between 0 and 20
        - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
        - `prefix` string — Validations: - Length between 0 and 20
        - `province` string — Validations: - Length between 0 and 100
        - `region` string — Validations: - Length between 0 and 100
        - `state` string — Validations: - Length between 0 and 100
        - `suffix` string — Validations: - Length between 0 and 20
      - `contact_details` TransactionEntityContactDetails
        - `email` string, required — Value to be used by the Tax Authority to forward messages to the customer. Validations: - Required property - Must be a valid email address.
        - `phone_number` string — The customer's phone number.
      - `entity_number` string — This is a company registration number if entity is a business or personal identifier if entity is an individual. e.g., 011589551 Validations: - Maximum length: 50
      - `entity_number_type` string — This is company or individual number type. e.g., 93 (Argentina - birth certificate) Validations: - Maximum length: 50
      - `legal_name` string, required — Full legal name of the company (or the individual). e.g., Acme LLC; John Fitzgerald Kennedy Validations: - Required property - Maximum length: 450
      - `role` string, required — Role of the entity in the transaction (e.g., RECIPIENT). Used to distinguish different types of secondary entities. Validations: - Must be provided for secondary entities.
      - `tax_information` TransactionEntityTaxInformation
        - `activity_code` string — Code representing the activity of the entity. Validations: - Maximum length: 50
        - `additional_tax_numbers` TransactionEntityTaxNumberCountrySpecific[] — Additional tax numbers used by the entity in domestic or foreign operations Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
          - `business_model` string[] — Applicable transaction business models (optional).
          - `country_code` string — Country where provided tax number should be used.
          - `country_subdivision_code` string — Country subdivision code where tax number should be used (optional).
          - `tax_number` string — Tax number.
          - `type` string — The tax number type (optional).
        - `distribution_address` string — Value to be used by the Tax Authority to forward the reported invoice to the customer/buyer Validations: - Maximum length: 256
        - `regime` string — Tax regime the entity is registered with. e.g., VAT Validations: - Maximum length: 10
        - `tax_code` string — Tax code that complements tax number.
        - `tax_number` string — Tax number of tax registered entity. e.g., 69061864-2-99 Validations: - Maximum length: 50
      - `trade_name` string — The name the company (or the individual) uses to do business. e.g., Acme; John F Kennedy Validations: - Maximum length: 450
      - `type` string, required — Entity type defining the type of the transaction (B2B, B2C, B2G). Validations: - Required property - Values allowed are (ignore case): BUSINESS, INDIVIDUAL, ECONOMIC_OPERATOR
  - `decimal_amounts` boolean — A flag to be used in a migration phase. It signals in which format amounts should be parsed. If true amounts are parsed as decimals, if false amounts are parsed as an integer representing the minor currency unit.
  - `direction` string — Document representing a transaction can be sent or received. Allows businesses to report both inbound and outbound transactions for VAT deduction purposes. Default: `SENT`. Validations: - Maximum length: 20 - Values allowed are (letter case matters): SENT, RECEIVED
  - `document_references` DocumentReference[] — List of document references related to the transaction, such as transport documents, customs documents, or other relevant references. The property applies only for France,Germany,Costa Rica Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `identifier` string, required — Buyer’s document reference identifier (e.g., PO number) identifying the document this invoice relates to. Validations: - Required property
    - `issue_date` string — Date when the referenced document was issued. Validations: - Must be an RFC3339 format date
    - `reason` string — Reason for the document reference.
    - `tender_reference` string — Identifier of the procurement procedure or tender associated with the referenced document.
    - `type` string — Type of the document reference.
  - `end_date` string — RFC3339 datetime string representing an ending point in time. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `frequency` string — Describes the frequency of reporting invoices to tax authority, used with SUMMARY invoice types.
  - `issue_date` string — The date when the transaction was issued by an external application. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `issuer` TransactionNonOnboardedEntity
    - `address` TransactionEntityAddress
      - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
      - `address_line_2` string — Validations: - Length between 0 and 450
      - `canton` string — Validations: - Length between 0 and 100
      - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
      - `city_code` string — Validations: - Length between 0 and 20
      - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
      - `district` string — Validations: - Length between 0 and 100
      - `neighbourhood` string — Validations: - Length between 0 and 100
      - `number` string — Validations: - Length between 0 and 20
      - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
      - `prefix` string — Validations: - Length between 0 and 20
      - `province` string — Validations: - Length between 0 and 100
      - `region` string — Validations: - Length between 0 and 100
      - `state` string — Validations: - Length between 0 and 100
      - `suffix` string — Validations: - Length between 0 and 20
    - `contact_details` TransactionEntityContactDetails
      - `email` string, required — Value to be used by the Tax Authority to forward messages to the customer. Validations: - Required property - Must be a valid email address.
      - `phone_number` string — The customer's phone number.
    - `entity_number` string — This is a company registration number if entity is a business or personal identifier if entity is an individual. e.g., 011589551 Validations: - Maximum length: 50
    - `entity_number_type` string — This is company or individual number type. e.g., 93 (Argentina - birth certificate) Validations: - Maximum length: 50
    - `legal_name` string, required — Full legal name of the company (or the individual). e.g., Acme LLC; John Fitzgerald Kennedy Validations: - Required property - Maximum length: 450
    - `role` string, required — Role of the entity in the transaction (e.g., RECIPIENT). Used to distinguish different types of secondary entities. Validations: - Must be provided for secondary entities.
    - `tax_information` TransactionEntityTaxInformation
      - `activity_code` string — Code representing the activity of the entity. Validations: - Maximum length: 50
      - `additional_tax_numbers` TransactionEntityTaxNumberCountrySpecific[] — Additional tax numbers used by the entity in domestic or foreign operations Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
        - `business_model` string[] — Applicable transaction business models (optional).
        - `country_code` string — Country where provided tax number should be used.
        - `country_subdivision_code` string — Country subdivision code where tax number should be used (optional).
        - `tax_number` string — Tax number.
        - `type` string — The tax number type (optional).
      - `distribution_address` string — Value to be used by the Tax Authority to forward the reported invoice to the customer/buyer Validations: - Maximum length: 256
      - `regime` string — Tax regime the entity is registered with. e.g., VAT Validations: - Maximum length: 10
      - `tax_code` string — Tax code that complements tax number.
      - `tax_number` string — Tax number of tax registered entity. e.g., 69061864-2-99 Validations: - Maximum length: 50
    - `trade_name` string — The name the company (or the individual) uses to do business. e.g., Acme; John F Kennedy Validations: - Maximum length: 450
    - `type` string, required — Entity type defining the type of the transaction (B2B, B2C, B2G). Validations: - Required property - Values allowed are (ignore case): BUSINESS, INDIVIDUAL, ECONOMIC_OPERATOR
  - `items` TransactionLineItem[], required — Goods, services, and discounts exchanged in a transaction. Validations: - Must not be empty. - Must be empty for PASS_THROUGH transactions. - Reference Item Number must reference actual Item Number. - Transaction item numbers must be unique. - Discount and fee tax rates must match the referenced item tax rates. - Discount items must be margin when referencing margin line items or when all line items are margin. - All or no items should reference a transaction. - Discount and fee items applied to this transactions must reference items that are not a discount or fee item. - The transaction may not have more than {{.max}} items. Please reach out to Fonoa support to learn about the alternatives. - A transaction with item level references may not have more than {{.max}} items. Please reach out to Fonoa support to learn about the alternatives.
    - `code` string — Item code used by Tax Authorities to classify transaction items. For example HSN (Harmonized System of Nomenclature). e.g., 08081000 - Apple More info can be found here - https://www.tariffnumber.com/" Validations: - Maximum length: 60
    - `description` string — Description of an item required for SAF-T documents in PT. Not displayed on a visual document. e.g., Chocolate cookies taste better with milk. Validations: - Maximum length: 200
    - `details` TransactionLineItemDetail[] — Additional details describing the line item. Validations: - Transaction line item details are not supported.
      - `name` string, required — Description of the line item detail that will be shared with the tax authority in supported countries. Validations: - Required property
      - `net_price` number — Net price of the line item detail. Indicated price excludes Tax. Validations: - Cannot exceed the maximum allowed precision.
      - `quantity` number — Quantity of the line item detail. Validations: - Cannot exceed the maximum allowed precision.
    - `ean` string — European article number (EAN) also known as International article number - EAN 13 - 13 digit barcode mandatory for PT reporting scenarios. e.g. 5012345678900. The property applies only for Portugal,Kenya Validations: - Maximum length: 13
    - `imported_content_code` string — Code for import content declaration. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `name` string, required — Item name displayed on an invoice. e.g., Chocolate cookies Validations: - Required property - Maximum length: 200
    - `net_price` number — A high precision decimal representing the item net price. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
    - `number` integer, required — Ordinal number of the item in a transaction. e.g., 1 Validations: - Required property - Value must be greater than 0
    - `operation_nature_code` string — The code of the nature of this item in the transaction. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `product_classification_code` string — Identifies the product using a standardized classification system. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `quantity` number, required — Non-zero high precision decimal representing the quantity of units of the line item. e.g., 3.1. Validations: - Required property - Value must be greater than 0
    - `reason` string — The reason this item is included on the invoice. Typically reserved for adjustments. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `reference_number` integer — Non-zero integer referring to one of the line items. Can be used only when item type is DISCOUNT indicating that the discount is applied to a specific item. If not specified, the discount is applied to the entire transaction. Item cannot reference itself. Validations: - Item cannot reference itself. - Item reference number can be applied only when item type is discount.
    - `reference_transaction_id` string — The external transaction identifier of the original transaction the adjustment is referencing. It is used when attempting to create a unique adjustment with multiple references. Each reference being a single item. Validations: - Reference transaction id is not supported.
    - `reference_transaction_item_number` integer — Non-zero integer referring to the referenced transaction item the adjustment should be applied to. If not specified, the adjustment is applied to the entire referenced transaction. Validations: - Reference transaction item number is not supported.
    - `tax_breakdown` TransactionLineItemTaxBreakdown[] — Taxes applied to a line item Validations: - Can contain only 1 tax breakdown when a breakdown with code=MARGIN is present.
      - `amount` number — A high precision decimal representing the tax amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
      - `application_mode` string — Defines what's the tax basis for the tax calculation and how it is applied. ADD_TO_UNIT_PRICE: uses the item's net price as the basis for tax calculation and adds to it. INCLUDED_IN_UNIT_PRICE: uses the item's total amount as the basis for tax calculation and doesn't add to it. When not specified, it is set to ADD_TO_UNIT_PRICE. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard. - Values allowed are (letter case matters): ADD_TO_UNIT_PRICE, INCLUDED_IN_UNIT_PRICE
      - `code` string — Tax code required by some tax authorities to justify the application of this tax, typically for items that are tax-exempt. The list of codes depends on the jurisdiction. e.g., M11 - Portuguese tobacco regime Set value MARGIN to indicate margin scheme items like second-hand goods, antiques and so on. Validations: - Maximum length: 10 - margin scheme items must have 0 tax rate. - margin scheme items must have 0 tax amount.
      - `compound_base_types` string[] — Defines which other taxes contribute to the base of the compound tax, with the taxable amount being calculated as `item.net_price + sum(compound_base_types[].amount)`. This allows for explicit modeling of dependencies between tax components where one tax is calculated on top of others. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
      - `description` string — Description required by some tax authorities to justify the application of this tax, typically for items that are tax-exempt. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
      - `rate` number, required — Non-negative tax rate percentage applied to an item. e.g. 25. Validations: - Required property - Value must be greater or equal to 0
      - `regime` string, required — Name of the tax regime. e.g., VAT Validations: - Required property - Maximum length: 10
      - `type` string — Tax type required by some tax authorities. e.g., PT tax authorities have different tax types per region. e.g., PT-MA - Madeira region tax type. Validations: - Maximum length: 10
    - `tax_point_date` string — Date when the tax point for this line item occurs. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `type` string — Type of item in a transaction either GOODS, SERVICES, or DISCOUNT. Validations: - Values allowed are (letter case matters): GOODS, SERVICES, DISCOUNT
    - `unit` string — Unit of measurement for the item. e.g., pcs. Validations: - Maximum length: 20
    - `unit_price` number, required — A high-precision decimal amount representing the price of a single unit. The amount should not include any taxes calculated based on the item's net price. However, it should include any taxes calculated based on the item's total amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Required property - Cannot exceed the maximum allowed precision of 9 decimals.
  - `labels` TransactionLabel[] — A list of transaction labels to be applied to the generated document. Labels are not supported in all countries, please see the Country Integration Guides for details. Validations: - Cannot contain more than {{.max}} labels, provided {{.actual}}.
    - `label` string, required — The descriptive name of the label Validations: - Required property - Maximum length: 35
    - `value` string, required — The value associated with the label Validations: - Required property - Maximum length: 35
  - `language_code` string, required — Language of the transaction document represented as ISO 639-1 uppercase language code. Required when document generation is enabled. Defaults to EN (English) if not provided. Validations: - Language of the transaction must be uppercase ISO 639-1. - Required property
  - `note` string — A text note attached to a transaction. Notes are HTML enabled and will be displayed on the visual document. Validations: - Maximum length: 3000
  - `operation_regime` string — A value describing the operation regime for the transaction if applicable. e.g., export - indicating the transaction should be reported as cross-border transaction. Validations: - Values allowed are (letter case matters): GENERAL, SELF_BILLING
  - `operation_regime_details` string — A value providing additional information on the specified operation regime. e.g., providing a tax authority supported export type. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `operational_context` OperationalContext
    - `line_of_business` string — Classification of the business line this transaction belongs to. Used by Fonoa for pre-agreed purposes such as separate billing or data routing. Validations: - Maximum length: 100
    - `source_system` string — Identifier for the internal system or application within the customer's organization that originated this transaction. Validations: - Maximum length: 100
  - `operator` union — Operator in a transaction. Usually the individual (employee) responsible for creating the transaction. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - object
      - `external_id` string — External resource identifier provided by the customer. e.g., MY_EXTERNAL_ID_001 Validations: - Maximum length: 150
      - `id` string, required — Fonoa id representing a resource within the system. e.g., a7cc64422fc247069aa64d4fe8b387c5 Validations: - Exact length: 32 - Supplier reference must be provided. Either supplier.id or supplier.external_id must be provided.
    - object
      - `address` TransactionEntityAddress
        - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
        - `address_line_2` string — Validations: - Length between 0 and 450
        - `canton` string — Validations: - Length between 0 and 100
        - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
        - `city_code` string — Validations: - Length between 0 and 20
        - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
        - `district` string — Validations: - Length between 0 and 100
        - `neighbourhood` string — Validations: - Length between 0 and 100
        - `number` string — Validations: - Length between 0 and 20
        - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
        - `prefix` string — Validations: - Length between 0 and 20
        - `province` string — Validations: - Length between 0 and 100
        - `region` string — Validations: - Length between 0 and 100
        - `state` string — Validations: - Length between 0 and 100
        - `suffix` string — Validations: - Length between 0 and 20
      - `contact_details` TransactionEntityContactDetails
        - `email` string, required — Value to be used by the Tax Authority to forward messages to the customer. Validations: - Required property - Must be a valid email address.
        - `phone_number` string — The customer's phone number.
      - `entity_number` string — This is a company registration number if entity is a business or personal identifier if entity is an individual. e.g., 011589551 Validations: - Maximum length: 50
      - `entity_number_type` string — This is company or individual number type. e.g., 93 (Argentina - birth certificate) Validations: - Maximum length: 50
      - `legal_name` string, required — Full legal name of the company (or the individual). e.g., Acme LLC; John Fitzgerald Kennedy Validations: - Required property - Maximum length: 450
      - `role` string, required — Role of the entity in the transaction (e.g., RECIPIENT). Used to distinguish different types of secondary entities. Validations: - Must be provided for secondary entities.
      - `tax_information` TransactionEntityTaxInformation
        - `activity_code` string — Code representing the activity of the entity. Validations: - Maximum length: 50
        - `additional_tax_numbers` TransactionEntityTaxNumberCountrySpecific[] — Additional tax numbers used by the entity in domestic or foreign operations Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
          - `business_model` string[] — Applicable transaction business models (optional).
          - `country_code` string — Country where provided tax number should be used.
          - `country_subdivision_code` string — Country subdivision code where tax number should be used (optional).
          - `tax_number` string — Tax number.
          - `type` string — The tax number type (optional).
        - `distribution_address` string — Value to be used by the Tax Authority to forward the reported invoice to the customer/buyer Validations: - Maximum length: 256
        - `regime` string — Tax regime the entity is registered with. e.g., VAT Validations: - Maximum length: 10
        - `tax_code` string — Tax code that complements tax number.
        - `tax_number` string — Tax number of tax registered entity. e.g., 69061864-2-99 Validations: - Maximum length: 50
      - `trade_name` string — The name the company (or the individual) uses to do business. e.g., Acme; John F Kennedy Validations: - Maximum length: 450
      - `type` string, required — Entity type defining the type of the transaction (B2B, B2C, B2G). Validations: - Required property - Values allowed are (ignore case): BUSINESS, INDIVIDUAL, ECONOMIC_OPERATOR
  - `payment_details` TransactionPaymentDetail[] — Payment details for the transaction. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `bank_info` PaymentDetailBankInfo
      - `account_holder_name` string — The name of the account holder as registered with the bank. Validations: - Maximum length: 100
      - `account_number` string — Bank account number used for the payment. e.g., 1234567890 Validations: - Maximum length: 100
      - `bank_identifier` string — Bank identifier used for the payment. e.g., ZABAHR2X Validations: - Maximum length: 100
      - `bank_name` string — Name of the bank where the payment was made. e.g., Bank of America Validations: - Maximum length: 100
    - `condition` string — Indicates the structure of payment. Acceptable values are: FULL (One-time payment for the full amount), INSTALLMENTS (Multiple scheduled payments), or ADVANCE (Prepayment before goods/services are delivered). Validations: - Values allowed are (letter case matters): FULL, INSTALLMENTS, ADVANCE
    - `payments` TransactionPayment[] — The list of payments related to the condition specified.
      - `amount` number — A high precision decimal representing the amount paid by the payment type. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
      - `card_brand` string — Card brand used for the payment. e.g., Visa, MasterCard, Amex Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
      - `code` string — Payment type code required by some tax authorities. e.g., single payment, deferred payment, installments... e.g., PUE - Mexican payment code for single payment. Validations: - Maximum length: 32
      - `date_of_payment` string — Date of the payment. e.g., 2021-01-01T00:00:00Z Validations: - Must be an RFC3339 format date
      - `payment_processor` PaymentProcessor
        - `authorization_code` string — Authorization code of the payment processor. e.g., 123456 Validations: - Maximum length: 100
        - `integration_type` string — Type of integration with the payment processor Validations: - Values allowed are (letter case matters): NOT_INTEGRATED, INTEGRATED
        - `tax_number` string — Tax number of the payment processor. e.g., 69061864-2-99 Validations: - Maximum length: 100
        - `terminal_id` string — Terminal ID of the payment processor. e.g., 1234567890 Validations: - Maximum length: 100
      - `payment_reference` string — Visual representation of payment like payment ID or payment reference Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
      - `settlements` PaymentSettlement[] — A list of payment settlements representing how this payment is applied against one or more prior transactions. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
        - `instalment_number` integer — The sequential number of the instalment this settlement represents (e.g., 1 for the first payment, 2 for the second).
        - `outstanding_balance` number — The remaining unpaid balance on the original transaction after this settlement is applied.
        - `reference_transaction_id` string — The external transaction identifier of the original transaction that this payment is settles.
        - `settled_amounts` SettledAmount[] — A list detailing how the payment amount is allocated - including the base (untaxed) amounts and any associated taxes.
          - `base_amount` number — The untaxed portion of the settled amount.
          - `tax_breakdown` TransactionLineItemTaxBreakdown[] — A detailed list of applied taxes (e.g., VAT, withholding, etc.) corresponding to this settled base amount.
            - `amount` number — A high precision decimal representing the tax amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
            - `application_mode` string — Defines what's the tax basis for the tax calculation and how it is applied. ADD_TO_UNIT_PRICE: uses the item's net price as the basis for tax calculation and adds to it. INCLUDED_IN_UNIT_PRICE: uses the item's total amount as the basis for tax calculation and doesn't add to it. When not specified, it is set to ADD_TO_UNIT_PRICE. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard. - Values allowed are (letter case matters): ADD_TO_UNIT_PRICE, INCLUDED_IN_UNIT_PRICE
            - `code` string — Tax code required by some tax authorities to justify the application of this tax, typically for items that are tax-exempt. The list of codes depends on the jurisdiction. e.g., M11 - Portuguese tobacco regime Set value MARGIN to indicate margin scheme items like second-hand goods, antiques and so on. Validations: - Maximum length: 10 - margin scheme items must have 0 tax rate. - margin scheme items must have 0 tax amount.
            - `compound_base_types` string[] — Defines which other taxes contribute to the base of the compound tax, with the taxable amount being calculated as `item.net_price + sum(compound_base_types[].amount)`. This allows for explicit modeling of dependencies between tax components where one tax is calculated on top of others. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
            - `description` string — Description required by some tax authorities to justify the application of this tax, typically for items that are tax-exempt. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
            - `rate` number, required — Non-negative tax rate percentage applied to an item. e.g. 25. Validations: - Required property - Value must be greater or equal to 0
            - `regime` string, required — Name of the tax regime. e.g., VAT Validations: - Required property - Maximum length: 10
            - `type` string — Tax type required by some tax authorities. e.g., PT tax authorities have different tax types per region. e.g., PT-MA - Madeira region tax type. Validations: - Maximum length: 10
      - `type` string, required — Free text input or one of predefined values representing payment type. Predefined values (CARD, CASH, CHECK, TRANSACTION, CREDITCARD, DEBITCARD, OTHER) are localized. e.g., CARD ending in 2022 Validations: - Maximum length: 32 - Required property
  - `payment_due_date` string — RFC3339 datetime string representing the deadline until which the payment must be made. Validations: - payment_due_date is not supported for the provided country
  - `payments` TransactionPayment[] — A list of transaction payments. The sum of all payment amounts must match the total transaction amount. i.e., sum(payments[].amount) == sum(items[].quantity * items[].unit_price * (1 + sum(tax_breakdown[].rate)/100)) Validations: - Sum of payment amounts must be equal to total transaction amount.
    - `amount` number — A high precision decimal representing the amount paid by the payment type. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
    - `card_brand` string — Card brand used for the payment. e.g., Visa, MasterCard, Amex Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `code` string — Payment type code required by some tax authorities. e.g., single payment, deferred payment, installments... e.g., PUE - Mexican payment code for single payment. Validations: - Maximum length: 32
    - `date_of_payment` string — Date of the payment. e.g., 2021-01-01T00:00:00Z Validations: - Must be an RFC3339 format date
    - `payment_processor` PaymentProcessor
      - `authorization_code` string — Authorization code of the payment processor. e.g., 123456 Validations: - Maximum length: 100
      - `integration_type` string — Type of integration with the payment processor Validations: - Values allowed are (letter case matters): NOT_INTEGRATED, INTEGRATED
      - `tax_number` string — Tax number of the payment processor. e.g., 69061864-2-99 Validations: - Maximum length: 100
      - `terminal_id` string — Terminal ID of the payment processor. e.g., 1234567890 Validations: - Maximum length: 100
    - `payment_reference` string — Visual representation of payment like payment ID or payment reference Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `settlements` PaymentSettlement[] — A list of payment settlements representing how this payment is applied against one or more prior transactions. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
      - `instalment_number` integer — The sequential number of the instalment this settlement represents (e.g., 1 for the first payment, 2 for the second).
      - `outstanding_balance` number — The remaining unpaid balance on the original transaction after this settlement is applied.
      - `reference_transaction_id` string — The external transaction identifier of the original transaction that this payment is settles.
      - `settled_amounts` SettledAmount[] — A list detailing how the payment amount is allocated - including the base (untaxed) amounts and any associated taxes.
        - `base_amount` number — The untaxed portion of the settled amount.
        - `tax_breakdown` TransactionLineItemTaxBreakdown[] — A detailed list of applied taxes (e.g., VAT, withholding, etc.) corresponding to this settled base amount.
          - `amount` number — A high precision decimal representing the tax amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
          - `application_mode` string — Defines what's the tax basis for the tax calculation and how it is applied. ADD_TO_UNIT_PRICE: uses the item's net price as the basis for tax calculation and adds to it. INCLUDED_IN_UNIT_PRICE: uses the item's total amount as the basis for tax calculation and doesn't add to it. When not specified, it is set to ADD_TO_UNIT_PRICE. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard. - Values allowed are (letter case matters): ADD_TO_UNIT_PRICE, INCLUDED_IN_UNIT_PRICE
          - `code` string — Tax code required by some tax authorities to justify the application of this tax, typically for items that are tax-exempt. The list of codes depends on the jurisdiction. e.g., M11 - Portuguese tobacco regime Set value MARGIN to indicate margin scheme items like second-hand goods, antiques and so on. Validations: - Maximum length: 10 - margin scheme items must have 0 tax rate. - margin scheme items must have 0 tax amount.
          - `compound_base_types` string[] — Defines which other taxes contribute to the base of the compound tax, with the taxable amount being calculated as `item.net_price + sum(compound_base_types[].amount)`. This allows for explicit modeling of dependencies between tax components where one tax is calculated on top of others. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
          - `description` string — Description required by some tax authorities to justify the application of this tax, typically for items that are tax-exempt. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
          - `rate` number, required — Non-negative tax rate percentage applied to an item. e.g. 25. Validations: - Required property - Value must be greater or equal to 0
          - `regime` string, required — Name of the tax regime. e.g., VAT Validations: - Required property - Maximum length: 10
          - `type` string — Tax type required by some tax authorities. e.g., PT tax authorities have different tax types per region. e.g., PT-MA - Madeira region tax type. Validations: - Maximum length: 10
    - `type` string, required — Free text input or one of predefined values representing payment type. Predefined values (CARD, CASH, CHECK, TRANSACTION, CREDITCARD, DEBITCARD, OTHER) are localized. e.g., CARD ending in 2022 Validations: - Maximum length: 32 - Required property
  - `place_of_supply` TransactionEntityAddress
    - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
    - `address_line_2` string — Validations: - Length between 0 and 450
    - `canton` string — Validations: - Length between 0 and 100
    - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
    - `city_code` string — Validations: - Length between 0 and 20
    - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
    - `district` string — Validations: - Length between 0 and 100
    - `neighbourhood` string — Validations: - Length between 0 and 100
    - `number` string — Validations: - Length between 0 and 20
    - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
    - `prefix` string — Validations: - Length between 0 and 20
    - `province` string — Validations: - Length between 0 and 100
    - `region` string — Validations: - Length between 0 and 100
    - `state` string — Validations: - Length between 0 and 100
    - `suffix` string — Validations: - Length between 0 and 20
  - `pos_device` PosDevice
    - `code` string — The code of the pos device.
  - `purchase_orders` DocumentReference[] — Buyer’s purchase orders information (e.g., PO number) this document relates to. The property applies only for Ghana,Italy,Nigeria Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `identifier` string, required — Buyer’s document reference identifier (e.g., PO number) identifying the document this invoice relates to. Validations: - Required property
    - `issue_date` string — Date when the referenced document was issued. Validations: - Must be an RFC3339 format date
    - `reason` string — Reason for the document reference.
    - `tender_reference` string — Identifier of the procurement procedure or tender associated with the referenced document.
    - `type` string — Type of the document reference.
  - `reference_transaction_id` string — The external transaction identifier of the original transaction the credit is referencing. e.g., MY_ORIGINAL_IDENTIFIER_0001 Validations: - Maximum length: 150 - And other transaction refences (in items and payments) cannot be provided together.
  - `secondary_currency` TransactionSecondaryCurrency
    - `currency_code` string, required — ISO 4217 currency code of the secondary transaction currency. e.g., MXN Validations: - Currency must be one of ISO 4217 codes. - Required property
    - `exchange_date` string — Date of the currency exchange rate. e.g., 2021-01-01T00:00:00Z Validations: - Must be an RFC3339 format date
    - `exchange_rate` number, required — Currency exchange rate between main and secondary transaction currency. Example: main currency USD, secondary currency MXN. Exchange rate is 18.38 because 1 USD is 18.38 MXN as of today. Validations: - Required property - Value must be greater than 0
  - `secondary_entities` TransactionNonOnboardedEntity[] — Secondary entities involved in the transaction. e.g., buyer agency, buyer branch information, supplier payee, etc. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `address` TransactionEntityAddress
      - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
      - `address_line_2` string — Validations: - Length between 0 and 450
      - `canton` string — Validations: - Length between 0 and 100
      - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
      - `city_code` string — Validations: - Length between 0 and 20
      - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
      - `district` string — Validations: - Length between 0 and 100
      - `neighbourhood` string — Validations: - Length between 0 and 100
      - `number` string — Validations: - Length between 0 and 20
      - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
      - `prefix` string — Validations: - Length between 0 and 20
      - `province` string — Validations: - Length between 0 and 100
      - `region` string — Validations: - Length between 0 and 100
      - `state` string — Validations: - Length between 0 and 100
      - `suffix` string — Validations: - Length between 0 and 20
    - `contact_details` TransactionEntityContactDetails
      - `email` string, required — Value to be used by the Tax Authority to forward messages to the customer. Validations: - Required property - Must be a valid email address.
      - `phone_number` string — The customer's phone number.
    - `entity_number` string — This is a company registration number if entity is a business or personal identifier if entity is an individual. e.g., 011589551 Validations: - Maximum length: 50
    - `entity_number_type` string — This is company or individual number type. e.g., 93 (Argentina - birth certificate) Validations: - Maximum length: 50
    - `legal_name` string, required — Full legal name of the company (or the individual). e.g., Acme LLC; John Fitzgerald Kennedy Validations: - Required property - Maximum length: 450
    - `role` string, required — Role of the entity in the transaction (e.g., RECIPIENT). Used to distinguish different types of secondary entities. Validations: - Must be provided for secondary entities.
    - `tax_information` TransactionEntityTaxInformation
      - `activity_code` string — Code representing the activity of the entity. Validations: - Maximum length: 50
      - `additional_tax_numbers` TransactionEntityTaxNumberCountrySpecific[] — Additional tax numbers used by the entity in domestic or foreign operations Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
        - `business_model` string[] — Applicable transaction business models (optional).
        - `country_code` string — Country where provided tax number should be used.
        - `country_subdivision_code` string — Country subdivision code where tax number should be used (optional).
        - `tax_number` string — Tax number.
        - `type` string — The tax number type (optional).
      - `distribution_address` string — Value to be used by the Tax Authority to forward the reported invoice to the customer/buyer Validations: - Maximum length: 256
      - `regime` string — Tax regime the entity is registered with. e.g., VAT Validations: - Maximum length: 10
      - `tax_code` string — Tax code that complements tax number.
      - `tax_number` string — Tax number of tax registered entity. e.g., 69061864-2-99 Validations: - Maximum length: 50
    - `trade_name` string — The name the company (or the individual) uses to do business. e.g., Acme; John F Kennedy Validations: - Maximum length: 450
    - `type` string, required — Entity type defining the type of the transaction (B2B, B2C, B2G). Validations: - Required property - Values allowed are (ignore case): BUSINESS, INDIVIDUAL, ECONOMIC_OPERATOR
  - `series` string — A pool of transaction numbers issued by tax authorities to pick the transaction number from. The transaction shall be assigned one of the numbers from this pool when reporting it to the tax authorities. Usually series can be opened and closed at any time and there can be multiple open series at the same time. e.g., 2022_01 Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `signature` string — The transaction signature generated by an external application. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `signature_date` string — The date of the transaction signature generated by an external application. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `start_date` string — RFC3339 datetime string representing a starting point in time. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `supplier` union, required — Supplier entity referenced by either Fonoa ID or customer provided ID. If both values are provided, Fonoa ID has precedance over external ID. In self-billing regime supplier can be non onboarded (TransactionNonOnboardedEntity). Validations: - Required property - Supplier entity should be onboarded in any case other than self-billing. For more information about onboarding refer to the public documentation.
    - object
      - `external_id` string — External resource identifier provided by the customer. e.g., MY_EXTERNAL_ID_001 Validations: - Maximum length: 150
      - `id` string, required — Fonoa id representing a resource within the system. e.g., a7cc64422fc247069aa64d4fe8b387c5 Validations: - Exact length: 32 - Supplier reference must be provided. Either supplier.id or supplier.external_id must be provided.
    - object
      - `address` TransactionEntityAddress
        - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
        - `address_line_2` string — Validations: - Length between 0 and 450
        - `canton` string — Validations: - Length between 0 and 100
        - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
        - `city_code` string — Validations: - Length between 0 and 20
        - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
        - `district` string — Validations: - Length between 0 and 100
        - `neighbourhood` string — Validations: - Length between 0 and 100
        - `number` string — Validations: - Length between 0 and 20
        - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
        - `prefix` string — Validations: - Length between 0 and 20
        - `province` string — Validations: - Length between 0 and 100
        - `region` string — Validations: - Length between 0 and 100
        - `state` string — Validations: - Length between 0 and 100
        - `suffix` string — Validations: - Length between 0 and 20
      - `contact_details` TransactionEntityContactDetails
        - `email` string, required — Value to be used by the Tax Authority to forward messages to the customer. Validations: - Required property - Must be a valid email address.
        - `phone_number` string — The customer's phone number.
      - `entity_number` string — This is a company registration number if entity is a business or personal identifier if entity is an individual. e.g., 011589551 Validations: - Maximum length: 50
      - `entity_number_type` string — This is company or individual number type. e.g., 93 (Argentina - birth certificate) Validations: - Maximum length: 50
      - `legal_name` string, required — Full legal name of the company (or the individual). e.g., Acme LLC; John Fitzgerald Kennedy Validations: - Required property - Maximum length: 450
      - `role` string, required — Role of the entity in the transaction (e.g., RECIPIENT). Used to distinguish different types of secondary entities. Validations: - Must be provided for secondary entities.
      - `tax_information` TransactionEntityTaxInformation
        - `activity_code` string — Code representing the activity of the entity. Validations: - Maximum length: 50
        - `additional_tax_numbers` TransactionEntityTaxNumberCountrySpecific[] — Additional tax numbers used by the entity in domestic or foreign operations Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
          - `business_model` string[] — Applicable transaction business models (optional).
          - `country_code` string — Country where provided tax number should be used.
          - `country_subdivision_code` string — Country subdivision code where tax number should be used (optional).
          - `tax_number` string — Tax number.
          - `type` string — The tax number type (optional).
        - `distribution_address` string — Value to be used by the Tax Authority to forward the reported invoice to the customer/buyer Validations: - Maximum length: 256
        - `regime` string — Tax regime the entity is registered with. e.g., VAT Validations: - Maximum length: 10
        - `tax_code` string — Tax code that complements tax number.
        - `tax_number` string — Tax number of tax registered entity. e.g., 69061864-2-99 Validations: - Maximum length: 50
      - `trade_name` string — The name the company (or the individual) uses to do business. e.g., Acme; John F Kennedy Validations: - Maximum length: 450
      - `type` string, required — Entity type defining the type of the transaction (B2B, B2C, B2G). Validations: - Required property - Values allowed are (ignore case): BUSINESS, INDIVIDUAL, ECONOMIC_OPERATOR
  - `tax_authority_id_1` string — Main transaction identifier returned by or to be provided to the tax authorities. e.g., JIR in Croatia. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `tax_authority_id_2` string — Secondary transaction identifier returned by or to be provided to the tax authorities. e.g., ZKI in Croatia. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `tax_reason` TransactionTaxReason
    - `code` string, required — The specific code to be used as the tax reason for the transaction. e.g., S01 - indicating no tax effect in Mexican jurisdiction Validations: - Maximum length: 15 - Required property
    - `description` string — Further explanation of the tax reason for the code provided Validations: - Maximum length: 450
    - `tax_reason_details` TransactionTaxReasonDetail[] — Additional details to be provided for the tax reason code. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
      - `code` string — Additional code that complements the tax reason code. For example, specific refusal code for refusal tax reason. Validations: - Maximum length: 30
      - `note` string — Further explanation of the tax reason detail for the code provided Validations: - Maximum length: 450
  - `total_amount` number — A high precision decimal representing the total amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals. - Please provide either all amounts (totals and line item's) or only the items unit price. - Line item values and total amounts must add up.
  - `total_net_amount` number — A high precision decimal representing the total net amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
  - `total_tax_amount` number — A high precision decimal representing the total tax amount. If you are using the legacy integer representation for this field refer to this documentation on how to migrate to decimals: https://docs.fonoa.com/reference/amounts-and-rounding Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
  - `total_tax_amounts` TransactionTotalTaxAmount[] — A list of total tax amounts broken down by tax regime. Each entry represents the total for a specific tax regime (e.g., ISH, VAT). The property applies only for Mexico Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
    - `amount` number — The total tax amount for this regime. Validations: - Cannot exceed the maximum allowed precision of 9 decimals.
    - `regime` string, required — Name of the tax regime. e.g., VAT, ISH Validations: - Required property - Maximum length: 10
  - `transaction_channel` string — The channel through which the transaction was conducted, such as in-person, online, telephone order, etc. The property applies only for Brazil Validations: - Values allowed are (letter case matters): IN_PERSON_AT_ESTABLISHMENT, ONLINE, TELEPHONE, IN_PERSON_OUTSIDE_ESTABLISHMENT, OTHER, NOT_APPLICABLE - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `transaction_date` string, required — RFC3339 datetime string representing the point in time when transaction is executed. Validations: - Required property - Must be an RFC3339 format date
  - `transaction_id` string, required — Unique external transaction identifier provided by the customer. Used as idempotency key. e.g., MY_EXTERNAL_IDENTIFIER_0001. Validations: - Maximum length: 150 - Required property
  - `transaction_number` string, required — Unique and usually sequential identifier of a transaction displayed on the document and reported to tax authorities. e.g., invoice number for debit scenario or credit note number for credit scenario. e.g., IE00000001 Validations: - Maximum length: 50 - Is required when Fonoa is not managing transaction numbers. - Must be empty when Fonoa is managing transaction numbers.
  - `transaction_scenario` string — The scenario type for a corrective invoice. Describes the type of correction being applied to the original transaction. The property applies only for France Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
  - `transport_data` TransactionTransportData
    - `recipient` TransactionNonOnboardedEntity
      - `address` TransactionEntityAddress
        - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
        - `address_line_2` string — Validations: - Length between 0 and 450
        - `canton` string — Validations: - Length between 0 and 100
        - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
        - `city_code` string — Validations: - Length between 0 and 20
        - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
        - `district` string — Validations: - Length between 0 and 100
        - `neighbourhood` string — Validations: - Length between 0 and 100
        - `number` string — Validations: - Length between 0 and 20
        - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
        - `prefix` string — Validations: - Length between 0 and 20
        - `province` string — Validations: - Length between 0 and 100
        - `region` string — Validations: - Length between 0 and 100
        - `state` string — Validations: - Length between 0 and 100
        - `suffix` string — Validations: - Length between 0 and 20
      - `contact_details` TransactionEntityContactDetails
        - `email` string, required — Value to be used by the Tax Authority to forward messages to the customer. Validations: - Required property - Must be a valid email address.
        - `phone_number` string — The customer's phone number.
      - `entity_number` string — This is a company registration number if entity is a business or personal identifier if entity is an individual. e.g., 011589551 Validations: - Maximum length: 50
      - `entity_number_type` string — This is company or individual number type. e.g., 93 (Argentina - birth certificate) Validations: - Maximum length: 50
      - `legal_name` string, required — Full legal name of the company (or the individual). e.g., Acme LLC; John Fitzgerald Kennedy Validations: - Required property - Maximum length: 450
      - `role` string, required — Role of the entity in the transaction (e.g., RECIPIENT). Used to distinguish different types of secondary entities. Validations: - Must be provided for secondary entities.
      - `tax_information` TransactionEntityTaxInformation
        - `activity_code` string — Code representing the activity of the entity. Validations: - Maximum length: 50
        - `additional_tax_numbers` TransactionEntityTaxNumberCountrySpecific[] — Additional tax numbers used by the entity in domestic or foreign operations Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
          - `business_model` string[] — Applicable transaction business models (optional).
          - `country_code` string — Country where provided tax number should be used.
          - `country_subdivision_code` string — Country subdivision code where tax number should be used (optional).
          - `tax_number` string — Tax number.
          - `type` string — The tax number type (optional).
        - `distribution_address` string — Value to be used by the Tax Authority to forward the reported invoice to the customer/buyer Validations: - Maximum length: 256
        - `regime` string — Tax regime the entity is registered with. e.g., VAT Validations: - Maximum length: 10
        - `tax_code` string — Tax code that complements tax number.
        - `tax_number` string — Tax number of tax registered entity. e.g., 69061864-2-99 Validations: - Maximum length: 50
      - `trade_name` string — The name the company (or the individual) uses to do business. e.g., Acme; John F Kennedy Validations: - Maximum length: 450
      - `type` string, required — Entity type defining the type of the transaction (B2B, B2C, B2G). Validations: - Required property - Values allowed are (ignore case): BUSINESS, INDIVIDUAL, ECONOMIC_OPERATOR
    - `shipping_from` TransactionEntityAddress
      - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
      - `address_line_2` string — Validations: - Length between 0 and 450
      - `canton` string — Validations: - Length between 0 and 100
      - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
      - `city_code` string — Validations: - Length between 0 and 20
      - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
      - `district` string — Validations: - Length between 0 and 100
      - `neighbourhood` string — Validations: - Length between 0 and 100
      - `number` string — Validations: - Length between 0 and 20
      - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
      - `prefix` string — Validations: - Length between 0 and 20
      - `province` string — Validations: - Length between 0 and 100
      - `region` string — Validations: - Length between 0 and 100
      - `state` string — Validations: - Length between 0 and 100
      - `suffix` string — Validations: - Length between 0 and 20
    - `shipping_to` TransactionEntityAddress
      - `address_line_1` string — Street name and number of the company. Validations: - Length between 0 and 450
      - `address_line_2` string — Validations: - Length between 0 and 450
      - `canton` string — Validations: - Length between 0 and 100
      - `city` string — The city where the legal entity that is being onboarded is registered. Validations: - Length between 0 and 100
      - `city_code` string — Validations: - Length between 0 and 20
      - `country_code` string, required — ISO 3166-1 alpha-2 uppercase country code of the country where entity is registered. Validations: - Required property - Country code must be uppercase ISO 3166-1 alpha-2.
      - `district` string — Validations: - Length between 0 and 100
      - `neighbourhood` string — Validations: - Length between 0 and 100
      - `number` string — Validations: - Length between 0 and 20
      - `postal_code` string — Postal code of the city where the company is registered. Validations: - Length between 0 and 100
      - `prefix` string — Validations: - Length between 0 and 20
      - `province` string — Validations: - Length between 0 and 100
      - `region` string — Validations: - Length between 0 and 100
      - `state` string — Validations: - Length between 0 and 100
      - `suffix` string — Validations: - Length between 0 and 20
    - `transport_mode` string — Defines how the transport was managed. Validations: - Values allowed are (letter case matters): WITHOUT_CHARGE, HIRED_BY_SENDER, HIRED_BY_RECIPIENT, HIRED_BY_THIRD_PARTY, OWNED_BY_SENDER, OWNED_BY_RECIPIENT
  - `type` string — Type of the transaction that usually depends on transaction value and business model (B2B or B2C). The most common types are FULL, SIMPLIFIED, RECEIPT, RECEIPT_INVOICE. Validations: - Values allowed are (letter case matters): FULL, SIMPLIFIED, RECEIPT, RECEIPT_INVOICE, BILLING_STATEMENT, DRAFT_INVOICE

## Response `202`

Accepted - transaction was successfully submitted for processing.

- OperationResultResponse
  - `errors` TransactionErrorResponse[] — List of errors in case the request was unsuccessful.
    - `code` string — Error code of the issue. e.g., field_not_valid
    - `doc_link` string — The link for the error documentation. Follow it to gather more details about the error
    - `field` string — Field from the input request that caused the error, in case of validation errors. e.g. transaction_date
    - `message` string — Error message of the issue. e.g., Date must be in RFC3339 format.
    - `type` string — Error type of the issue. e.g., warning, validation, general, tax_authority
  - `message` string — Information about the failure reason in case the request was unsuccessful.
  - `operation_id` string — Auto-generated unique identifier of a transaction operation returned upon async operation request.
  - `transaction_id` string — The unique external transaction identifier provided with the initial request.

## Other responses

- `400` — Bad customer request - some of the provided information is incorrect or mandatory data is missing. Check the message and errors section of the response for more details.
- `401` — Authentication failed - missing or incorrect subscription key
- `429` — Too many requests were sent for a short period of time. Try again a bit later.
- `5XX` — Internal server error. Its not you, its us! We are experiencing a rare and unexpected system disruption. Retry again later. The message field of the response will contain more information for the cause. Feel free to contact us.

---

[API](https://skmtc.net/fonoa/apis/fonoa-api.md) · [All operations](https://skmtc.net/fonoa/apis/fonoa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fonoa/fonoa-api/versions/cf0ebc843a3f/schema)