FTP update reports

You may define an SFTP Secure File Transfer Protocol (SFTP) is a secure version of File Transfer Protocol (FTP), which facilitates data access and data transfer over a Secure Shell (SSH) data stream. folder to receive daily updates (CSV files) on payees, payments, and payer fees from Tipalti. All files are PGP-encrypted and signed. PGP keys are exchanged in advance between Tipalti and the payer. To enable integration, please submit a request to our Support Team and provide the following information.

  • Host name and port number
  • Input folder
  • Output folder
  • Depending on your mode of authentication:
    • Username/ Password
    • Username/ Key file (OpenSSH)
  • PGP public key (encryption key): This key is used by Tipalti to encrypt the files. Use your private key to decrypt the files.

You may specify any interval of time for these reports and when to start the interval.

Select a report below to view descriptions and limitations for each field in the report:

The payees file provides a record of each updated and/ or created payee in Tipalti.

File name: PayeeDetails_PayerName_yyMMdd_hh.csv

Field

Description

Limitation
Idap Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
  • No spaces allowed
FirstName Payee first name
  • Length = 2 to 35 characters
  • Valid characters:
    • Letters
    • Spaces, periods, dashes (cannot be the first character)—e.g., "Mary Jo", "Jr.", "Mary-Jo"
MiddleName Payee middle name
  • Length = 2 to 35 characters
  • Valid characters:
    • Letters
    • Spaces, periods, dashes (cannot be the first character)—e.g., "Mary Jo", "Jr.", "Mary-Jo"
LastName Payee last name
  • Length = 2 to 35 characters
  • Valid characters:
    • Letters
    • Spaces, periods, dashes (cannot be the first character)—e.g., "Mary Jo", "Jr.", "Mary-Jo"
CompanyName Payee company name
  • Max. length = 35
  • Valid characters:
    • Letters
    • Symbols, numbers (only if accompanied by letters)—e.g., "Company 24", "Company Inc.", "12up"
Alias An alternate name for the payee, if applicable Max. length = 250
Street1 Payee street address line 1 Max. length = 35
Street2 Payee street address line 2 Max. length = 35
City Payee city Max. length = 30
State Payee state/ province
  • For payees in the US, Canada, or Mexico
  • Value can be null, 2 letters, or 3 letters (per ISO 3166)
Zip Payee zip/ postal code No spaces (e.g., N1W 8H5 is N1W8H5)
Country Payee country Length = 2 (per ISO 3166)
PaymentCountry The country in which the payee receives payment Length = 2 (per ISO 3166)
Phone Payee phone number Max. length = 50
PaymentCurrency The payment currency selected by the payee Length = 3 (per ISO 4217)
Payable Indicates if the payee is payable  
TaxFormStatus The status of the payee's submitted tax form (only relevant if the payer has requested tax forms)

Valid values:

  • NOT_SUBMITTED
  • SUBMITTED
  • SUBMITTED ([PENDING_DOCUMENTS or PENDING_DOCUMENTS_APPROVAL] and/ or [FAILED_TIN_VALIDATION or PENDING_TIN_VALIDATION or TIN_VALIDATED])
  • PENDING_REVIEW
  • PENDING_REVIEW (PENDING_DOCUMENTS or PENDING_DOCUMENTS_APPROVAL)
