Function: GetPayeeInvoicesListDetails

The GetPayeeInvoicesListDetails function returns invoice details for a list of payee invoices.

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>

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

<payerName>​string​</payerName>

<timestamp>​double​</timestamp>

<key>​string​</key>

<invoicesRefCodes>

<string>​string​</string>

<string>​string​</string>

</invoicesRefCodes>

</GetPayeeInvoicesListDetails>

</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>

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

<GetPayeeInvoicesListDetailsResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<InvoiceErrors>

<TipaltiInvoiceItemError>

<ErrorMessage>string​</ErrorMessage>

<ErrorCode>string​</ErrorCode>

<InvoiceRefCode>​string​</InvoiceRefCode>

</TipaltiInvoiceItemError>

<TipaltiInvoiceItemError>

<ErrorMessage>​string</ErrorMessage>

<ErrorCode>​string​</ErrorCode>

<InvoiceRefCode>​string​</InvoiceRefCode>

</TipaltiInvoiceItemError>

</InvoiceErrors>

<Invoices>

<TipaltiInvoiceItem>

<Idap>​string​</Idap>

<InvoiceRefCode>​string​</InvoiceRefCode>

<InvoiceDate>​dateTime​</InvoiceDate>

<InvoiceDueDate>​dateTime​</InvoiceDueDate>

<InvoiceLines>

<InvoiceLine>

<Currency>string</Currency>

<Amount>double</Amount>

<Description>string</Description>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<EWalletMessage>string</EWalletMessage>

<BankingMessage>string</BankingMessage>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

</InvoiceLine>

</InvoiceLines>

<Description>​string​</Description>

<CanApprove>​boolean</CanApprove>

<InvoiceInternalNotes>​string​</InvoiceInternalNotes>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>​boolean​</IsPaidManually>

<IncomeType>​string​</IncomeType>

</TipaltiInvoiceItem>

<TipaltiInvoiceItem>

<Idap>​string​</Idap>

<InvoiceRefCode>​string​</InvoiceRefCode>

<InvoiceDate>​dateTime​</InvoiceDate>

<InvoiceDueDate>​dateTime​</InvoiceDueDate>

<InvoiceLines>

<InvoiceLine>

<Currency>string</Currency>

<Amount>double</Amount>

<Description>string</Description>

<InvoiceInternalNotes>string</InvoiceInternalNotes>

<EWalletMessage>string</EWalletMessage>

<BankingMessage>string</BankingMessage>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

</InvoiceLine>

</InvoiceLines>

<Description>​string​</Description>

<CanApprove>​boolean</CanApprove>

<InvoiceInternalNotes>​string​</InvoiceInternalNotes>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IsPaidManually>​boolean​</IsPaidManually>

<IncomeType>​string​</IncomeType>

</TipaltiInvoiceItem>

</Invoices>

</GetPayeeInvoicesListDetailsResult>

</GetPayeeInvoicesListDetailsResponse>

</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
invoicesRefCodes List of invoice reference codes Max. request limit = 200 refcodes Mandatory Array of string

string

element

description

limitation

data type
string The reference code for the invoice
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string

Response parameters

element

description

data type
GetPayeeInvoicesList
DetailsResult		 Contains the response parameters TipaltiGetPayeeInvoicesList
DetailsResponse (extension of type TipaltiResponse)

TipaltiGetPayeeInvoicesListDetailsResponse

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. string
b If the return code is Boolean, this parameter will carry the value.   boolean
i If the return code is integer, this parameter will carry the value.   integer
d If the return code is double, this parameter will carry the value.   double
s If the return code is string, this parameter will carry the value.   string
InvoiceErrors
  • Array of invoice item errors
  • Each invoice item error is of type TipaltiInvoiceItemError.
  Array of TipaltiInvoiceItemError
Invoices
  • Array of invoice items
  • Each invoice item is of type TipaltiInvoiceItem.
Max. records returned = 200 Array of TipaltiInvoiceItem
TipaltiInvoiceItemError

The error 1011 "InvoiceRefCodeUnknown" is returned by the GetPayeeInvoicesListDetails Endpoint for any invoices that currently don't have any bill lines created for them (e.g., an invoice created in the Tipalti Hub before it was saved by the user)

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. string
InvoiceRefCode The reference code for the invoice
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string
TipaltiInvoiceItem

Element

Description

Limitation

Data Type
Idap Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
  • No spaces allowed
 string
InvoiceRefCode The reference code for the invoice
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string
InvoiceDate Invoice value date (estimated date and time the payee receives the funds) YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section dateTime
InvoiceDueDate The date and time the invoice is due to be paid YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section dateTime
InvoiceLines
  • List of invoice lines
  • Each invoice line is of type InvoiceLine.
   Array of InvoiceLine
Description A description of the invoice Max. length = 256 string
CanApprove Indicates whether or not the payee is able to approve the invoice   boolean
InvoiceInternalNotes Notes that are not displayed to the payee
  • Max. length = 256
  • Default = null
 string
CustomFields If custom fields have been defined for the bill/ invoice entity, the field name is the display name and the value is what was defined on the bill.
  • Default = null
  • Max. length = 140 for "free text" entries
 Array of KeyValuePair
IsPaidManually If TRUE, the invoice is marked as paid manually   boolean
IncomeType 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.
  • See Income types.
  • Default = null
 string
InvoiceLine

element

description

limitation

data type
Currency The currency of the invoice Length = 3 (per ISO 4217) string
Amount Invoice line amount   double
Description Description of the invoice line Max. length = 256 string
InvoiceInternalNotes Notes that are not displayed to the payee
  • Max. length = 256
  • Default = null
 string
EWalletMessage
  • A message to attach to the payment
  • This message is sent to providers and appears on payee bank statements.
  • If no value is provided, the InvoiceRefCode is used.
  • Max. length = 160
  • Default = null
 string
BankingMessage
  • 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
CustomFields

If custom fields have been defined for the bill/ invoice line entity, the field name is the display name and the value is what was defined on the bill line.
  • Default = null
  • Max. length = 140 for "free text" entries
 Array of KeyValue
Pair
KeyValuePair

Element

description

data type
Key Name of field string
Value Value of field string