Function: CreateOrUpdatePaymentTerms

The CreateOrUpdatePaymentTerms function allows you to create and update payer payment terms.

For a list of payees and their assigned payment terms, see the payees file FTP report.

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

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

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

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<paymentTerms>

<TipaltiPaymentTerm>

<ExternalId>string</ExternalId>

<Name>string</Name>

<Term>integer</Term>

<IsDefault>boolean</IsDefault>

</TipaltiPaymentTerm>

<TipaltiPaymentTerm>

<ExternalId>string</ExternalId>

<Name>string</Name>

<Term>integer</Term>

<IsDefault>boolean</IsDefault>

</TipaltiPaymentTerm>

</paymentTerms>

</CreateOrUpdatePaymentTerms>

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

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

<CreateOrUpdatePaymentTermsResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<CreatedCount>integer</CreatedCount>

<UpdatedCount>integer</UpdatedCount>

<PaymentTerms>

<TipaltiPaymentTerm>

<ExternalId>string</ExternalId>

<Name>string</Name>

<Term>integer</Term>

<IsDefault>boolean</IsDefault>

</TipaltiPaymentTerm>

<TipaltiPaymentTerm>

<ExternalId>string</ExternalId>

<Name>string</Name>

<Term>integer</Term>

<IsDefault>boolean</IsDefault>

</TipaltiPaymentTerm>

</PaymentTerms>

</CreateOrUpdatePaymentTermsResult>

</CreateOrUpdatePaymentTermsResponse>

</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
paymentTerms
  • List of payment terms
  • Each term is of type TipaltiPaymentTerm.
   Mandatory Array of TipaltiPayment
Term

TipaltiPaymentTerm

Element

Description

Limitation

Mandatory?

Data Type
ExternalId The ID of the payment term in your accounting system
  • Max. length = 40
  • Value must be unique
 Mandatory string
Name The display name for the payment term in the Tipalti Hub
  • Max. length = 20
  • Value must be unique
 Mandatory string
Term The value of the payment term
  • Max. length = 8
  • Natural numbers only
 Mandatory integer
IsDefault
  • Indicates if the payment term is the default for the payer
  • When creating or updating terms, if no term in defined as the default, the first term in the list will become the default.

Note: If you change the existing default, all payees linked to this default and all new payees will be assigned to the new default. Existing payees on other payment terms will not be affected.

 Only a single payment term can be the default Optional boolean

Response parameters

element

description

data type
CreateOrUpdatePaymentTermsResult Contains the response parameters CreateOrUpdatePaymentTermsResult (extension of type TipaltiResponse)

CreateOrUpdatePaymentTermsResult

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
CreatedCount The number of new payment terms created   integer
UpdatedCount The number of payment terms updated   integer
PaymentTerms
  • List of payment terms
  • Each term is of type TipaltiPaymentTerm.
   Array of TipaltiPaymentTerm
TipaltiPaymentTerm

Element

Description

Limitation

Data Type
ExternalId The ID of the payment term in your accounting system
  • Max. length = 40
  • Value must be unique
 string
Name The display name for the payment term in the Tipalti Hub
  • Max. length = 20
  • Value must be unique
 string
Term The value of the payment term
  • Max. length = 8
  • Natural numbers only
 integer
IsDefault
  • Indicates if the payment term is the default for the payer
  • When creating or updating terms, if no term in defined as the default, the first term in the list will become the default.

Note: If you change the existing default, all payees linked to this default and all new payees will be assigned to the new default. Existing payees on other payment terms will not be affected.

 Only a single payment term can be the default boolean