Function: PayeePayable

The PayeePayable function lets you know if the payee is eligible to receive payments when a payment request is issued (i.e., would the payee be paid?)

The request returns:

  • TRUE, if the payee is payable
  • FALSE, with reason, if the payee is not payable (the "s" parameter will contain the reason—see Validation results)

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

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

<payerName>string</payerName>

<idap>string</idap>

<timestamp>double</timestamp>

<key>string</key>

<amount>double</amount>

</PayeePayable>

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

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

<PayeePayableResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

</PayeePayableResult>

</PayeePayableResponse>

</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
amount The amount to be paid to the payee, in USD
  • 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).
 Mandatory double

Response parameters

The result of the PayeePayable function is provided in the "b" parameter.

Element

Description

Data Type
PayeePayableResult 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

Validation results

The following table lists the possible reasons why the payee is not payable, which are returned in the "s" parameter.

Multiple reasons can be returned.

Reason

description
Address The payee's address is invalid.
Analyzing latest updates Due to updates, the payability status is under calculation and not yet determined.
Certificate of No U.S. Activities has expired The payee's Certificate of No U.S. Activities has expired.
Country is not supported The payment country selected by the payee is not supported.
Currency is not supported The currency selected by the payee is not supported.
Document uploaded by payee, but it hasn't been reviewed yet The payee has uploaded the required document to the iFrame, but it has yet to be reviewed by the payer.
Hold The payee has selected "Hold my payments" in the iFrame.
Last payment failed The payee's last payment transaction failed.
Missing payment method details Details about the payee's payment method are missing (i.e., the payee has not completed these fields in the iFrame).
No documents provided for compliance review The payee has not provided the required documents for compliance review.
No PM The payee has not selected a payment method in the iFrame.
Paid amount not in range The amount to be paid to the payee is not in the required range.
Payee account is closed The payee's account is closed (i.e., not active).
Payee blocked The payee has a status of "Blocked".
Payee currency is not selected The payee has not selected a payment currency in the iFrame.
Payee is blocked by Tipalti The payee was blocked by a Tipalti operator.
Payee record is missing

The payee's review record is missing. For example, if there are existing payees and Tipalti then activates the payee review feature (which screens payees during registration in the iFrame), the existing payees will not have a review status because they have already registered in the iFrame.
Payee record is pending payee update The payer has requested that the payee update the information in the iFrame and the payee has not yet made the updates.
Payee record is pending review The updates the payee made in the iFrame are pending review by the payer.
Payee record was declined The updates the payee made in the iFrame have been declined by the payer.
Payee suspended The payee has a status of "Suspended".
Payer ToS not signed The payer's Terms of Service have not been signed.
Pending Compliance Review The payee is pending compliance review.
Pending tax form approval The payee's tax form is pending approval.
PM is not supported The payee's selected payment method is not supported.
Required documents were not provided The payee has not provided the required documents.
Tax The payee's tax forms have not been received.
Tax form document was uploaded by the payee, but has not been reviewed The required tax form document has been uploaded by the payee, but has not yet been reviewed by the payer.
Tax form documents have not been uploaded by payee The payee has not uploaded the required tax form documents.
Tax number was not entered The payee has not entered a tax number in the iFrame.
Tipalti ToS not signed Tipalti's Terms of Service have not been signed.
Validation for tax form failed Validation of the payee's tax form has failed.
VAT number was not entered The payee has not entered a value-added tax (VAT) number in the iFrame.