Articles in this section

Payee Onboarding (Sandbox)

Payee onboarding involves the following workflows:

Payee_OB_SB_-_1.png

  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,  W9, W8

    • PayPal validation is not supported on SB

    • Sample Bank Info for ACH/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 -

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 theiFrameis 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 

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

    • Note:

        • If collecting W8, go through the Documents module (accept/reject) for testing/training

        • W8 types vary based on Payee's country

  • IPN -

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

       

  2. Update the payee information

    • You can use API to update information on an existing payee profile. If anyone updates the following: email, address, payment method details, Tax form expiry/invalidation, etc. on a payee profile, you can pull this updated information via IPN or API. You can test the IPN and API on Sandbox.

    • There is only one IPN where you will get both Payee Status as well as the Tax status

    • Change in Payee status due to OFAC cannot be tested on Sandbox

  • IPN -  

  • The following trigger event for this IPN can only be tested on Production:

      • A payee risk case is opened

      • OFAC handling when the payee status changes

      • Payee status is updated after a review of the risk case

      • The "last transaction failed" field is updated (Tipalti Hub, payment order error handling, OFAC handling)

 

  1. 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.
  •