Function: CreatePaymentOrdersReport

The CreatePaymentOrdersReport function creates a CSV file containing details of payment orders submitted between specified start and end dates. The file is placed in Tipalti's 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.

Refer to the resultsFile parameter in the reponse for the report file name. For field descriptions and limitations included in the report, see the file structure following the request and response samples below.

The details of the file may change over time (i.e., columns may be added). When reading the file, ensure you have functionality that can ignore new columns.

The following is a sample SOAP 1.2 request and response. In the request, you need to replace the data types in yellow with actual values.

SOAP 1.2: Request

POST /v2/payerfunctions.asmx HTTP/1.1

Host: api.tipalti.com

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<CreatePaymentOrdersReport xmlns="http://Tipalti.org/">

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<startTime>dateTime</startTime>

<endTime>dateTime</endTime>

</CreatePaymentOrdersReport>

</soap12:Body>

</soap12:Envelope>

SOAP 1.2: Response

HTTP/1.1 200 OK

Content-Type: application/soap+xml; charset=utf-8

Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

<soap12:Body>

<CreatePaymentOrdersReportResponse xmlns="http://Tipalti.org/">

<CreatePaymentOrdersReportResult>

<errorMessage>string</errorMessage>

<errorCode>integer</errorCode>

<resultsFile>string</resultsFile>

</CreatePaymentOrdersReportResult>

</CreatePaymentOrdersReportResponse>

</soap12:Body>

</soap12:Envelope>

Request parameters

element

description

limitation

Mandatory?

data type
payerName The name of the payer, as assigned by Tipalti
  • Max. length = 50
  • Value is case sensitive
 Mandatory string
timestamp

Current time (UTC) when the request is sent

Unix time

 Mandatory double
key Encryption key   Mandatory string
startTime The start date and time of the report YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section Mandatory dateTime
endTime The end date and time of the report YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section Mandatory dateTime

Response parameters

element

description

data type
CreatePaymentOrdersReportResult Contains the response parameters TipaltiReportResponse

TipaltiReportResponse

element

description

limitation

data type
errorMessage A description of the error See API error codes. string
errorCode The status of the error See API error codes. integer
resultsFile The name of the Payment Orders report file Max. length of report name = 260 string

File structure of Payment Orders report

The following table describes the fields in the Payment Orders report.

field

description

limitation
Payee ID Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
  • No spaces allowed
Name Payee first and 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"
Company Payee company name
  • Max. length = 35
  • Valid characters:
    • Letters
    • Symbols, numbers (only if accompanied by letters)—e.g., "Company 24", "Company Inc.", "12up"
Date Remitted The date and time the payment was submitted to Tipalti MM/DD/YYYY hh:mm:ss
Value Date Estimated date and time the payee will receive the funds MM/DD/YYYY hh:mm:ss
Amount Submitted The amount submitted for payment

 
Amount Submitted (USD) The amount submitted for payment, in USD  
Withholding Amount
  • The amount withheld from the payment (in the payment currency)
  • Only applies when the Tax Withholding module is enabled and the payment is subject to withholding
  
Withholding Amount (USD)
  • The amount withheld from the payment, in USD
  • Only applies when the Tax Withholding module is enabled and the payment is subject to withholding
  
Withholding Rate (%)
  • The withholding rate percentage
  • Only applies when the Tax Withholding module is enabled and the payment is subject to withholding
  
Additional Withholding Amount
  • The additional amount withheld from payments
  • Only applies if an additional withholding module, such as State Withholding is supported.
  
Additional Withholding Amount (USD)
  • The additional amount withheld from payments, in USD
  • Only applies if an additional withholding module, such as State Withholding is supported.
  
Additional Withholding Rate (%)
  • The additional percentage withheld from payments
  • Only applies 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.
Payee TXN Fees
  • 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.
  
Amount After TXN Fees
  • The amount after deducting:
    • Payee transaction fee
    • Tax withholding (if applicable)
  • Displays in the amount submitted currency

 
Payee FX Fees The foreign exchange fee for conversion of submitted currency to payee selected currency  
Net to Payee
  • The amount after deducting:
    • Payee transaction fee
    • Tax withholding (if applicable)
    • Payee NetNow fee (if applicable)
  
