Articles in this section

Use Tipalti iFrame URLs

When payees onboard themselves in Tipalti, it is usually done via the supplier’s portal. The portal contains the setup process, invoice history, and payment history for that individual payee. In order to automate this process within your own proprietary software, each of these modules must be initialized in your HTML front end using a separate iFrame container. 

Payee iFrame:

  • Setup Process (main iFrame)
      • Sandbox: https://ui2.sandbox.tipalti.com/payeedashboard/home?[parameters here]
      • Production: https://ui2.tipalti.com/payeedashboard/home?[parameters here]
  • Invoice History (optional iFrame)
      • Sandbox: https://ui2.sandbox.tipalti.com/PayeeDashboard/Invoices
      • Production: https://ui2.tipalti.com/PayeeDashboard/Invoices
  • Payment History (optional iFrame)
    • Sandbox: https://ui2.sandbox.tipalti.com/PayeeDashboard/PaymentsHistory
    • Production: https://ui2.tipalti.com/PayeeDashboard/PaymentsHistory

iFrame Authentication

iFrame URL:

Tipalti provides an inline iFrame element that loads the HTML page of our supplier’s portal securely within another document. 

iFrame example call:

<iframe src="​https://ui2.sandbox.tipalti.com/payeedashboard/home?idap=baseTest&payer=Payername&ts=1486771548&hashkey=1385b2e31f9f6011f34d3473a0b44b803d0b134653303ccf19f1df42a3cc7f96">

</iframe>​

 

How to set up the iFrame element:

The iFrame element consists of four parts. The colors below match their equivalent components in the overall iFrame HTML call in your HTML document (Please refer to the example above) :

  1. The iFrame element
  2. The Tipalti payee dashboard URL which will serve as the endpoint the iFrame call is sourcing the data from
  3. The Tipalti parameters being passed via the initial iFrame call
  4. The Encryption key needed for authentication

iFrame call client-side (You the payer) behavior:

Tipalti encrypts the string containing the parameters with the HMAC-SHA256 algorithm. Prepare all your parameters like the following examples and use your Tipalti API master key to encrypt them using HMAC-SHA256:

  • idap=​baseTest&payer=​Payername&ts=1486771548 (with base parameters)
  • idap=​baseTest&payer=​Payername&ts=1486771548&country=USA&zip=94044&alias=JohnDoe&ETC (encrypt all the parameters you’d like the supplier’s portal to be prepopulated with)

The basic steps to the HMAC algorithm are as follows:

The final encryption key should look like the following (below is a sample):

  • 1385b2e31f9f6011f34d3473a0b44b803d0b134653303ccf19f1df42a3cc7f96

iFrame call server-side (Tipalti) behavior: 

Once the iFrame URL is called, Tipalti performs the following steps to authenticate the string:

  1. Checks that the time passed from the "ts" parameter has not exceeded one minute. If it has, the iFrame displays an appropriate error message (see the example below for the code used).
  2. If the call is within the allowed time interval, the Tipalti application will encrypt the parameters using the same method outlined in the iFrame call client-side behavior section
  3. If strings are identical, Tipalti returns the iFrame content with the relevant data of the payer (whose name was retrieved from the query string).
  4. If strings are not identical, the iFrame displays an appropriate error message.

Python iFrame Hash Key Example: 

defHashkey():

msgiframe = 'idap=' + idap + '&payer=' + payer +'&ts=' + str(ts) 

secretkey =   'BUQ9pBJOxfdaQcv++3pUqe5yY8GOnJPp/oDpLn1lGjH22MFoHGu70U/PXtp4QYkK'

hashkey = hmac.new(bytes(secretkey, 'latin-1'), msg=bytes(msgiframe,'latin-1' ) , digestmod=hashlib.sha256).hexdigest()

return hashkey

 

Link to our Python iFrame SDK:

iFrame error codes

ERROR CODE

STATUS

DESCRIPTION

1

NoIdapInRequest

No payee ID is included in the request. This parameter is mandatory.

2

UnknownPayerInRequest

The payer's name is unknown in Tipalti. Ensure the payer's name is entered correctly. If the error is still returned, submit a ticket to our Support Team.

5

MissingRequestParams

Mandatory request parameters are missing.

6

QueryStringEncryptionError

There is an encryption error in the query string (see Encrypt query strings).

8

PayeeCountryNotSupported

The payee country in the request is not supported (e.g., a blocked Office of Foreign Assets Control [OFAC] country). A different country must be used.

10

UnknownPayeeInRequest

Tipalti does not recognize the payee ID in the request; therefore, the system assumes this is a new payee and creates a new record.

12

InvalidIdap
  • Payee ID is invalid.
  • ID max. length = 64; valid characters: numbers, letters, commas, spaces (not leading or trailing), periods, underscores, and dashes

13

InvalidToken

The token for the request is not valid. Please submit a ticket to our Support Team.

14

IllegalPayerUserAccess

You do not have access to the payee's iFrame or Supplier Hub account (e.g., if the payee is not managed by the payer and you do not have the Payee Payment Details Administrator role, you cannot access the payee's account). Please see User Roles for a complete list of roles and permissions.

15

IllegalPayeeName
  • Payee name contains illegal characters or is an invalid length; length = 2 to 35 characters each (for first and last name)
  • Valid values:
    • Letters
    • Spaces, periods, dashes (cannot be the first character); e.g., "Mary Jo", "Jr.", "Mary-Jo"

16

UnknownPayerEntity

The payer entity name is not recognized. Ensure the payer entity has been defined in Tipalti.

17

InvalidErpCurrency

The ERP currency in the request is not valid.

18

ErpCurrencyMismatch

The ERP currency does not match the currency in the request.

19

PayeeCountryOfBirthNotSupported

The payee's country of birth is not supported (e.g., a blocked OFAC country).

20

PayeeDateOfBirthIsNotSupported

The payee's date of birth is not supported.

21

NoPaymentMethodAvailable

The payment method was not added to the request.

99

UnknownError

An unknown error has occurred. Please submit a ticket to our Support Team