Function: GetExtendedPayeeDetails

The GetExtendedPayeeDetails function returns extended information for a specific payee.

This API call requires you to enter a payee ID (idap). You can find the payee ID on the payee's record in the Tipalti Hub or you can get a list of all payee IDs by using the CreatePayeeStatusFile API.

EAT Encryption Additional Terms parameter: None
API version: V5

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 /v5/payeefunctions.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>

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<idap>string</idap>

</GetExtendedPayeeDetails>

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

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</Properties>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

</GetExtendedPayeeDetailsResult>

</GetExtendedPayeeDetailsResponse>

</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
idap	Unique payee identifier (the payee ID)	Max. length = 64 Valid characters: Numbers Letters Commas Periods Underscores Dashes No spaces allowed	Mandatory	string

Response parameters

The result of the GetExtendedPayeeDetails function is provided in the "s" parameter.

Element	Description	Data Type
GetExtendedPayeeDetailsResult	Contains the response parameters	TipaltiExtendedPayeeDetailsResponse (extension of type TipaltiResponse)

TipaltiExtendedPayeeDetailsResponse

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
Properties	List of payee values (see List of payee fields below)		Array of KeyValuePair
CustomFields	If custom fields have been defined for the payee entity, these fields return the values. The field name matches the defined custom field display name.	Field name and value	Array of KeyValuePair

KeyValuePair

Element	description	Mandatory?	data type
Key	Name of field	Optional	string
Value	Value of field	Optional	string

List of payee fields

field	description	limitation	data type
FirstName	Payee first name	Max. length = 70 Valid characters: Latin and numeric (cannot be only numeric) Spaces, periods, dashes (cannot be the first character)—e.g., "Mary Jo", "Jr.", "Mary-Jo"	string
MiddleName	Payee middle name	Max. length = 70 Valid characters: Latin and numeric (cannot be only numeric) Spaces, periods, dashes (cannot be the first character)—e.g., "Mary Jo", "Jr.", "Mary-Jo"	string
LastName	Payee last name	Max. length = 70 Valid characters: Latin and numeric (cannot be only numeric) Spaces, periods, dashes (cannot be the first character)—e.g., "Mary Jo", "Jr.", "Mary-Jo"	string
CompanyName	Payee company name	Max. length = 70 Valid characters: Latin and numeric (cannot be only numeric) Spaces, periods, dashes (cannot be the first character)—e.g., "Company 24", "Company Inc.", "12-up"	string
Alias	An alternate name for the payee, if applicable	Max. length = 250	string
Street1	Payee street address line 1	Max. length = 35 Valid EBCDIC values: Letters, numbers and special characters ^[\w\d\/\-\?\:\.\,\'\+ ]+$"	string
Street2	Payee street address line 2	Max. length = 35 Valid EBCDIC values: Letters, numbers and special characters ^[\w\d\/\-\?\:\.\,\'\+ ]+$"	string
City	Payee city	Max. length = 30 Valid EBCDIC values: Letters, numbers and special characters ^[\w\d\/\-\?\:\.\,\'\+ ]+$"	string
State	Payee state/ province	For payees in the US, Canada, or Mexico Value can be null, 2 letters, or 3 letters (per ISO 3166)	string
Zip	Payee zip/ postal code	No spaces (e.g., N1W 8H5 is N1W8H5)	string
Country	Payee country	Length = 2 (per ISO 3166)	string
Phone	Payee phone number	Max. length = 50	string
PaymentCurrency	The payment currency selected by the payee	Length = 3 (per ISO 4217)	string
Payable	Indicates if the payee is payable		boolean
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)	string
TaxFormEntityType	Represents the type of payee entity selected on tax forms	See Tax form & entity types.	string
TaxFormEntityName	Name of entity entered on the W-9, W-8BEN or W-8BEN-E tax forms		string
TaxFormType	Type of tax form submitted by payee	See Tax form & entity types.	string
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 is not returned at all.	string
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.)	string
TaxFormSubmittedBy	Indicates if the tax form was submitted to Tipalti by the payee or the payer	Valid values: THE_PAYEE THE_PAYER	string
TaxFormSubmittedDate	The date the tax form was signed		string
TreatyCountry	The treaty country entered on the payee tax form		string
WithholdingRate	The withholding rate percentage Sent when the Tax Withholding module is enabled and the payee's payments are subject to withholding		string
PaymentMethod	Payee payment method	Valid values: NoPM PayPal WireTransfer Payoneer ACH Check Global ACH/Local bank transfer HoldMyPayments Custom Intercash	string
Email	Payee email address	Max. length = 200 Valid email format (e.g., [email protected])	string
POTransmissionEmail	When configured, the email address of the payment order recipient	Max. length = 200 Valid email format (e.g., [email protected])	string
ServiceTypes	When configured, the service type codes selected by the payee		string
ServiceTypeOther	When configured, if the payee selects "Other" for the service type, the value entered is shown.		string
PreferredPayerEntity	The payer entity linked to the payee	Valid values: "Entity name" - Max. length = 100; alphanumeric characters only Default	string
PortalUser	Represents the Supplier Hub status of the payee	Valid values: Invited Registered NotRegistered	string
Status	Payee risk status	Valid values: ACTIVE CLOSED SUSPENDED BLOCKED	string
StatusReason	The reason the payee was blocked		string
StatusUpdateDate	The date the payee status was updated		date
CountryName	The name of the payee country (as used in the Tipalti Hub and iFrame)		string
PaymentTermsId	The ID associated with the payment term	Max. length = 40	string
PaymentTermsName	The name of the payment term	Max. length = 20	string
ErpCurrency	The payer's QuickBooks Online vendor currency	Length = 3 (per ISO 4217)	string
PayeeType	The type of payee: Individual Company	Valid values: Individual Company	string