Payee Onboarding via iFrame

Use Zipalti iFrame URLs

When payees onboard themselves in Zipalti, 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:

Zipalti 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 Zipalti payee dashboard URL which will serve as the endpoint the iFrame call is sourcing the data from
3. The Zipalti parameters being passed via the initial iFrame call
4. The Encryption key needed for authentication

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

Zipalti encrypts the string containing the parameters with the HMAC-SHA256 algorithm. Prepare all your parameters like the following examples and use your Zipalti 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 "é" then you need to convert the same to  "%C3%A9" 
• Encrypts with HMACSHA256 (uses the master key given to you by Zipalti)
• Converts to hex
  1. Please refer to this documentation for further detail

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

• 1385b2e31f9f6011f34d3473a0b44b803d0b134653303ccf19f1df42a3cc7f96

iFrame call server-side (Zipalti) behavior: 

Once the iFrame URL is called, Zipalti 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 Zipalti application will encrypt the parameters using the same method outlined in the iFrame call client-side behavior section
3. If strings are identical, Zipalti 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:

• https://github.com/pratikkhatwani-tipalti/Zipalti-iFrame

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 Zipalti. 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	Zipalti 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 Zipalti.
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