Skip to main content
Beta. The Tipalti payout integration is available as a beta feature and appears with a Beta label in Settings → Integrations. The setup flow and field names described here may still change.

What it does

Tipalti is a mass-payout platform. If you already pay your affiliates through your own Tipalti account, this integration removes the CSV round trip: instead of exporting payouts from FirstPromoter, uploading them to Tipalti and marking them as paid by hand, FirstPromoter sends the payment instructions to Tipalti for you and keeps each payout’s status in sync. Once connected:
  • Promoters onboard as payees in your Tipalti account, through Tipalti’s own secure hosted page — they choose their payment method and complete their tax forms there.
  • Paying a batch of payouts becomes a one-click action in FirstPromoter.
  • Payout statuses (paid, failed, deferred) flow back into FirstPromoter automatically.
FirstPromoter never holds or moves your money. Payments are made by your own Tipalti account, from your own funds — FirstPromoter only sends the payment instructions and tracks what Tipalti reports back. Funding, compliance, tax forms and payment fees stay between you and Tipalti.

Requirements

Your Developer Hub application must be granted all six of these scopes:
Missing a scope is the most common cause of a failed Test connection. If you add a scope in the Developer Hub after creating the application, save the credentials in FirstPromoter again so a fresh token is requested.

Connecting Tipalti in FirstPromoter

1

Open the integration

In FirstPromoter, go to Settings → Integrations and open the Tipalti card (labelled Beta).
2

Choose the environment

Select Sandbox or Production. Sandbox credentials only work against Tipalti’s sandbox, and production credentials only against production — they are never interchangeable.
3

Enter your credentials

Fill in your payer name, client ID, client secret, iFrame key and webhook secret, plus a payer entity ID if you use one.Secrets are stored encrypted and never shown again. Once saved, the fields display a “configured” placeholder — leaving them empty on a later save keeps the existing value, so you only re-enter a secret when you actually want to replace it.
4

Pick how promoters are identified in Tipalti

The payee identifier decides what FirstPromoter uses as each promoter’s payee reference code in Tipalti.You can also set an optional reference prefix, which is prepended to every reference. This is useful when several FirstPromoter accounts share one Tipalti payer and you need the references to stay unique.
If you already have payees in Tipalti, choose the option that matches your current payee reference codes — FirstPromoter can then reuse those payees instead of creating duplicates. The setting locks as soon as the first payee exists, because changing it afterwards would orphan every connected promoter.
5

Save and test

Click Save & test connection. FirstPromoter requests a token from Tipalti and performs a read-only call to confirm the credentials and scopes are valid.
6

Enable it

Click Enable. For your security, enabling a payout integration requires a two-factor verification step.
7

Offer it to promoters

Tipalti now appears in Payouts → Payout terms as an available payout method. Enable it there for it to show up in your promoters’ affiliate portal.

Registering the webhook

FirstPromoter relies on Tipalti webhooks to learn when a payment succeeded, failed or was deferred, and when a payee’s details change.
1

Copy the webhook URL

The Tipalti form in FirstPromoter shows a read-only webhook URL with a copy button. It is unique to your account.
2

Register it in Tipalti

In Tipalti, go to Administration → API integration → Webhook setup and add the URL you copied.
3

Enable the events

Enable these events:
Sandbox and production webhooks are configured separately in Tipalti, and the FirstPromoter webhook URL differs per environment setting. When you switch from sandbox to production, register the webhook again.
Every incoming event is signature-verified with your webhook secret, and repeated deliveries of the same event are ignored, so Tipalti’s automatic retries are safe.

How promoters connect

Promoters set Tipalti up themselves, from the affiliate portal:
1

Open payout methods

The promoter goes to My payouts → Payout methods and adds Tipalti.
2

Continue with Tipalti

They click Continue with Tipalti. FirstPromoter creates the payee in your Tipalti account and redirects them to Tipalti’s secure page.
3

Complete the Tipalti form

