CSV

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

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

[
  {
    "origin_identifier": "35087345",
    "amount": "20.56",
    "payment_date": "2025-03-31",
    "transaction_type": "reversal",
    "reversal_code": "0654"
  }
]

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:

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

[
  {
    "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
  }
]

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`.

Product

Networking

Webhooks

Imports

Integrations

Structure of the CSV file

Processing

Data types

Headers

Debtor

Language code

Name and address fields

Invoice-specific contact person

Payments

Invoice lines

Changelog

​Structure of the CSV file

​Processing

​Data types

​Headers

​Debtor

​Language code

​Name and address fields

​Invoice-specific contact person

​Payments

​Invoice lines

​Changelog

Structure of the CSV file

Processing

Data types

Headers

Debtor

Language code

Name and address fields

Invoice-specific contact person

Payments

Invoice lines

Changelog