Articles in this section

Payee onboarding (Sandbox)

Payee onboarding involves the following workflows:

Payee onboarding workflow diagram

Create a new payee

  • In Sandbox, create a test payee. A payee can be "Payable" or "Not Payable"; it needs to be "Payable" to start paying the payee via Tipalti. We recommend using "Check" as the payment method for testing, since it has the lowest requirements. If you're collecting tax forms, you can mark the payee as "Tax forms collected manually" to make them Payable, or enter tax form info directly if you prefer.
  • We recommend creating multiple payee profiles in different tax statuses, using a test email address and sample combinations based on your payee database (different country/tax combinations, W-9, W-8, and so on).
  • PayPal validation isn't supported in Sandbox.

  • Sample bank info for ACH/wire testing in Sandbox:

    United States United Kingdom
    Wells Fargo
    333 Market St
    San Francisco, CA 94105
    ABA: 121000248
    SWIFT: WFBIUS6SXXX
    Account Number: 123456789
    Account Type: Checking    		 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
  • You can create a payee in Tipalti via iFrame, API, CSV upload, or manual data entry. This document focuses on the iFrame and API creation methods. Before going live in Production, we recommend creating yourself as a payee using a personal email address and paying yourself no more than $5 via ACH (the transaction fees are lowest), so you can experience the end-to-end workflow.
IPN API

payee_details_changed

Notifies you of details changed for a payee. Triggered on every iFrame step where the payee's details are updated.

UpdateOrCreatePayeeInfo

Updates the payee's basic information. If the payee doesn't exist in the system, this call creates them. The values you submit must match the details in the payee's bank records.

If the payer restricts changing the account name in the iFrame, and the payee or company name (or address) associated with the account is changed via this API call, the payment method in the iFrame is invalidated. The payee is notified, and the next time they log in, they must complete the "Payment Method" page again.

Tax status on a payee profile

  • Tax forms in Tipalti are assigned progressive statuses for transparency in tracking. Statuses display in the Tipalti Hub and are returned in APIs and IPNs.
  • Tax status can't be tested in Sandbox in an automated way — the testing workflow needs Tipalti's intervention to change the tax form status. If you want to test IPNs or APIs for pulling tax status during Sandbox testing, contact your implementation manager. We recommend adding payees in different statuses for testing.
  • To invalidate a tax form for testing purposes, reach out to your implementation manager.
  • Tax form expiry can't be tested.

If you're collecting W-8 forms, use the Documents module (accept/reject) for testing and training. W-8 types vary based on the payee's country.

IPN API

payee_details_changed

Look for the "tax_form_status" field in this IPN. It sends a notification when:

  • The payee uploads a document in the iFrame
  • The payer reviews and approves the payee's uploaded document
  • The payer rejects the payee's uploaded document
  • The tax form expires or is invalidated
  • The tax form status changes after a TIN validation result is processed
  • GetExtendedPayeeDetailsList (for multiple payees) — returns extended details for multiple payees. Requires you to enter multiple payee IDs (Idaps).
  • GetExtendedPayeeDetails (for one payee) — returns extended information for a specific payee.
  • Look for the "TaxFormStatus" field in this API call.
  • TIN validation for W-9 forms happens in the Production environment only. Tipalti runs this validation on business days at approximately 7:00 AM Pacific. During this check, the payee status remains "Payable." If your workflow is sensitive to tax status, we recommend waiting for the status to change to "TIN Validated" or "Failed TIN Validation."
  • If you're collecting W-8 forms for international payees, the Documents module helps you verify the additional documents the payee submits.
  • If TIN validation fails, the payee status becomes "Not Payable."
  • If document validation is pending, the payee status remains "Not Payable" until you review and accept the W-8 documents via the Documents module.

Update the payee information

  • You can use the API to update information on an existing payee profile. If anyone updates the payee's email, address, payment method details, tax form expiry, or invalidation, you can pull the updated information via IPN or API. You can test both on Sandbox.
  • There's only one IPN where you get both payee status and tax status.
  • Changes to payee status caused by OFAC can't be tested on Sandbox.
IPN API

payee_details_changed

The following trigger events 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)

Routine payee status check

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