Function: GetExtendedPODetails

The GetExtendedPODetails function returns extended information for a specific payment order A single payment instruction for a payee. The system searches for the payment order by RefCode.

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>

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

<payerName>string</payerName>

<timestamp>double</timestamp>

<key>string</key>

<poRefCode>string</poRefCode>

</GetExtendedPODetails>

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

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

<GetExtendedPODetailsResult>

<errorMessage>string</errorMessage>

<errorCode>string</errorCode>

<b>boolean</b>

<i>integer</i>

<d>double</d>

<s>string</s>

<Properties>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</Properties>

<CustomFields>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

<KeyValuePair>

<Key>string</Key>

<Value>string</Value>

</KeyValuePair>

</CustomFields>

</GetExtendedPODetailsResult>

</GetExtendedPODetailsResponse>

</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
poRefCode The reference code for the payment order
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 Mandatory string

Response parameters

element

description

data type
GetExtendedPODetailsResult Contains the response parameters TipaltiExtendedPaymentOrderResponse (extension of type TipaltiResponse)

TipaltiExtendedPaymentOrderResponse

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
Properties List of payment order values (see List of payment order fields below)   Array of KeyValuePair
CustomFields
  • If custom fields have been defined for the payment entity, the field name is the display name and the value is what was defined on the payment order.
  • The field name matches the defined custom field display name.
 Field name and value Array of KeyValuePair
KeyValuePair

Element

description

Mandatory?

data type
Key Name of field Optional string
Value Value of field Optional string
List of payment order fields

field

description

Limitation

data type
Idap Unique payee identifier (the payee ID)
  • Max. length = 64
  • Valid characters:
    • Numbers
    • Letters
    • Commas
    • Periods
    • Underscores
    • Dashes
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
SubmissionDate The date and time the payment was submitted to Tipalti MMM DD, YYYY hh:mm:ss.sss dateTime
AmountSubmitted The amount submitted for payment   double
AmountSubmittedCurrency The currency of the amount submitted Length = 3 (per ISO 4217) string
PaymentMethod Payee payment method

Valid values:

  • NoPM
  • PayPal
  • WireTransfer
  • Payoneer
  • ACH
  • Check
  • Global ACH/Local bank transfer
  • HoldMyPayments
  • Custom
  • Intercash
string
Status The status of the payment order See Statuses. string
PayerFees
  • The fee amount that the payer paid to Tipalti
  • Displays in the payer account currency
   double
PayeeFees
  • The part of the Tipalti transaction fee (which is based on the payer agreement with Tipalti) that is incurred by the payee
  • The fee is based on the payee selected payment method and is deducted from the amount paid to the payee.
  • Displays in the payer account currency
   double
SubmittedCurrencyTo
PayeeCurrencyFxRate
  • The foreign exchange rate for conversion of submitted currency to payee selected currency
  • If both currencies are the same, the value is 1.
    
PayerFXFees The foreign exchange fee for conversion of submitted currency to payer account currency   double
WithdrawCurrency The currency of the payer account used for the payment Length = 3 (per ISO 4217) string
WithdrawAmount The total amount deducted, by Tipalti, from the payer account   double
NetAmount Sum of all bill lines

  • Default = 0

  • Valid characters: digits and an optional decimal point for cents

 double
ValueDate Estimated date and time the payee will receive the funds MMM DD, YYYY hh:mm:ss.sss dateTime
Message The payer's EWalletMessage that was attached to the payment
  • Max. length = 160
  • Default = null
 string
BankingMessage The payer's banking message that was attached to the payment
  • Max. length = 160
  • Default = null
  • Supported for:
    • ACH
    • Check
    • Global ACH/Local bank transfer
    • Wire transfer
string
EmailSubject The payer's EmailMessage that was attached to the payment
  • Max. length = 255
  • Default = null
 string
TxnReference Payment provider's transaction reference code Max. length = 450 string
PaymentAmount Amount paid to the payee (in the payment currency)   double
PaymentCurrency The payment currency selected by the payee Length = 3 (per ISO 4217) string
ErrorMessages If the payment has errors, a list of these errors is returned. See Payment error codes. Array of string
ScheduledDate If the payment is a scheduled payment, this field returns the scheduled date and time. MMM DD, YYYY hh:mm:ss.sss dateTime
EstimatedProviderFees Additional fees that may be required by the provider   double
LiftingFees Fee charged by the bank on a returned payment   double
WithholdingAmount
  • The amount withheld from the payment (in the payment currency)
  • Sent when the Tax Withholding module is enabled and the payment is subject to withholding
   double
WithholdingAmountUSD
  • The amount withheld from the payment, in USD
  • Sent when the Tax Withholding module is enabled and the payment is subject to withholding
   double
WithholdingRate
  • The withholding rate percentage
  • Sent when the Tax Withholding module is enabled and the payment is subject to withholding
   string
TreatyCountry
  • The treaty country entered on the payee tax form
  • Sent when the Tax Withholding module is enabled
   string
IncomeTypeCode
  • The income code associated with the income type
  • Sent when the Tax Withholding module is enabled
 See Income types. string
IncomeType
  • The income type applied to the payment
  • Sent when the Tax Withholding module is enabled
  • See Income types.
  • Default = null
 string
InvoiceRefCode The reference code for the invoice
  • ASCII: max. length = 16 (Account Direction model: max. length = 15)
  • Valid special characters: hyphens, underscores
 string
PayerEntityName The payer entity linked to the payment order
  • Max. length = 100
  • Alphanumeric characters only
 string
AccountIdentifier An identifier for the provider account   string
EarlyPayment Indicates if the payment is an early payment   boolean
PayeeEarlyPaymentFee
  • The payee fee for NetNow
  • Only displays if EarlyPayment = TRUE
   double
PayeeFXFee The foreign exchange fee for conversion of submitted currency to payee selected currency   double
PayerExchangeRate
  • The foreign exchange rate for conversion of submitted currency to payer account currency
  • If both currencies are the same, the value is 1.
   double
PaymentAmountIn
WithdrawCurrency
  • The amount paid to the payee in the payer account currency
  • Includes payee foreign exchange fees
   double
TxnDate The date the payment becomes finalized MMM DD, YYYY hh:mm:ss.sss dateTime
BankAccount (or CreditCard) The ID of the bank account or credit card used to pay the payment order (only relevant for bills paid manually)   string
PayerEntityCountryISO The ISO code for the payer entity country Length = 2 (per ISO 3166) string