On Tipalti’s page, the promoter enters their payment method and completes the required tax forms. This information is entered on Tipalti and is never handled by FirstPromoter.
4

Return to the portal

Tipalti sends them back to the affiliate portal, where their payout method now shows its current status.
Statuses shown on the payout method:
A promoter is only payable once Tipalti’s own compliance checks pass. Finishing the form is not always enough — tax form validation and screening can take additional time, and the badge stays Pending setup until Tipalti says otherwise. Promoters can reopen the Tipalti page at any time from Manage in Tipalti to fix what’s missing.

Paying promoters

Paying works like any other one-click payout method:
1

Generate the payouts

Approve commissions and generate payouts as usual.
2

Select and pay

In Payouts, select the Tipalti payouts and start the payment. FirstPromoter creates one Tipalti payment batch per FirstPromoter batch.
3

Watch the statuses

The batch goes to processing while Tipalti works through it, and each payout settles on its own as Tipalti reports back.
What the statuses mean: Failed payouts stay selectable — fix the cause in Tipalti (or with the promoter) and include them in a new payout run.
Deferred or pending payer funds. If your Tipalti account does not hold enough funds, Tipalti defers the payments instead of failing them. Those payouts stay processing in FirstPromoter and the batch shows the reason Tipalti gave. Fund your Tipalti account and Tipalti releases them by itself — there is nothing to re-send from FirstPromoter.
Promoters whose payee is not payable at the moment you pay (missing payment method, tax form pending, blocked) are not sent to Tipalti at all. Their payouts are marked as failed with the reason Tipalti reports, so you can see exactly who needs to finish their setup.

Blocking and unblocking

Blocks are kept in sync in both directions, with a deliberate bias towards safety.
A block made in Tipalti is never undone from FirstPromoter. Unblocking a promoter in FirstPromoter will not reactivate a payee that Tipalti or your team blocked on the Tipalti side — unblock it in Tipalti first.
Blocking never touches payments already in flight: Tipalti reports the outcome of those, and FirstPromoter records it as usual.

Troubleshooting

  • Missing credentials — one of payer name, client ID, client secret, iFrame key or webhook secret is empty.
  • Invalid credentials — the client ID/secret pair is wrong, or it belongs to the other environment. Sandbox credentials never work against production and vice versa.
  • Missing permissions — the application is missing one of the six required scopes. Add it in the Tipalti Developer Hub, then save the credentials in FirstPromoter again.
  • Tipalti error — Tipalti rejected the request for another reason; the message shown comes straight from Tipalti.
Tipalti retries a failed webhook delivery a limited number of times, so an outage on either side can drop an event. FirstPromoter also polls Tipalti periodically for batches that are still processing and for payees that were recently onboarded, so missed events are picked up automatically — it just takes longer than a webhook.If statuses stay stale for a long time, check that the webhook URL is registered in the right Tipalti environment and that all seven events listed above are enabled.
Tipalti applies an account-wide API rate limit. FirstPromoter batches its calls (one payment batch per payout run rather than one call per promoter) and backs off when Tipalti asks it to, so large payout runs are safe. If you also call the Tipalti API from your own systems, keep in mind that the limit is shared across everything using your Tipalti account.
Switching the environment does not carry anything over — the two Tipalti environments have separate applications, payers, payees and webhooks. To go live:
  1. Create a production application at developer.tipalti.com with the same six scopes.
  2. Switch the environment to Production in the FirstPromoter form and re-enter all credentials, including the production iFrame key and webhook secret.
  3. Register the webhook URL again in your production Tipalti account and enable the same events.
  4. Run Test connection, then Enable.
Promoters who onboarded in sandbox exist only in the sandbox account and will need to connect again.
Yes. Payments created directly in Tipalti are unaffected, and FirstPromoter only tracks the payments it submitted itself. If you already have payees in Tipalti, set the payee identifier to match your existing reference codes before any promoter connects, so FirstPromoter reuses them instead of creating duplicates.

Related