Function: UpdateOrCreatePayeeInfo

The UpdateOrCreatePayeeInfo function updates the payee's basic information. If the payee does not exist in the system, then the payee will be created. The payee values that you input must match the details in the payee's bank records.

If the payer has a restriction for changing the name on the account in the iFrame, and the payee or company name (associated with the account) or address are changed via this API call, the payment method in the iFrame is invalidated. The payee is notified and when they next log into the iFrame, the details on the "Payment Method" page must be completed again.

To set OverridePayableCountry to false via API, the payee has to have a selected payment method.

EAT Encryption Additional Terms parameter: street1
API version: V6

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

<idap>string</idap>

<timestamp>double</timestamp>

<key>string</key>

<skipNulls>boolean</skipNulls>

<overridePayableCountry>boolean</overridePayableCountry>

<item>

<Idap>string</Idap>

<FirstName>string</FirstName>

<LastName>string</LastName>

<Street1>string</Street1>

<Street2>string</Street2>

<City>string</City>

<State>string</State>

<Zip>string</Zip>

<Country>string</Country>

<Email>string</Email>

<Alias>string</Alias>

<Company>string</Company>

<PreferredPayerEntity>string</PreferredPayerEntity>

<ApAccountNumber>string</ApAccountNumber>

<PayerEntityName>string</PayerEntityName>

<PaymentTermId>string</PaymentTermId>

<CountryName>string</CountryName>

<ErpCurrency>string</ErpCurrency>

<PayeeEntityType>string</PayeeEntityType>

<MiddleName>string</MiddleName>

<ApAccountExternalId>string</ApAccountExternalId>

<SendSupplierPortalInvite>boolean</SendSupplierPortalInvite>

</item>

</UpdateOrCreatePayeeInfo>

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

</UpdateOrCreatePayeeInfoResult>

</UpdateOrCreatePayeeInfoResponse>

</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
idap	Unique payee identifier (the payee ID)	Max. length = 64 Valid characters: Numbers Letters Commas Periods Underscores Dashes No spaces allowed	Mandatory	string
timestamp	Current time (UTC) when the request is sent	Unix time	Mandatory	double
key	Encryption key		Mandatory	string
skipNulls	If skipNulls=TRUE, this service ignores parameters with a null value. If skipNulls=FALSE, the null values overwrite existing values.		Mandatory	boolean
overridePayableCountry	Overrides the payment country of the payee If TRUE, both the payee "Country" and "Payment Country" fields in the iFrame or Supplier Hub are updated with the value entered in the "country" field above		Mandatory	boolean
item	List of payee details		Optional	PayeeDetailsItem

PayeeDetailsItem

Element	Description	limitation	Mandatory?	data type
Idap	Unique payee identifier (the payee ID)	Max. length = 64 Valid characters: Numbers Letters Commas Periods Underscores Dashes No spaces allowed	Mandatory	string
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"	Mandatory (without a company name value) Optional (with a company name value)	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"	Mandatory (without a company name value) Optional (with a company name value)	string
Street1	Payee street address line 1	Max. length = 35 Valid EBCDIC values: Letters, numbers and special characters ^[\w\d\/\-\?\:\.\,\'\+ ]+$"	Optional	string
Street2	Payee street address line 2	Max. length = 35 Valid EBCDIC values: Letters, numbers and special characters ^[\w\d\/\-\?\:\.\,\'\+ ]+$"	Optional	string
City	Payee city	Max. length = 30 Valid EBCDIC values: Letters, numbers and special characters ^[\w\d\/\-\?\:\.\,\'\+ ]+$"	Optional	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)	Optional	string
Zip	Payee zip/ postal code	No spaces (e.g., N1W 8H5 is N1W8H5)	Optional	string
Country	Payee country	Length = 2 (per ISO 3166)	Optional	string
Email	Payee email address	Max. length = 200 Valid email format (e.g., [email protected])	Mandatory	string
Alias	An alternate name for the payee, if applicable	Max. length = 250	Optional	string
Company	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"	Mandatory (without payee first and last name values) Optional (with payee first and last name values)	string
PreferredPayerEntity	The payer entity linked to the payee The field name is the "Entity name" defined in Tipalti, or "Default" (to use the payer's default entity).	Max. length = 100 Alphanumeric characters only	Optional	string
ApAccountNumber	The default GL account number (credited with invoice amounts) to link to the payee	Max. length = 450	Mandatory, if multiple AP accounts have been defined in Tipalti	string
PayerEntityName	The payer's default entity	Max. length = 100 Alphanumeric characters only	Optional	string
PaymentTermId	The ID associated with the payment term	Max. length = 40	Optional	string
CountryName	The name of the payee country (as used in the Tipalti Hub and iFrame)		Optional	string
ErpCurrency	The payer's QuickBooks Online vendor currency	Once a value is set, it cannot be changed. Length = 3 (per ISO 4217)	Mandatory, if the payee is the payer's QuickBooks Online vendor.	string
PayeeEntityType	The type of payee: Individual Company	Valid values: Individual Company	Optional	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"	Optional	string
ApAccountExternalId	An ID that uniquely identifies the GL account (e.g., in NetSuite, it is the "Internal ID")	Max. length = 100	Mandatory	string
SendSupplierPortalInvite	Indicates whether to send the payee an invite to register in the Supplier Hub (only sent if the payee has never received an invitation)	Valid values: TRUE FALSE (default)	Optional	boolean

Response parameters

The result of the UpdateOrCreatePayeeInfo is provided in the "b" parameter.

element	description	data type
UpdateOrCreatePayeeInfoResult	Contains the response parameters	TipaltiResponse

TipaltiResponse

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