TaxFormEntityType Represents the type of payee entity selected on tax forms See Tax form & entity types.
TaxFormEntityName Name of entity entered on the W-9, W-8BEN or W-8BEN-E tax forms  
TaxFormType Type of tax form submitted by payee See Tax form & entity types.
TaxID Payee tax identification number (masked by asterisks unless you have the View Secure Details user role)
  • W-9: Returns EIN or SSN (if EIN empty), or TIN
  • W-8BEN, W-8BEN-E: Returns EIN or SSN or FOREIGN_TIN (if TIN empty) or VAT_ID (if collected)
  • LOCAL_TAX_ID: Returns the Tax ID Type (depends on entity's country and relevant tax ID types for the country)
  • If none of the values are available, the old "Tax ID" field (from the iFrame "Payment Method" tab, if applicable) is returned.
  • If there is no value for the old "Tax ID" field, it returns empty.
TaxIDType Type of Tax ID

Valid values:

  • EIN
  • SSN
  • TIN
  • FOREIGN_TIN
  • VAT_ID
  • Local tax ID types (CUIT, CUIL, CPF, CNPJ, ID, INN, etc.)
PaymentMethod Payee payment method

Valid values:

  • NoPM
  • PayPal
  • WireTransfer
  • Payoneer
  • ACH
  • Check
  • Global ACH/Local bank transfer
  • HoldMyPayments
  • Custom
  • Intercash
Email Payee email address
ServiceTypes When configured, the service type codes selected by the payee  
ServiceTypeOther When configured, if the payee selects "Other" for the service type, the value entered is shown.  
POTransmissionEmail When configured, the email address of the payment order recipient
Status Payee risk status

Valid values:

  • ACTIVE
  • CLOSED
  • SUSPENDED
  • BLOCKED
ReviewerStatus When the payee makes changes to account information in the iFrame or Supplier Hub, the changes need to be approved by the payer. This field indicates the status of the review. Valid values:
  • PENDING_REVIEW
  • APPROVED
  • DECLINED
  • UPDATE_REQUIRED
PreferredEntity The payer entity linked to the payee Only displays if the payer has more than one entity
PaymentTermsID The ID associated with the payment term Max. length = 40
PaymentTermsName The name of the payment term Max. length = 20
PAYMENT DETAILS
PaymentMethodToken Unique token for the payment method details (payee's payment routing details joined as one string) Supported for:
  • ACH
  • Check
  • Global ACH/Local bank transfer
  • eWallet
  • Wire transfer
BankBeneficiaryName Name of the beneficiary who holds the bank account
  • Max. length = 128
  • Supported for:
    • ACH
    • Global ACH/Local bank transfer
    • Wire transfer
BeneficaryNameIn
LocalLanguage		 The beneficiary name in the local language  
AccountNumber Bank account number Supported for:
  • ACH
  • Global ACH/Local bank transfer
  • Wire transfer
Iban International bank account number
  • Max. length = 450
  • Supported for:
    • Global ACH/Local bank transfer
    • Wire transfer
Swift A unique identification code for financial institutions
  • Max. length = 128
  • Supported for:
    • Global ACH/Local bank transfer
    • Wire transfer
IntermediaryBankName Intermediary bank name
  • Max. length = 128
  • Supported for wire transfer
IntermediaryAccount
Number		 Intermediary bank account number
  • Max. length = 128
  • Supported for wire transfer
IntermediarySwift Intermediary bank SWIFT code
  • Max. length = 128
  • Supported for wire transfer
BankCode Bank local code
  • Max. length = 128
  • Supported for:
    • Global ACH/Local bank transfer
    • Wire transfer
BranchCode Bank branch code
  • Max. length = 128
  • Supported for:
    • Global ACH/Local bank transfer
    • Wire transfer
BankName Bank name
  • Max. length = 128
  • Supported for:
    • ACH
    • Global ACH/Local bank transfer
    • Wire transfer
BankBranchName Bank branch name
  • Max. length = 128
  • Supported for wire transfer
RoutingNumber Bank branch routing number
  • Max. length = 128
  • Supported for ACH
BankAddress Bank branch address line 1
  • Max. length = 128
  • Supported for wire transfer
BankAddress2 Bank branch address line 2
  • Max. length = 128
  • Supported for wire transfer
BankCity Bank branch city
  • Max. length = 128
  • Supported for:
    • Global ACH/Local bank transfer
    • Wire transfer
BankZipCode Bank branch zip code
  • Max. length = 128
  • Supported for wire transfer to China only
NameOnCheck The check is written to this payee name. Max. length = 450
CheckAddress The mailing address line 1 for the check Max. length = 128
CheckAddress2 The mailing address line 2 for the check Max. length = 128
CheckCity City where the check is sent Max. length = 128
CheckState State or province where the check is sent
  • For payees in the US, Canada, or Mexico
  • Value can be null, 2 letters, or 3 letters (per ISO 3166)
CheckZipCode Zip code where the check is sent Max. length = 128
ewalletAccount The eWallet account identifier Max. length = 450
BeneficiaryID Identification number of the beneficiary  
AgencyCode The agency code provided when a payment is sent to Brazil  
IFSCCode Indian Financial System Code
  • Alphanumeric
  • Max. length = 11
INNKPP Taxpayer’s identification number and registration code (Russia)  
PhoneNumber Phone number of the beneficiary Max. length = 50
CorrespondentAccount The correspondent account provided when a payment is sent to Russia  
ACHAccountType Type of bank account (e.g., checking, savings)  
RemittanceInformation Additional remittance information for wire transfers  
[Custom field name], [Custom field name]… If custom fields have been defined for the payee entity, the field name is the display name and the value is what was defined on the payee record. Field name and value

The payment file A CSV or TXT file that contains one or more payment orders/ instructions to Tipalti. It can be submitted via the Tipalti Hub or Tipalti's FTP path. provides a record of all payments that have had a status update, including new payment orders that have been created.

File name: PaymentStatus_PayerName_yyMMdd_hh.csv

Field

Description

Limitation
Idap Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
  • No spaces allowed
RefCode The reference code for the payment order
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
RelatedInvoiceRefCode The invoice reference code linked to the payment
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
SubmissionDate The date the payment order was submitted to Tipalti MMM DD, YYYY
AmountSubmitted The amount submitted for payment  
AmountSubmittedCurrency
  • The currency of the amount submitted
  • If no currency has been provided, the payment is assumed to be in the currency of the payer's primary bank account.
 Length = 3 (per ISO 4217)
PaymentMethod Payee payment method

Valid values:

  • NoPM
  • PayPal
  • WireTransfer
  • Payoneer
  • ACH
  • Check
  • Global ACH/Local bank transfer
  • HoldMyPayments
  • Custom
  • Intercash
Status The status of the payment order See Statuses.
PayerFees The fee amount that the payer paid to Tipalti  
PayeeFees
  • The part of the Tipalti transaction fee (which is based on the payer agreement with Tipalti) that is incurred by the payee
  • The fee is based on the payee selected payment method and is deducted from the amount paid to the payee.
  
PayerFXFees The foreign exchange fee for conversion of submitted currency to payer account currency  
EstimatedProviderFees Additional fees that may be required by the provider  
WithdrawCurrency The currency of the payer account used for the payment Length = 3 (per ISO 4217)
WithdrawAmount The total amount deducted, by Tipalti, from the payer account  
ValueDate Estimated date the payee will receive the funds MMM DD, YYYY
WithholdingRate The withholding rate percentage  
WithholdingAmount The amount withheld from the payment, in USD  
IncomeCode The income code associated with the income type See Income types.
IncomeDisplayType The income type applied to the payment
  • See Income types.
  • Default = null
TreatyCountry
  • The treaty country entered on the payee tax form
  • Sent when the Tax Withholding module is enabled
  
TxnReference Payment provider's transaction reference code Max. length = 450
PaymentAmount Amount paid to the payee (in the payment currency)  
PaymentCurrency The payment currency selected by the payee Length = 3 (per ISO 4217)
Provider The provider name

Valid values:

  • None
  • PayPal
  • Payoneer
  • Payer
  • Intercash
  • Tipalti
  • WellsFargo
  • Earthport
  • External
AccountIdentifier An identifier for the provider account  
ErrorMessages If the payment has errors, a list of these errors is returned. See Payment error codes.
ScheduledDate If the payment is a scheduled payment, this field returns the scheduled date. MMM DD, YYYY
Payer Exchange Rate
  • The foreign exchange rate for conversion of submitted currency to payer account currency
  • If both currencies are the same, the value is 1.
  
[Custom field name], [Custom field name]… If custom fields have been defined for the payment entity, the field name is the display name and the value is what was defined on the payment order. Field name and value

The payer fees file provides a record of payment-related fees that Tipalti charges the payer. Fees, such as monthly subscription fees display in each record, whereas fees, such as transaction fees are aggregated per the defined time interval.

File name: PayerFees_PayerName_yyMMdd_hh.csv

Field

Description

Limitation
TipaltiFeeReference Tipalti-generated reference code for payer fees  
FeeCollectionDate The date the fee is collected MMM DD, YYYY
FeeCurrency The currency of the fee Length = 3 (per ISO 4217)
FeeAmount
  • The amount of the fee
  • The value equals the daily sum of transaction fees (both payer and payee transaction fees) + payer FX fees + lifting fees for all finalized payments.
  
FeeDescription A description of the fee collected (e.g., transaction fee, lifting fee, foreign exchange fee, etc.)  
Provider Name of the provider that has paid the fees

Valid values:

  • None
  • PayPal
  • Payoneer
  • Payer
  • Intercash
  • Tipalti
  • WellsFargo
  • Earthport
  • External
AccountIdentifier An identifier for the provider account