Articles in this section

See more

Payment file format

A payment file can be used for executing payments or for performing evaluations. Payment files are typically CSV files that contain one or more payment orders and instructions for Tipalti. They can be uploaded to the Tipalti Hub as a CSV file.

Once uploaded, Tipalti can automatically verify that the file details are prepared correctly and in the correct format, and calculate and display the required amounts. Once the payment file is validated, you can submit it to Tipalti for payment.

For payment method coverage and time zone differences, go to Payment methods coverage.
For scheduling payments, go to Schedule payments via file upload.

Click the image below to download a sample of the CSV file structure. You can clear all data in the file and enter your own data for upload. A maximum of 2 million lines is allowed.

File structure

The following table describes the fields in the payment file. Fields are not case sensitive.

Field

Description

Limitation

Data type
Idap
(Mandatory)		 Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    Numbers
    Letters
    Commas
    Periods
    Underscores
    Dashes
  • No spaces allowed
 string
Amount
(Mandatory)
  • The amount to be paid to the payee

  • This amount is the gross amount due. Tipalti deducts, from this amount, the fees the payee needs to pay per the fee schedule—for example:

    The payer fee schedule states that a payee pays $5 for each paper check.

    The amount due to the payee is $100.

    You must type "100" for the value in the Amount field.

    The payee receives $95.
  • Do not enter the currency symbol or thousand separators.
  • Allowed characters are digits and an optional decimal point for cents (only the first 2 digits after the decimal point are taken into account).
  • Default = USD; if you want to send a different currency, input a SubmittedAmount
    Currency
 double
SubmittedAmount
Currency
(Optional)		 The currency to be used for the payment
  • Length = 3 (per ISO 4217)
  • Default = USD
 string
RefCode
(Mandatory)
  • The reference code for the payment
  • To auto-generate a reference code, leave this field empty.
  • This code is referenced in the payments summary file and Payment details report.
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string
EWalletMessage
(Optional)
  • A message to attach to the payment
  • This message is sent to providers and appears on payee financial statements.
  • Max. length = 160
  • Default = null
 string
BankingMessage
(Optional)
  • A message to attach to the payment
  • This message is sent to providers and appears on payee bank statements.
  • If a value is not provided, the EWalletMessage is used.
  • Max. length = 160
  • Default = null
  • Supported for:
    ACH
    Check
    Global ACH/Local bank transfer
    Wire transfer
 string
IgnoreThresholds
(Optional)		 If TRUE, the system ignores payment thresholds and executes the payment Default = FALSE boolean
EmailMessage
(Optional)
  • When the payer is using its own physical PayPal account, this message is sent to PayPal and used as the email subject line for payment-related emails that PayPal sends to payees.
  • If a value is provided, it overrides the email subject line defined in the "Payment - Paid" email template.
  • If a value is not provided, the EWalletMessage is used.
  • Max. length = 255
  • Default = null
 string
ScheduledDate
(Optional)		 Date the payment is scheduled to be paid MM/DD/YYYY date
scheduleType
(Optional)		 Allow users to specify whether a payment is scheduled based on the payment departure date (submission) or the estimated payment arrival date to the payee (not including holidays).

Supports 2 values
if schedule date is filled:

  • Arrival
  • Departure

Any other input is not supported. 

 string
VisibleWhen
Scheduled
(Optional)		 Indicates if the payment and scheduled date are to be visible to the payee on the iFrame or Supplier Hub   boolean
IncomeType
(Mandatory, if more than one income type is enabled)		 If the Tax Withholding module is enabled and there are multiple income types that can be associated with the payment, then you must enter the income type per payment. string
MaxWithholding
(Optional)
  • If the Tax Withholding module is enabled and the payee is unpayable due to an incomplete tax form, this value can be set to "TRUE" to make the payee payable.
  • If TRUE, the maximum withholding percentage is applied (24% for W-9s and 30% for W-8s)
 Default = null boolean
IgnoreTax
Validation
(Optional)		 If TIN (Tax identification number) validation is enabled and this field is set to "TRUE", the result of the TIN validation is ignored. Default = null boolean
CustomFields
(Optional)
  • If custom fields have been defined for the payment entity, the values of these fields can be set here.
  • The field name must match the defined custom field name.
  • Default = null
  • Max. length = 140 for "free text" entries
 string
Additional
Withholding
(Optional)
  • The additional percentage to be withheld from payments
  • Use only if an additional withholding module, such as State Withholding is supported.

Note: Additional withholding is added to federal withholding.
  • Only numbers and a decimal point are allowed
  • Percent sign is optional.
 double
TreatyLimit
Exceeded
(Optional)		 Indicates that you are aware the country yearly limit has passed for payees who have not signed the Certificate of No U.S. Activities Default = FALSE boolean
UsSource
(Optional)		 The percentage of the payment that is US sourced (if value ≠ null)
  • Default = null =100% US sourced
  • Only numbers 0-100, and a decimal point followed by 2 digits are allowed
  • Percent sign is optional
 decimal
payingEntity
Name
(Optional)

The entity from which the payment will be sent to the payee.

 

 Can be set in case the payer entity and/ or the payee don't have tax configuration enabled. String