Onboard payee

Payee onboarding involves the following workflows:

1. Create a new payee

  • In Sandbox, create a test payee. A payee can either be "Payable" or "Not Payable". It should be "Payable" in order to start paying this payee via Tipalti. We recommend "Check" as a Payment method for testing purposes. If collecting tax forms, you can mark the payee as "Tax forms collected manually" to make the payee Payable. Or, you can enter tax form info if comfortable.

  • We recommend creating multiple payee profiles in different tax statuses using a test email ID and using different sample combinations based on your payee database. Different country/ Tax combos, W-9, W-8.

  • PayPal validation is not supported on SB.

  • Sample Bank Info for ACH Automated Clearing House/ Wire for SB testing:

    United States (Sample Info to be used for testing)

    • Wells Fargo

    • 333 Market St

    • San Francisco, CA 94105

    • ABA: 121000248

    • SWIFT: WFBIUS6SXXX

    • Account Number: 123456789 Account

    • Type: Checking.

    Sample UK Bank Details

    • Payment method: eCheck

    • Currency: GBP

    • Account Number: 31926819

    • Sort Code: 601613

    • Bank Name: Barclays

    • Account Type: Checking

    • IBAN: GB13 BUKB 6016 1331 9268 19

    • SWIFT: BARCGB22

    • Country: United Kingdom

    • Address: 1 CHURCHILL PLACE

    • Postal Code: E14 5HP.

  • A payee can be created in Tipalti via iFrame, API, CSV Upload, or Manual Data entry. This document focuses on iFrame and API payee creation methods.

    • Before going live on Production, we recommend creating yourself as a payee using a different/ personal email ID and paying yourself no more than $5 via the ACH payment method as the transaction fees are the lowest. This will help you experience the end-to-end workflow.

    IPN - payee_details_changed

    • This IPN notifies of details changed for a payee and is triggered on every iFrame step where the payee details are updated.

    API - UpdateOrCreatePayeeInfo

    • The UpdateOrCreatePayeeInfo function updates the payee's basic information. If the payee does not exist in the system, then the payee will be created. The payee values that you input must match the details in the payee's bank records.

    • If the payer has a restriction for changing the name on the account in the iFrame, and the payee or company name (associated with the account) or address is changed via this API call, the payment method in the iFrame is invalidated. The payee is notified and when they next log into the iFrame, the details on the "Payment Method" page must be completed again.

  • A payee can be created in Tipalti via iFrame, API, CSV Upload, or Manual Data entry. This document focuses on iFrame and API payee creation methods. Before going live on Production, we recommend creating yourself as a payee using a different/personal email ID and paying yourself no more than $5 via the ACH payment method as the transaction fees are the lowest. This will help you experience the end-to-end workflow.

2. Tax Status on a payee profile

  • Tax Status - Tax forms in Tipalti are assigned progressive statuses for transparency in tracking. Statuses display in the Tipalti Hub and returned in APIs and IPNs An Instant Payment Notification (IPN) is a messaging service that enables you to receive notifications from Tipalti. IPNs are triggered when defined events occur (e.g., updating payee details)..

  • Tax status cannot be tested on SB in an automated way. The testing workflow needs Tipalti's intervention to change the Tax Form status. If you wish to test the IPNs or APIs for pulling tax status on your website during SB testing please contact your implementation manager. It is recommended to add payees in different statuses for testing purposes.

  • If you wish to invalidate a tax form, for testing purposes, please reach out to your Implementation Manager.

  • Tax form expiry cannot be tested.

    If collecting W8, go through the Documents module (accept/ reject) for testing/ training. W8 types vary based on Payee's country.

    IPN - payee_details_changed

    • Look for "tax_form_status" field in this IPN.

    • This IPN sends a notification when:

      • Payee uploads document in the iFrame

      • Payer reviews and approves the payee's uploaded document .

      • The payer rejects the payee's uploaded document.

      • Tax form expires or is invalidated

      • Change in tax form status after TIN validation result is processed

    API

    • GetExtendedPayeeDetailsList (for multiple Payees) - This API returns extended details for multiple payees.

      • This API call requires you to enter multiple payee IDs (Idaps).

    • GetExtendedPayeeDetails (for ONE Payee) - This API returns extended information for a specific payee.

      • Look for the field "TaxFormStatus" in this API call.

  • TIN Taxpayer Identification Number Validation for W9 - TIN validation happens in the Production environment only. Tipalti will run this validation on business days at approx around 7:00 AM Pacific. During this check, the payee status remains "Payable". If the workflow is sensitive to tax status, we recommend waiting for the status to change to "TIN Validated" or "Failed TIN Validation".

  • If collecting W8 for international Payees, the Documents module will help you verify the additional documents submitted by the payee.

  • If TIN validation fails - The payee status is "Not Payable".

  • If Document validation is pending, payee status remains "Not Payable" until you review and accept the W8 documents via the Documents module.

3. Update the payee information
4. Routine payee status check

On a routine basis, if you wish to track status changes on the payee profile, we recommend using two APIs. You can create a test payee profile in Sandbox and run the API every time you make updates to the payee profile. If your workflow is sensitive to payee status updates, you can run this API at a fixed interval.