> ## Documentation Index > Fetch the complete documentation index at: https://docs.paytsoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # CSV > Information about the outstanding items can be provided in a CSV file. In this chapter you can read how to build the CSV file, how the file is processed. ### Structure of the CSV file * File encoding must be UTF-8. * CSV format specification RFC 4180 ([http://tools.ietf.org/html/rfc4180](http://tools.ietf.org/html/rfc4180)) serves as a guideline. * Separator can be semicolon (;) or comma (,). * (Text) fields must be enclosed in double quotation marks (“). * When using double quotation marks to enclose fields, double quotation marks in a field must be escaped by prefixing it with another double quotation mark. * Field length is max. 255 characters. * The first line is reserved for the column headers. * A number of columns are mandatory, these are indicated in bold. * Unused columns do not need to be included in the CSV file. * The order of columns is not important. ### Processing * The CSV file must present all invoices that must be processed by Payt for sending, reminding, etc. Please note that filtering from the accounting system on only "outstanding items" can sometimes be incomplete. For example, when an invoice is created within 24 hours and immediately matched with a cash payment. At the time of export, this invoice will no longer be in the outstanding items, while Payt may still have to send the invoice. As a guideline, Payt recommends that invoices must appear in the CSV file for a month, to minimize the risk of missing invoices, credit notes or zero invoices. * Payments are calculated and registered based on the outstanding amount of the invoice. * When an invoice has disappeared from the import, Payt marks the invoice as paid. * This means that empty CSV files are interpreted as there are no outstanding invoices. So all invoices are seen as paid. A setting is available in the application that can serve as protection for loading an empty file. ## Data types | Type | Description | Example | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | boolean | "0" or "false" for false and "1" or "true" for true | false | | country\_code | ISO 3166-1 Alpha-2 code | NL | | currency\_code | ISO 4217 three letter code | EUR | | date | yyyy-mm-dd | 2020-12-17 | | integer | Whole number | 7 | | decimal | Maximum two decimal places; point separated | 12345.78 | | email\_address | email address; is validated against a pattern | [info@example.com](mailto:info@example.com) | | gender\_code | "f" or "female" for female and "m" or "male" for male | female | | JSON | Any valid JSON content (make sure the content is properly escaped text content in the CSV, see: [Structure of the CSV file](/imports/csv#structure-of-the-csv-file)) | \{ "key": "value" } | | language\_code | ISO 639-1 two letter language code | nl | | phone\_number | The preferred input is the international version. The number will be validated, which might result in a warning in the interface, but never in an error. Numbers without a country code are assumed to be national phone numbers in the country of the administration. | +31612345678 | | postal\_code | Postal code/zipcode; is required and validated against a pattern for the following countries: NL, BE, DE, FR, LU | 1234AB | | text | Maximum 255 characters | abc def | ## Headers | Name (bold is required) | Description | Data type | | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | **administration\_code** | The unique human readable identifier of the administration. This value must be set in the corresponding administration within Payt. | text | | **debtor\_code** | The unique human readable identifier of the debtor. | text | | debtor\_origin\_id | A unique unchanging identifier of the debtor. \[NB - If not submitted the debtor\_code will be used instead, this means the debtor\_code is allowed to be changed.] | text | | **debtor\_company\_name** | Company name | text | | debtor\_is\_company | Whether the debtor is a company/organization or a private individual | boolean | | debtor\_firstname | First name | text | | debtor\_middlename | Middle name | text | | debtor\_infix | Insertion | text | | debtor\_suffix | Suffix of the debtor name | text | | debtor\_lastname | Last name | text | | debtor\_gender | Gender of the debtor | gender\_code | | debtor\_birth\_date | Birth date of the debtor | date (YYYY-MM-DD) | | debtor\_country\_code | The nationality or country of residence of the debtor. This is not the debtor's postal address country code; use `debtor_post_country_code` for the postal address country. | country\_code | | debtor\_title | Title to address the debtor. Eg: “Dr.”, “Mr.” or “Ms.”. It is recommended to only use this field in exceptional cases, since this field is not translated. If not given a title such as Mrs., Mr. or Mr. / Mrs. is used, depending on the `debtor_gender` field, which is also translated into the language of the debtor. | text | | debtor\_category | The application can be filtered by debtor category. In this way, a distinction can be made between different groups of debtors. The delivered value is considered as one category, multiple categories are not possible. | text (max 50 characters) | | debtor\_coc\_number | Chamber of Commerce number or for Ireland: company number (CRO) or for UK: company registration number (CRN) | text | | debtor\_vat\_number | VAT number | text | | debtor\_oin\_number | Government identification number (for delivering invoice UBLs via the PEPPOL network) | text | | debtor\_peppol\_identifier | PEPPOL identifier for the debtor (for delivering invoice UBLs via the PEPPOL network). Examples: NL:KVK:123456789 or 0106:123456789 | text | | debtor\_gln\_number | Global Location Number (GLN) of the debtor; a 13-digit identifier used in supply chain and e-invoicing (e.g. for PEPPOL) | text | | debtor\_meta\_data | Meta data as key-value pairs that will be rendered in the debtor details column on the debtor page | JSON | | **debtor\_post\_street\_1** | Address line 1 (street and house number) | text | | debtor\_post\_street\_2 | Address line 2 | text | | **debtor\_post\_postalcode** | The postal code of the post address | postal\_code | | **debtor\_post\_city** | The city of the post address | text | | **debtor\_post\_country\_code** | The country code of the post address | country\_code | | debtor\_post\_region | The region code of the post address | text | | debtor\_sms\_number | Number for text reminders | phone\_number | | debtor\_phone\_number | Number for robocalls | phone\_number | | debtor\_email | General email address | email\_address | | debtor\_invoice\_email | Invoice email address | email\_address | | debtor\_invoice\_cc\_email | Invoice cc email address | email\_address | | debtor\_invoice\_bcc\_email | Invoice bcc email address | email\_address | | debtor\_labels | Label names separated by a comma. Will create labels and assign or remove them from debtors when this is enabled for an administration. | text | | debtor\_origin\_url | URI which is used to guide the user from Payt to the URI of the debtor in the origin administration | text | | debtor\_reminder\_email | Reminder email address | email\_address | | debtor\_reminder\_cc\_email | Reminder cc email address | email\_address | | debtor\_reminder\_bcc\_email | Reminder bcc email address | email\_address | | debtor\_language\_code | The language in which to communicate with the debtor | language\_code | | debtor\_payment\_condition | A unique identifier from the source system. The identifiers can be mapped to flows via the interface. | text | | debtor\_relation\_manager | The relation/account manager of the debtor | text | | debtor\_credit\_limit\_amount | The maximum sum of invoice open amount the debtor is allowed to accumulate. When provided the value should be zero or greater than zero. Zero means no open amount is allowed. | decimal | | debtor\_allow\_invoice\_emailing\_override | When a value is provided for this property then it will override the setting as known in Payt. If set to false then no invoices will be sent by email and will therefore fallback to sending invoices by snail mail. | boolean | | debtor\_allow\_reminder\_emailing\_override | When a value is provided for this property then it will override the setting as known in Payt. If set to false then no reminders will be sent by email and will therefore fallback to sending invoices by snail mail. | boolean | | **invoice\_number** | The unique human readable identifier of the invoice. | text | | invoice\_description | Invoice description | text | | **invoice\_date** | The accounting date of the invoice. | date | | **invoice\_due\_date** | The date at which the invoice should be paid. | date | | **invoice\_total\_amount\_inc\_vat** | The full, original amount in the currency of the invoice, including VAT. As it should be paid by the debtor. | decimal | | **invoice\_open\_amount\_inc\_vat** | The current payable amount in the currency of the invoice, including VAT | decimal | | invoice\_currency\_code | Currency of specific invoice. If this column is added, it must be filled. Outstanding amount payments are calculated and registered | currency\_code | | invoice\_book\_amount\_total | The full, original amount in the accounting currency of the administration, including VAT. If this column is added, it must be filled. | decimal | | invoice\_book\_amount\_open | The current payable amount in the accounting currency of the administration, including VAT. If this column is added, it must be filled. | decimal | | administration\_book\_currency\_code | The accounting currency of the administration. This must match the currency as set within Payt. | currency\_code | | invoice\_labels | Label names separated by a comma. Will create labels and assign or remove them from invoices when this is enabled for an administration. | text | | invoice\_last\_payment\_date | The payment date of the most recent payment on the invoice. | date | | invoice\_category | The application can be filtered by invoice category. In this way, a distinction can be made between different categories of invoices. The delivered value is considered as one category. | text (max 50 characters) | | invoice\_order\_number | Order number | text | | invoice\_origin\_id | A unique unchanging database identifier of the invoice. | text | | invoice\_peppol\_identifier | PEPPOL identifier for the invoice (for delivering UBLs via the PEPPOL network). Examples: NL:KVK:123456789 or 0106:123456789 | text | | invoice\_gln\_number | Global Location Number (GLN) for the invoice; a 13-digit identifier used in supply chain and e-invoicing (e.g. for PEPPOL) | text | | invoice\_origin\_url | URI which is used to guide the user from Payt to the URI of the invoice in the origin administration. | text | | invoice\_reference | An additional reference by which the debtor can recognize the invoice. | text | | invoice\_payment\_reference | A custom payment reference which will be used for emails, letters, debtor portal and online payments | text | | invoice\_purchase\_order\_number | Purchase number | text | | invoice\_payment\_condition | A unique identifier from the source system. The identifiers can be mapped to flows via the interface. This value will take precedence over the debtor\_payment\_condition. | text | | invoice\_payment\_method | One of: 'bank\_transfer', 'direct\_debit', 'cash' | text | | invoice\_payment\_term | The number of days within which the invoice must be paid. When not provided it is calculated as the number of days between the invoice\_date and the due\_date. | integer | | invoice\_paused | Whether the invoice should be paused. Invoices paused by this column cannot be unpaused in the app, but only by a new import where this column is set to false | boolean | | invoice\_contact\_origin\_id | A unique unchanging identifier of the contact. \[NB - Mandatory when invoice-specific contact person is present!] | text | | invoice\_contact\_sms\_phone\_number | Number for text reminders of invoice-specific contact person | phone\_number | | invoice\_contact\_call\_phone\_number | Number for robocalls of invoice-specific contact person | phone\_number | | invoice\_contact\_default\_email\_address | General email address of invoice-specific contact person | email\_address | | invoice\_contact\_invoice\_email\_address | Invoice email address of invoice-specific contact person | email\_address | | invoice\_contact\_invoice\_cc\_email\_address | Invoice cc email address of invoice-specific contact person | email\_address | | invoice\_contact\_invoice\_bcc\_email\_address | Invoice bcc email address of invoice-specific contact person | email\_address | | invoice\_contact\_reminder\_email\_address | Reminders email address of invoice-specific contact person | email\_address | | invoice\_contact\_reminder\_cc\_email\_address | Reminders cc email address of invoice-specific contact person | email\_address | | invoice\_contact\_reminder\_bcc\_email\_address | Reminders bcc email address of invoice-specific contact person | email\_address | | invoice\_contact\_gender | Gender of invoice-specific contact person | gender\_code | | invoice\_contact\_firstname | First name of invoice-specific contact person | text | | invoice\_contact\_middlename | Middle name of invoice-specific contact person | text | | invoice\_contact\_infix | Insertion last name of invoice-specific contact person | text | | invoice\_contact\_lastname | Last name of invoice-specific contact person \[NB - first name or last name Mandatory when using invoice-specific contact person!] | text | | invoice\_contact\_post\_street\_1 | Address line 1 of invoice-specific contact person | text | | invoice\_contact\_post\_street\_2 | Address line 2 of invoice-specific contact person | text | | invoice\_contact\_post\_postalcode | Postcode of invoice-specific contact person | postal\_code | | invoice\_contact\_post\_city | Place of invoice-specific contact person | text | | invoice\_contact\_post\_country\_code | Country code of invoice-specific contact person | country\_code | | invoice\_contact\_post\_region | Region of invoice-specific contact person | text | | payments | See [payments](#payments) | JSON | | invoice\_lines | See [invoice\_lines](#invoice-lines) | JSON | ### Debtor The `debtor_*` fields must be delivered consistently for all invoices. E.g. the postal address must be the same for all invoices from the same debtor, as must fields like emails, phone numbers, relation manager, etc. If it is desirable to use a different address for different invoices from one debtor, the `invoice_contact_*` fields can be used. #### Language code The languages Dutch, German, English, French, Spanish, Italian and Polish are supported in the application. When a different language code is supplied, the application falls back to the language set as fallback on the administration. When Dutch is used for Belgian customers, Flemish is used. #### Name and address fields At least one of the fields `debtor_company_name` or `debtor_firstname` / `debtor_lastname` -> (this is merged into debtor\_fullname in the code) must be filled. ### Invoice-specific contact person It is possible to assign an invoice-specific contact person to an invoice. If an invoice has an invoice-specific contact person, the details of the contact person will be used instead of the details of the debtor. Note: If there is an invoice-specific contact person, the fields `invoice_contact_origin_id` and (`invoice_contact_firstname` or `invoice_contact_lastname`) must both be filled. The `invoice_contact_origin_id` field contains the unique source ID of the contact. If `invoice_contact_origin_id` is filled, but the name is missing, the invoice-specific contact person will not be loaded and a validation error will be displayed. Keep in mind that the corresponding invoice and debtor will be loaded in this case. If no specific email address for sending invoices is known for the contact person, the email address for sending invoices of the debtor is used. If this address is also unknown, the general email address of the contact person will be used. Finally, if no general email address of the contact person is known, the general email address of the debtor is used. If no specific email address for sending reminders is known for the contact person, the email address for sending reminders from the debtor is used. If this address is also unknown, the general email address of the contact person will be used. Finally, if no general email address of the contact person is known, the general email address of the debtor is used. ### Payments If no payments are provided Payt will create one based on the difference between total and open amount of the invoice. This payment created by Payt only contains the paid amount and a date, the date of the import. The payments field allows you to take control of the payments that will be created. It also allows you to update existing payments. There are a few things to note when providing the payments: * all payments of the invoice must be provided, also the historical ones. This allows Payt to recognize when payments have been changed or destroyed in the bookkeeping system and apply these changes. * the payments must be ordered chronologically with the oldest first * the sum of the payment amounts must be equal to the difference between the total and open amount of the invoice. | Type | Description | Example | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | **origin\_identifier** | The database identifier of the payment. This identifier must be unique within the administration. | 35087345 | | **payment\_date** | The date at which the payment/transaction took place. | 2025-03-31 | | **amount** | The amount that was paid, in the currency of the invoice. | 20.56 | | book\_amount | The amount that was paid, in the currency of the administration. If not provided this will be calculated using the exchange rate between the total\_amount and book\_total\_amount of the invoice. This property becomes required when `transaction_type` is "revaluation". | 20.56 | | transaction\_type | The type of booking. This indicates whether it was an actual payment or if there was a different reason to change the open amount of the invoice. The values can be one of: "payment", "reversal", "credit", "write\_off", "settlement", "revaluation". Note that for "revaluation" the value of `amount` must be zero and `book_amount` must be non-zero. | reversal | | payment\_method | The method that was used to perform the payment. This is only relevant when the `transaction_type` is "payment". | bank\_transfer | | reversal\_code | The code provided by the bank which indicates the reason why the direct debit transaction was reversed. This is only relevant when the `transaction_type` is "reversal". | 0654 | ```json theme={null} [ { "origin_identifier": "35087345", "amount": "20.56", "payment_date": "2025-03-31", "transaction_type": "reversal", "reversal_code": "0654" } ] ``` ```csv theme={null} invoice_id,payments 12345,"[{""origin_identifier"":""35087345"",""amount"":""20.56"",""payment_date"":""2025-03-31"",""transaction_type"":""reversal"",""reversal_code"":""0654""}]" ``` For invoices with no payments, an empty array should be provided: ```csv theme={null} invoice_id,payments 12345,"[]" ``` ### Invoice lines Invoice lines describe the products and/or services that are being invoiced. Invoice lines are not required for most of the features within Payt. When you want Payt to create the invoice document or UBL then the invoice lines are required. There are a few things to note when providing the invoice\_lines: * the sum of the amounts in the invoice lines must be equal to the total amount of the invoice. * if changes in the invoice\_lines are detected these changes will automatically be applied. Invoice lines no longer present in the set will be removed. * if an empty set of invoice lines is provided then all invoice\_lines will be removed. * once an invoice is published, it is sent to the debtor, it is no longer allowed to change the invoice lines. | Type | Description | Example | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | **description** | Text that describes the product or service that is invoiced. | Office chair - black | | **product\_price** | The price for a single unit of product. | 125.75 | | product\_unit | The unit in which the quantity of the invoiced products are counted. Default value is "piece". | piece | | product\_quantity | The amount of product that is invoiced, in the unit as provided in `product_unit`. Default value is "1". | 24 | | total\_excl\_tax\_amount | The amount invoiced excluding VAT. If this amount is absent it will be calculated from the `total_incl_tax_amount` and `vat_amount`. Either `total_excl_tax_amount`, `total_incl_tax_amount` or both must be provided. | 3018.0 | | total\_incl\_tax\_amount | The amount invoiced including VAT. If this amount is absent it will be calculated from the `total_excl_tax_amount` and `vat_amount`. Either `total_incl_tax_amount`, `total_excl_tax_amount` or both must be provided. | 3651.78 | | **vat\_rate\_code** | The code of the vat rate applied to the invoice line. This vat rate must be present in the administration. | high | | vat\_percentage | The percentage of VAT applied. This percentage must match the percentage that is associated with the vat\_rate\_code. If not supplied the percentage that is associated with the vat\_rate\_code is used. | 21.0 | | vat\_amount | The amount of VAT charged. If not provided it is calculated from the other values. | 633.78 | | line\_order | The position of the invoice\_line within the set of invoice\_lines of the invoice. If the line\_order is not provided then the order in which the lines are provided will be used. If line\_order is provided then each invoice\_line must have a unique integer. | 1 | ```json theme={null} [ { "description": "Office chair - black", "product_price": "125.75", "product_unit": "stuk", "product_quantity": "24", "total_excl_tax_amount": "3018.0", "total_incl_tax_amount": "3651.78", "vat_rate_code": "high", "vat_percentage": "21.0", "vat_amount": "633.78", "line_order": 1 } ] ``` ```csv theme={null} invoice_id,invoice_lines 12345,"[{""description"":""Office chair - black"",""product_price"":""125.75"",""product_quantity"":""24"",""total_excl_tax_amount"":""3018.0"",""vat_rate_code"":""high""}]" ``` ## Changelog | Date | Change | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 2026-06-16 | Added `debtor_country_code` column | | 2026-04-15 | Added documentation of entries in payments column for invoices without any payments | | 2026-03-17 | Added `debtor_gln_number` and `invoice_gln_number` columns | | 2025-12-03 | Added `debtor_peppol_identifier` and `invoice_peppol_identifier` columns | | 2025-10-13 | Updated the allowed values for the `invoice_payment_method` column | | 2025-10-13 | Added `invoice_lines` column | | 2025-03-31 | Added `payments` column | | 2024-10-07 | Added `debtor_birth_date` column | | 2024-03-08 | Updated Name and address fields description | | 2023-11-16 | Removed `invoice_administration_costs_paid`, `invoice_collection_costs_paid`, `invoice_interest_paid` fields as these fields are only relevant for custom integrations | | 2023-07-27 | Added `invoice_payment_reference` | | 2022-07-07 | Added `invoice_administration_costs_paid`, `invoice_collection_costs_paid`, `invoice_interest_paid` | | 2022-04-12 | Added `invoice_paused` | | 2022-04-08 | Added `debtor_invoice_cc_email`, `debtor_invoice_bcc_email`, `debtor_reminder_cc_email`, `debtor_reminder_bcc_email`, `invoice_contact_invoice_cc_email_address`, `invoice_contact_invoice_bcc_email_address`, `invoice_contact_reminder_cc_email_address`, `invoice_contact_reminder_bcc_email_address` | | 2022-04-01 | Fixed name and description of `invoice_last_payment_date` | | 2022-04-01 | Added `invoice_contact_post_region`, `invoice_payment_method`, `invoice_payment_term`, `debtor_middlename`, `debtor_suffix`, `invoice_origin_id`, `invoice_reference` | | 2022-04-01 | Added `integer` data type | | 2022-03-14 | Added `debtor_meta_data` and JSON data type | | 2021-08-03 | Added `debtor_origin_url` and `invoice_origin_url` | | 2020-12-17 | Added `debtor_allow_invoice_emailing_override` and `debtor_allow_reminder_emailing_override` | | 2020-12-14 | Added `debtor_post_region` | | 2020-07-29 | Changed URL for submission of files to backend.paytsoftware.com | | 2020-06-15 | Added `debtor_credit_limit_amount` | | 2020-05-20 | Added `debtor_title` | | 2020-05-07 | Added a short text on `language_code`. | | 2020-01-06 | Add that an invoice must appear in a CSV file for a month. | | 2019-11-29 | Added short explanation of status codes and about consistency debtor\_\* fields. | | 2019-11-04 | Added `invoice_description` | | 2019-07-30 | Added explanation for uniqueness of different fields. | | 2019-05-09 | Added explanation about fallback logic for invoice and reminder email addresses. | | 2019-05-02 | Removed upload via web. - FTPS removed. - Organize and rename headers. - Update index | | 2019-03-25 | Added `debtor_oin_number` | | 2019-02-01 | Changed the order of valid CSV Headers. | | 2019-01-10 | Removed text \[still in development] from currency fields. | | 2018-12-06 | Renamed `invoice_book_currency_code` to `administration_book_currency_code` | | 2018-11-27 | “Authentication with HTTP basic authentication (to be phased out)” deleted. - Naming of currency fields changed, added “invoice\_” correct name: - `invoice_currency_code`. - `invoice_book_amount_total` - `invoice_book_amount_open` - `invoice_book_currency_code`. | | 2018-11-06 | Added currency fields to CSV headers table | | 2018-10-08 | Expanded and adjusted general passage about double quotation marks | | 2018-09-13 | `debtor_lastname` not obligatory anymore (is now or firstname/infix/lastname) | | 2018-09-11 | Added `invoice_category` | | 2018-07-26 | Text change for uploading files. | | 2018-05-23 | Added `invoice_order_number` - Removed `debtor_invoice_*` fields (Not recommended for general usage), except `debtor_invoice_email`. | | 2018-05-14 | Added `invoice_contact_*` fields - Minimal TLS 1.2 | | 2017-08-28 | Removed `invoice_flow_code` and `debtor_flow_code` | | 2017-06-20 | Added `debtor_is_company` | | 2017-06-01 | Added information about API token for HTTP upload | | 2017-05-03 | Correction specification `debtor_language_code` to ISO 639-1 | | 2017-03-22 | Added `debtor_coc_number` and `debtor_vat_number` | | 2016-10-20 | Changed FTPS address to ftp-debiteurenbeheer.payt.nl | | 2016-10-04 | Endpoint added for the delivery of invoice attachments via the API | | 2016-03-15 | Version Management Added - Index added - `debtor_origin_flow_code` Renamed to `debtor_payment_condition` - `invoice_origin_flow_code` Renamed to `invoice_payment_condition`. |