Function: ProcessPayments

The ProcessPayments function processes payments from a list of payment orders. A payment group A group of payment orders/ instructions that the payer submits to Tipalti to execute payments to payees is created, the payments are added to it and then submitted. The payment list cannot be more than 250 items long.

Tipalti uses the payment refcode to safeguard against duplicate payments. If you try to submit the same payment again using a different refcode in case of an error, it may result in duplicate payments going out to the payee. Please ensure your code handles this error situation correctly.

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

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

<payerName>string</payerName>

<paymentGroupTitle>string</paymentGroupTitle>

<tipaltiPaymentsOrders>

<TipaltiPaymentOrderItem>

<Idap>string</Idap>

<Amount>double</Amount>

<RefCode>string</RefCode>

<EWalletMessage>string</EWalletMessage>

<IgnoreThresholds>boolean</IgnoreThresholds>

<BankingMessage>string</BankingMessage>

<EmailMessage>string</EmailMessage>

<Currency>string</Currency>

<ScheduledDate>dateTime</ScheduledDate>

<IsScheduledVisible>boolean</IsScheduledVisible>

<IgnoreRiskCases>boolean</IgnoreRiskCases>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IgnoreTaxValidation>boolean</IgnoreTaxValidation>

<MaxWithholding>boolean</MaxWithholding>

<IncomeType>string</IncomeType>

<TreatyLimitExceeded>boolean</TreatyLimitExceeded>

<AdditionalWithholding>double</AdditionalWithholding>

<UsSource>double</UsSource>

</TipaltiPaymentOrderItem>

<TipaltiPaymentOrderItem>

<Idap>string</Idap>

<Amount>double</Amount>

<RefCode>string</RefCode>

<EWalletMessage>string</EWalletMessage>

<IgnoreThresholds>boolean</IgnoreThresholds>

<BankingMessage>string</BankingMessage>

<EmailMessage>string</EmailMessage>

<Currency>string</Currency>

<ScheduledDate>dateTime</ScheduledDate>

<IsScheduledVisible>boolean</IsScheduledVisible>

<IgnoreRiskCases>boolean</IgnoreRiskCases>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

<IgnoreTaxValidation>boolean</IgnoreTaxValidation>

<MaxWithholding>boolean</MaxWithholding>

<IncomeType>string</IncomeType>

<TreatyLimitExceeded>boolean</TreatyLimitExceeded>

<AdditionalWithholding>double</AdditionalWithholding>

<UsSource>double</UsSource>

</TipaltiPaymentOrderItem>

</tipaltiPaymentsOrders>

<timeStamp>double</timeStamp>

<key>string</key>

</ProcessPayments>

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

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

<ProcessPaymentsResult>

<errorMessage>string</errorMessage>

<errorCode>integer</errorCode>

<linesResults>

<ExpandedLineResult>

<status>string</status>

<paymentOrderStatus>string</paymentOrderStatus>

<message>string</message>

<refCode>string</refCode>

<lineErrorOrWarningType>integer</lineErrorOrWarningType>

</ExpandedLineResult>

<ExpandedLineResult>

<status>string</status>

<paymentOrderStatus>string</paymentOrderStatus>

<message>string</message>

<refCode>string</refCode>

<lineErrorOrWarningType>integer</lineErrorOrWarningType>

</ExpandedLineResult>

</linesResults>

<summary>

<TipaltiProcessPaymentsSummary>

<accountType>integer</accountType>

<accountCurrency>string</accountCurrency>

<fundsRequired>double</fundsRequired>

<outstandingAmount>double</outstandingAmount>

<tipaltiSummaryAmounts>

<TipaltiSummaryAmounts>

<summaryRowCurrency>string</summaryRowCurrency>

<totalAmount>double</totalAmount>

<immediateAmount>double</immediateAmount>

<payableAmount>double</payableAmount>

<payerFees>double</payerFees>

<scheduledAmount>double</scheduledAmount>

<outstandingAmount>double</outstandingAmount>

<withholdingAmount>double</withholdingAmount>

<estimatedProviderFees>double</estimatedProviderFees>

</TipaltiSummaryAmounts>

</tipaltiSummaryAmounts>

</TipaltiProcessPaymentsSummary>

<TipaltiProcessPaymentsSummary>

<accountType>integer</accountType>

<accountCurrency>string</accountCurrency>

<fundsRequired>double</fundsRequired>

<outstandingAmount>double</outstandingAmount>

<tipaltiSummaryAmounts>

<TipaltiSummaryAmounts>

<summaryRowCurrency>string</summaryRowCurrency>

<totalAmount>double</totalAmount>

<immediateAmount>double</immediateAmount>

<payableAmount>double</payableAmount>

<payerFees>double</payerFees>

<scheduledAmount>double</scheduledAmount>

<outstandingAmount>double</outstandingAmount>

<withholdingAmount>double</withholdingAmount>

<estimatedProviderFees>double</estimatedProviderFees>

</TipaltiSummaryAmounts>

</tipaltiSummaryAmounts>

</TipaltiProcessPaymentsSummary>

</summary>

</ProcessPaymentsResult>

</ProcessPaymentsResponse>

</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
paymentGroupTitle Title of payment group   Optional string
tipaltiPaymentsOrders
  • List of payment items
  • Each payment item is of type TipaltiPayment
    OrderItem
   Mandatory Array of TipaltiPayment
OrderItem
timeStamp

Current time (UTC) when the request is sent

 Unix time Mandatory double
key Encryption key   Mandatory string

