Set up payee onboarding via iFrame

Using Tipalti iFrame URLs

When payees onboard themselves in Tipalti, they usually do it through the supplier's portal. The portal contains the setup process, invoice history, and payment history for that individual payee. To automate this process within your own proprietary software, you need to initialize each of these modules 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 securely loads the HTML page of our supplier's portal 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 (see the example above):

1. The iFrame element
2. The Tipalti payee dashboard URL, which serves as the endpoint the iFrame call sources data from
3. The Tipalti parameters passed via the initial iFrame call
4. The encryption key needed for authentication

iFrame call client-side behavior

Tipalti encrypts the string containing the parameters with the HMAC-SHA256 algorithm. Prepare your parameters as shown in the examples below, then 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:

• Prepare your string with the parameters to be encrypted
• Encode the parameter value to URL-encoded format
  • For example, if your parameter value includes "é," convert it to "%C3%A9"
• Encrypt with HMACSHA256 (uses the master key Tipalti gives you)
• Convert to hex (see this documentation for more detail)

The final encryption key should look like this sample:

1385b2e31f9f6011f34d3473a0b44b803d0b134653303ccf19f1df42a3cc7f96

iFrame call server-side (Tipalti) behavior

Once the iFrame URL is called, Tipalti authenticates the string as follows:

1. Checks that the time elapsed since the "ts" parameter hasn't exceeded one minute. If it has, the iFrame displays an error message (see the error codes below).
2. If the call is within the allowed time interval, the Tipalti application encrypts the parameters using the same method described in iFrame call client-side behavior above.
3. If the strings match, Tipalti returns the iFrame content with the relevant data for the payer (whose name is retrieved from the query string).
4. If the strings don't match, the iFrame displays an error message.

Python iFrame hash key example:

def Hashkey():
    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

Python iFrame SDK: https://github.com/pratikkhatwani-tipalti/Tipalti-iFrame

iFrame error codes