Net Currency The currency of the "Net to payee" amount

Length = 3 (per ISO 4217)
Payer Offset If the payee transaction fees are higher than the original payment provider fees, the offset shows the difference between the two fees.  
Payer Fees The fee amount that the payer paid to Tipalti  
Estimated Provider Fees Additional fees that may be required by the provider

 
Payment Currency The payment currency selected by the payee

Length = 3 (per ISO 4217)
Payment Amount (target currency) The amount paid to the payee in the currency selected by the payee  
Payment Method Payee payment method

Valid values:

  • NoPM
  • PayPal
  • WireTransfer
  • Payoneer
  • ACH
  • Check
  • Global ACH/Local bank transfer
  • HoldMyPayments
  • Custom
  • Intercash
Payment Method Identifier An identifier for the payment method used  
Bill Refcode The reference code for the bill
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
Invoice Number The number of the invoice  
Bill Amount The original amount of the bill  
Bill Amount per Payment The amount of the bill paid for this payment  
Ref Code The reference code for the payment order
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
Transaction Ref Tipalti internal transaction reference code
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
Payment Status The status of the payment order See Statuses.
Payment Provider Result The payment status returned from the payment provider  
Payment Provider Result Date The date of the "Payment provider result" MM/DD/YYYY
Payment Provider Result Text A description of the "Payment provider result"  
Returned Amount
  • The amount returned by the payment provider
  • Only applies to a submitted payment that is unsuccessful
  
Return Date
  • The date of the returned amount
  • Only applies to a submitted payment that is unsuccessful
 MM/DD/YYYY
Debit Date The date and time when the payer's bank/ payment provider account was debited MM/DD/YYYY hh:mm:ss
Debit Ref Code The debit transaction reference code provided to the payee by the payer's bank/ payment provider Max. length = 450
Last Payee Detail Change The last date and time the payee changed the selected payment method in the iFrame or Supplier Hub MM/DD/YYYY hh:mm:ss
Currently Payable
  • Indicates whether the payee is currently able to receive payments
  • If a payee is unpayable, check the "Alerts" information in the file to see the reason why.
  
eMail Address Avail Indicates if an email address is attached to the payee account  
Tax Treaty Country
  • The treaty country entered on the payee tax form
  • Only applies when the Tax Withholding module is enabled and the payment is subject to withholding
  
Income Type
  • The income type applied to the payment
  • Only applies when the Tax Withholding module is enabled and the payment is subject to withholding
  • See Income types.
  • Default = null
Income Type Code
  • The income code associated with the income type
  • Only applies when the Tax Withholding module is enabled and the payment is subject to withholding
 See Income types.
Alerts Indicates the reason why a payment has been deferred See Payment error codes.
Alias An alternate name for the payee, if applicable Max. length = 250
Scheduled Date If the payment is a scheduled payment, this field returns the scheduled date and time. MM/DD/YYYY hh:mm:ss
Payer FX Fees The foreign exchange fee for conversion of submitted currency to payer account currency  
Submitted Amount Currency The currency of the amount submitted Length = 3 (per ISO 4217)
Withdrawal Amount The total amount deducted, by Tipalti, from the payer account  
Account Currency The currency of the payer account used for the payment Length = 3 (per ISO 4217)
Payment Provider Account The payment provider account number  
TAX Number
  • Payee tax number
  • Only applies when Tax Number is activated
  
VAT Number
  • Value-added tax number
  • Only applies when VAT Collection is activated
  
Provider Account The name of the Tipalti provider account used for the payment  
Entity Name The name of the payer entity linked to the payment order
  • Max. length = 100
  • Alphanumeric characters only
Override Withholding Applied Indicates if the payee withholding rate was overridden by the payer Valid values:
  • TRUE
  • FALSE
Override Withholding Reason The reason why the payee withholding rate was overridden by the payer  
Early Payment Fee The payee fee for NetNow  
Early Payment Auto Pay Indicates if NetNow AutoPay is enabled for the payee

Valid values:

  • TRUE
  • FALSE