Structure of the CSV file
- File encoding must be UTF-8.
- CSV format specification RFC 4180 (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 |
| 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) | { “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 | JSON |
| invoice_lines | See invoice_lines | JSON |
Debtor
Thedebtor_* 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 fieldsdebtor_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 fieldsinvoice_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 |
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 |
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. |