Set up payee onboarding via iFrame (New)

Required user role Technical admin

New payee onboarding experience

Tipalti is rolling out a simplified new payee onboarding interface. Only the base URL changes — you use the new iFrame URL exactly as you do today, with the same parameters and the same hashkey signature. You can choose to switch to the new experience on your own schedule.

You can preview the new experience in Sandbox before going live in Production. Sandbox testing requires an existing Sandbox account; if you don't have one, contact your Tipalti representative.

What stays the same

• Nothing changes in the information you collect from your payees.
• The way you work with the iFrame is unchanged — same embed, same parameters, same hashkey signature. Only the base URL is new.

What's changing

• A cleaner, more intuitive flow with clear guidance at every step.
• A new setup overview greets payees when they log in, featuring a “Payability” indicator that clearly shows their status and what's left before they can start receiving payments.
• An updated base URL that your platform calls behind the scenes to load the payee iFrame.

Using Tipalti iFrame URLs

The Tipalti iFrame contains the Payment details (setup process), Invoice history, and Payment history for individual payees. To automate this within your own platform, initialize each of these modules in your HTML front end using a separate iFrame container.

Payment details iFrame (main setup process)

• Sandbox: https://payee-onboarding-app.sandbox.tipalti.com?[your existing parameters]
• Production: https://payee-onboarding-app.tipalti.com?[your existing parameters]

The optional Invoice history and Payment history iFrames remain on the existing domains — only the Payment details tab is moving to a new URL.

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

Allowlist the new hostnames

Before you switch, check whether anything on your side restricts embedded content — for example a Content-Security-Policy (CSP), firewall, or proxy. This applies whether you switch the URL yourself or ask Tipalti to enable it for you.

• If you allowlisted a wildcard (for example https://*.tipalti.com), no action is needed — the new hostnames are already covered.

• If you allowlisted the specific hostname (ui2.tipalti.com), add the new hostname the same way, or the frame will be blocked:

  Content-Security-Policy: frame-src https://payee-onboarding-app.tipalti.com;
  (add https://payee-onboarding-app.sandbox.tipalti.com too if you test in Sandbox)

iFrame authentication

iFrame URL

Tipalti provides an inline iFrame element that securely loads the HTML page of our payee experience within another document.

iFrame example call:

<iframe src="https://payee-onboarding-app.sandbox.tipalti.com?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 iFrame 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

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

iFrame error codes