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 must have a selected payment method.

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

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

<payerName>string</payerName>

<idap>string</idap>

<timestamp>double</timestamp>

<key>string</key>

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

<company>string</company>

<alias>string</alias>

<skipNulls>boolean</skipNulls>

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

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

<UpdateOrCreatePayeeInfoResult>

<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
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 Mandatory 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
alias An alternate name for the payee, if applicable Max. length = 250 Optional string
skipNulls
  • If skipNulls=TRUE, this service ignores parameters with a null value.
  • If skipNulls=FALSE, the null values overwrite existing values.
   Mandatory boolean
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