TipaltiPaymentOrderItem

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
Amount The amount to be paid to the payee
  • Do not enter the currency symbol or thousand separators.
  • Allowed characters are digits and an optional decimal point for cents (only the first 2 digits after the decimal point are taken into account).
  • Default = USD
 Mandatory double
RefCode The reference code for the payment order
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 Mandatory string
EWalletMessage
  • A message to attach to the payment
  • This message is sent to providers and appears on payee financial statements.
  • Max. length = 160
  • Default = null
 Optional string
IgnoreThresholds If TRUE, the system ignores payment thresholds and executes the payment   Mandatory boolean
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
Optional string
EmailMessage
  • When the payer is using its own physical PayPal account, this message is sent to PayPal and used as the email subject line for payment-related emails that PayPal sends to payees.
  • If a value is provided, it overrides the email subject line defined in the "Payment - Paid" email template.
  • If a value is not provided, the EWalletMessage is used.
  • Max. length = 255
  • Default = null
 Optional string
Currency The currency of the amount submitted
  • Length = 3 (per ISO 4217)
  • Default = Null = USD
 Optional string
ScheduledDate The date and time the payment is scheduled to be paid
  • YYYY-MM-DDThh:mm:ss, where T indicates the start of the time section
  • Default = null
 Optional dateTime
IsScheduledVisible Indicates if the payment and scheduled date are to be visible to the payee in the iFrame Default = null Optional boolean
IgnoreRiskCases

If TRUE, the system ignores a payee's risk case and executes the payment

 Default = FALSE Optional boolean
CustomFields
  • If custom fields have been defined for the payment entity, the values of these fields can be set here.
  • The field name must match the defined custom field name.
  • Default = null
  • Max. length = 140 for "free text" entries
 Optional Array of KeyValuePair
IgnoreTaxValidation If TIN (Tax identification number) validation is enabled and this field is set to "TRUE", the result of the TIN validation is ignored. Default = null Optional boolean
MaxWithholding
  • If the Tax Withholding module is enabled and the payee is unpayable due to an incomplete tax form, this value can be set to "TRUE" to make the payee payable.
  • If TRUE, the maximum withholding percentage is applied (24% for W-9s and 30% for W-8s)
 Default = null Optional 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
 Mandatory, if more than one income type is enabled string
TreatyLimitExceeded Indicates that you are aware the country yearly limit has passed for payees who have not signed the Certificate of No U.S. Activities Default = FALSE Optional boolean
AdditionalWithholding The additional percentage to be withheld from payments
  • Only numbers 0-100, and a decimal point are allowed
  • Percent sign is allowed
 Optional double
UsSource The percentage of the payment that is US sourced (if value ≠ null)
  • Default = null (=100% US sourced)
  • Only numbers 0-100, and a decimal point followed by 2 digits are allowed
  • Percent sign is forbidden
 Optional double
KeyValuePair

Element

description

Mandatory?

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

Response parameters

element

description

data type
ProcessPaymentsResult Contains the response parameters TipaltiExpandedProcess
PaymentResponse

TipaltiExpandedProcessPaymentResponse

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. integer
linesResults
  • List of line errors or warnings
  • Each line error or warning is of type ExpandedLineResult.
   Array of ExpandedLineResult
summary Summary of the payment instructions   Array of TipaltiProcessPaymentsSummary
ExpandedLineResult

element

Description

Limitation

Data Type
status TipaltiLineResultStatus

Valid values:

  • OK
  • Warning
  • Error
string
paymentOrderStatus The status of the payment order See Statuses. string
message The payer's EWalletMessage that was attached to the payment
  • Max. length = 160
  • Default = null
 string
refCode The reference code for the payment order
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string
lineErrorOrWarningType* Type of line error or warning   integer
* See Payment Error Codes.
TipaltiProcessPaymentsSummary

element

description

limitation

data type
accountType Type of account

0 = No account*

2 = PayPal

3 = Payoneer

6 = Intercash

7 = Tipalti

9 = Wells Fargo Bank N.A.

10 = Earthport

999 = External

integer

accountCurrency Currency of the account Length = 3 (per ISO 4217) string
fundsRequired
  • Required funds for the payment instructions
  • Related to the accountType and summaryRowCurrency
   double
outstandingAmount Total amount due   double
tipaltiSummaryAmounts
  • List of payment summary amounts
  • Each payment summary is of type TipaltiSummaryAmounts.
   Array of TipaltiSummary
Amounts
* For payment instructions that refer to payees without a payment method configured
TipaltiSummaryAmounts

element

description

limitation

data type
summaryRowCurrency Currency of the amounts in the TipaltiProcessPaymentsSummary record Length = 3 (per ISO 4217) string
totalAmount
  • Total amount submitted in the payment instructions
  • Related to the accountType and summaryRowCurrency
   double
immediateAmount
  • Amount for immediate payment in the payment instructions
  • Related to the accountType and summaryRowCurrency
   double
payableAmount
  • Amount that is payable in the payment instructions
  • Related to the accountType and summaryRowCurrency
   double
payerFees
  • The fee amount that the payer paid to Tipalti
  • Related to the accountType and summaryRowCurrency
   double
scheduledAmount
  • Amount for scheduled payments in the payment instructions
  • Related to the accountType and summaryRowCurrency
   double
outstandingAmount Total amount due   double
withholdingAmount
  • The amount withheld from the payment (in the payment currency)
  • Sent when the Tax Withholding module is enabled
   double
estimatedProviderFees
  • Additional fees that may be required by the provider
  • Related to the accountType and summaryRowCurrency
   double