Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.
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
What you need
Where it comes from
A Tipalti account
tipalti.com — sandbox and production accounts are separate
A Developer Hub application
developer.sandbox.tipalti.com (sandbox) or developer.tipalti.com (production) → Applications. Gives you a client ID and client secret
Your payer name
Your Tipalti payer dashboard. This is the payer value Tipalti uses to identify your account
iFrame master key (encryption key)
Tipalti → Administration → API integration. Used to sign the promoter onboarding links
Webhook signing secret
Tipalti → Administration → API integration → Secrets management. Used to verify that incoming events really come from Tipalti
Payer entity ID (optional)
Only if your Tipalti account uses multiple paying entities and you want FirstPromoter to pay from a specific one
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.
Option
Payee reference becomes
Use it when
Promoter ID(default)
The promoter’s FirstPromoter ID
You are starting fresh in Tipalti
Promoter email
The promoter’s email address
Your existing Tipalti payees are keyed by email
Promoter custom field
The value of a custom field on the promoter
Your existing Tipalti payees use your own reference, stored on the promoter
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:
Event
Why FirstPromoter needs it
paymentSubmitted
Payment accepted by Tipalti and on its way
paymentCompleted
Payment paid — marks the payout as completed
paymentDeferred
Payment postponed, e.g. waiting for funds
paymentError
Payment failed — marks the payout as failed
paymentCanceled
Payment cancelled in Tipalti
paymentGroupDeclined
Payment group declined — fails the affected payouts
payeeDetailsChanged
Payee became payable, blocked or changed payment method
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:
Badge
Meaning
Pending setup
The payee exists in Tipalti but is not payable yet — usually a missing payment method, an incomplete tax form or a compliance check still in progress. The reasons Tipalti reports are listed on the payout method.
Ready
Tipalti confirms the payee is payable. They can be included in payouts.
Blocked
The payee is blocked or suspended in Tipalti, or you disabled the payout method in FirstPromoter. They are excluded from payouts.
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:
Status in FirstPromoter
When
Processing
Tipalti accepted the instruction and has not reported a final result yet
Completed
Tipalti reported the payment as paid. (Tipalti’s later bank-settlement update does not change anything in FirstPromoter — a paid payment is already complete here.)
Failed
Tipalti rejected or cancelled the payment. Tipalti’s own message is shown on the payout
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.
What happens
Effect
You block a promoter in all of their campaigns in FirstPromoter
The payee is blocked in Tipalti
You disable a promoter’s Tipalti payout method in FirstPromoter
The payee is blocked in Tipalti
You accept/unblock the promoter again, and their payout method is active
The payee is set back to active in Tipalti
Someone blocks the payee in Tipalti
The promoter’s Tipalti payout method is disabled in FirstPromoter
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
Test connection fails
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.
A promoter sees an invalid hashkey or expired link error on Tipalti
The signed onboarding link is short-lived and single-use by design. If a promoter opens an old link, bookmarks it,
or leaves the page open too long, Tipalti rejects it. The fix is always the same: go back to My payouts → Payout
methods in the affiliate portal and start from Continue with Tipalti / Manage in Tipalti again, which
generates a fresh link.A persistent invalid-hashkey error for every promoter usually means the iFrame key or payer name in the
FirstPromoter form does not match the Tipalti account.
A payout stays processing, or a payee status looks stale
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.
Rate limits
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.
Moving from sandbox to production
Switching the environment does not carry anything over — the two Tipalti environments have separate
applications, payers, payees and webhooks. To go live:
Create a production application at developer.tipalti.com with the same six scopes.
Switch the environment to Production in the FirstPromoter form and re-enter all credentials, including the
production iFrame key and webhook secret.
Register the webhook URL again in your production Tipalti account and enable the same events.
Run Test connection, then Enable.
Promoters who onboarded in sandbox exist only in the sandbox account and will need to connect again.
Can I keep using Tipalti manually as well?
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"FirstPromoter Docs","colors":{"primary":"#2497F3","light":"#42A5F5","dark":"#1A1C25"},"logo":{"light":"https://mintcdn.com/firstpromoter/Qml53iAwCwPGiKRZ/logo/light.svg?fit=max\u0026auto=format\u0026n=Qml53iAwCwPGiKRZ\u0026q=85\u0026s=17d35344b27497f795682da8932295c9","dark":"https://mintcdn.com/firstpromoter/Qml53iAwCwPGiKRZ/logo/dark.svg?fit=max\u0026auto=format\u0026n=Qml53iAwCwPGiKRZ\u0026q=85\u0026s=ef23e747176d9a87b5ddf122595793f8"},"favicon":"https://mintcdn.com/firstpromoter/rNk-Jdvp2vdjAvd9/favicon.png?fit=max\u0026auto=format\u0026n=rNk-Jdvp2vdjAvd9\u0026q=85\u0026s=7faf17e323609b0fef661b9a9fe49ebc","navbar":{"links":[{"href":"mailto:support@firstpromoter.com","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://login.firstpromoter.com/"}},"footer":{"socials":{"x":"https://x.com/firstpromoter","linkedin":"https://www.linkedin.com/company/first-promoter"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"firstpromoter","hasAudioNarration":false,"actualSubdomain":"firstpromoter","customDomains":["docs.firstpromoter.com"],"gitSource":{"type":"github","owner":"firstpromoter","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6afafa3dee0aa4defa1c5867","clientVersion":"0.0.4160","searchFilterCounts":[{"language":"default","tag":"Documentation","count":217},{"language":"default","tag":"API Reference","count":81},{"language":"default","tag":"Integration Options","count":43},{"language":"default","tag":"Promoters","count":25},{"language":"default","tag":"Platform","count":23},{"language":"default","tag":"Custom","count":9},{"language":"default","tag":"Webhooks","count":9},{"language":"default","tag":"Reports","count":8},{"language":"default","tag":"Payouts","count":7},{"language":"default","tag":"Commissions","count":7}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"integrations/payouts/tipalti","slug":"/integrations/payouts/tipalti","pageMetadata":{"title":"Tipalti","description":"Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.","href":"/integrations/payouts/tipalti"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,em:`em`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{Accordion,AccordionGroup,CodeBlock,Heading,Note,Step,Steps,Table,Tip,Warning}=_components;if(!Accordion)_missingMdxReference(`Accordion`,true);if(!AccordionGroup)_missingMdxReference(`AccordionGroup`,true);if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);if(!Step)_missingMdxReference(`Step`,true);if(!Steps)_missingMdxReference(`Steps`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Tip)_missingMdxReference(`Tip`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Note,{children:_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Beta.`}),` The Tipalti payout integration is available as a beta feature and appears with a `,_jsx(_components.strong,{children:`Beta`}),` label in\n`,_jsx(_components.strong,{children:`Settings → Integrations`}),`. The setup flow and field names described here may still change.`]})}),`\n`,_jsx(Heading,{level:`1`,id:`what-it-does`,children:`What it does`}),`\n`,_jsx(_components.p,{children:`Tipalti is a mass-payout platform. If you already pay your affiliates through your own Tipalti account, this\nintegration removes the CSV round trip: instead of exporting payouts from FirstPromoter, uploading them to Tipalti and\nmarking them as paid by hand, FirstPromoter sends the payment instructions to Tipalti for you and keeps each payout’s\nstatus in sync.`}),`\n`,_jsx(_components.p,{children:`Once connected:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Promoters onboard as `,_jsx(_components.strong,{children:`payees`}),` in your Tipalti account, through Tipalti’s own secure hosted page — they choose their\npayment method and complete their tax forms there.`]}),`\n`,_jsxs(_components.li,{children:[`Paying a batch of payouts becomes a `,_jsx(_components.strong,{children:`one-click`}),` action in FirstPromoter.`]}),`\n`,_jsx(_components.li,{children:`Payout statuses (paid, failed, deferred) flow back into FirstPromoter automatically.`}),`\n`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`FirstPromoter never holds or moves your money. Payments are made `,_jsx(_components.strong,{children:`by your own Tipalti account, from your own\nfunds`}),` — FirstPromoter only sends the payment instructions and tracks what Tipalti reports back. Funding,\ncompliance, tax forms and payment fees stay between you and Tipalti.`]})}),`\n`,_jsx(Heading,{level:`1`,id:`requirements`,children:`Requirements`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`What you need`}),_jsx(_components.th,{children:`Where it comes from`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`A Tipalti account`}),_jsxs(_components.td,{children:[_jsx(_components.a,{href:`https://tipalti.com`,children:`tipalti.com`}),` — sandbox and production accounts are separate`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`A Developer Hub application`}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`developer.sandbox.tipalti.com`}),` (sandbox) or `,_jsx(_components.code,{children:`developer.tipalti.com`}),` (production) → `,_jsx(_components.strong,{children:`Applications`}),`. Gives you a `,_jsx(_components.strong,{children:`client ID`}),` and `,_jsx(_components.strong,{children:`client secret`})]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Your payer name`}),_jsxs(_components.td,{children:[`Your Tipalti payer dashboard. This is the `,_jsx(_components.code,{children:`payer`}),` value Tipalti uses to identify your account`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`iFrame master key (encryption key)`}),_jsxs(_components.td,{children:[`Tipalti → `,_jsx(_components.strong,{children:`Administration → API integration`}),`. Used to sign the promoter onboarding links`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Webhook signing secret`}),_jsxs(_components.td,{children:[`Tipalti → `,_jsx(_components.strong,{children:`Administration → API integration → Secrets management`}),`. Used to verify that incoming events really come from Tipalti`]})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`Payer entity ID `,_jsx(_components.em,{children:`(optional)`})]}),_jsx(_components.td,{children:`Only if your Tipalti account uses multiple paying entities and you want FirstPromoter to pay from a specific one`})]})]})]}),`\n`,_jsx(_components.p,{children:`Your Developer Hub application must be granted all six of these scopes:`}),`\n`,_jsx(CodeBlock,{numberOfLines:`7`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`7`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`tipalti.api.payee.read`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`tipalti.api.payee.write`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`tipalti.api.payment-batch.read`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`tipalti.api.payment-batch.write`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`tipalti.api.payment.read`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`tipalti.api.payer-entity.read`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsx(Tip,{children:_jsxs(_components.p,{children:[`Missing a scope is the most common cause of a failed `,_jsx(_components.strong,{children:`Test connection`}),`. If you add a scope in the Developer Hub\nafter creating the application, save the credentials in FirstPromoter again so a fresh token is requested.`]})}),`\n`,_jsx(Heading,{level:`1`,id:`connecting-tipalti-in-firstpromoter`,children:`Connecting Tipalti in FirstPromoter`}),`\n`,_jsxs(Steps,{children:[_jsx(Step,{title:`Open the integration`,children:_jsxs(_components.p,{children:[`In FirstPromoter, go to `,_jsx(_components.strong,{children:`Settings → Integrations`}),` and open the `,_jsx(_components.strong,{children:`Tipalti`}),` card (labelled `,_jsx(_components.strong,{children:`Beta`}),`).`]})}),_jsx(Step,{title:`Choose the environment`,children:_jsxs(_components.p,{children:[`Select `,_jsx(_components.strong,{children:`Sandbox`}),` or `,_jsx(_components.strong,{children:`Production`}),`. Sandbox credentials only work against Tipalti’s sandbox, and production\ncredentials only against production — they are never interchangeable.`]})}),_jsxs(Step,{title:`Enter your credentials`,children:[_jsxs(_components.p,{children:[`Fill in your `,_jsx(_components.strong,{children:`payer name`}),`, `,_jsx(_components.strong,{children:`client ID`}),`, `,_jsx(_components.strong,{children:`client secret`}),`, `,_jsx(_components.strong,{children:`iFrame key`}),` and `,_jsx(_components.strong,{children:`webhook secret`}),`, plus a\n`,_jsx(_components.strong,{children:`payer entity ID`}),` if you use one.`]}),_jsx(_components.p,{children:`Secrets are stored encrypted and never shown again. Once saved, the fields display a “configured” placeholder —\nleaving them empty on a later save keeps the existing value, so you only re-enter a secret when you actually\nwant to replace it.`})]}),_jsxs(Step,{title:`Pick how promoters are identified in Tipalti`,children:[_jsxs(_components.p,{children:[`The `,_jsx(_components.strong,{children:`payee identifier`}),` decides what FirstPromoter uses as each promoter’s payee reference code in Tipalti.`]}),_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Option`}),_jsx(_components.th,{children:`Payee reference becomes`}),_jsx(_components.th,{children:`Use it when`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[_jsx(_components.strong,{children:`Promoter ID`}),` `,_jsx(_components.em,{children:`(default)`})]}),_jsx(_components.td,{children:`The promoter’s FirstPromoter ID`}),_jsx(_components.td,{children:`You are starting fresh in Tipalti`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Promoter email`})}),_jsx(_components.td,{children:`The promoter’s email address`}),_jsx(_components.td,{children:`Your existing Tipalti payees are keyed by email`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Promoter custom field`})}),_jsx(_components.td,{children:`The value of a custom field on the promoter`}),_jsx(_components.td,{children:`Your existing Tipalti payees use your own reference, stored on the promoter`})]})]})]}),_jsxs(_components.p,{children:[`You can also set an optional `,_jsx(_components.strong,{children:`reference prefix`}),`, which is prepended to every reference. This is useful when\nseveral FirstPromoter accounts share one Tipalti payer and you need the references to stay unique.`]}),_jsx(Warning,{children:_jsxs(_components.p,{children:[`If you already have payees in Tipalti, choose the option that matches `,_jsx(_components.strong,{children:`your current payee reference codes`}),` —\nFirstPromoter can then reuse those payees instead of creating duplicates. The setting `,_jsx(_components.strong,{children:`locks as soon as the\nfirst payee exists`}),`, because changing it afterwards would orphan every connected promoter.`]})})]}),_jsx(Step,{title:`Save and test`,children:_jsxs(_components.p,{children:[`Click `,_jsx(_components.strong,{children:`Save \u0026 test connection`}),`. FirstPromoter requests a token from Tipalti and performs a read-only call to\nconfirm the credentials and scopes are valid.`]})}),_jsx(Step,{title:`Enable it`,children:_jsxs(_components.p,{children:[`Click `,_jsx(_components.strong,{children:`Enable`}),`. For your security, enabling a payout integration requires a two-factor verification step.`]})}),_jsx(Step,{title:`Offer it to promoters`,children:_jsxs(_components.p,{children:[`Tipalti now appears in `,_jsx(_components.strong,{children:`Payouts → Payout terms`}),` as an available payout method. Enable it there for it to show up\nin your promoters’ affiliate portal.`]})})]}),`\n`,_jsx(Heading,{level:`1`,id:`registering-the-webhook`,children:`Registering the webhook`}),`\n`,_jsx(_components.p,{children:`FirstPromoter relies on Tipalti webhooks to learn when a payment succeeded, failed or was deferred, and when a payee’s\ndetails change.`}),`\n`,_jsxs(Steps,{children:[_jsx(Step,{title:`Copy the webhook URL`,children:_jsxs(_components.p,{children:[`The Tipalti form in FirstPromoter shows a read-only `,_jsx(_components.strong,{children:`webhook URL`}),` with a copy button. It is unique to your\naccount.`]})}),_jsx(Step,{title:`Register it in Tipalti`,children:_jsxs(_components.p,{children:[`In Tipalti, go to `,_jsx(_components.strong,{children:`Administration → API integration → Webhook setup`}),` and add the URL you copied.`]})}),_jsxs(Step,{title:`Enable the events`,children:[_jsx(_components.p,{children:`Enable these events:`}),_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Event`}),_jsx(_components.th,{children:`Why FirstPromoter needs it`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`paymentSubmitted`})}),_jsx(_components.td,{children:`Payment accepted by Tipalti and on its way`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`paymentCompleted`})}),_jsx(_components.td,{children:`Payment paid — marks the payout as completed`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`paymentDeferred`})}),_jsx(_components.td,{children:`Payment postponed, e.g. waiting for funds`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`paymentError`})}),_jsx(_components.td,{children:`Payment failed — marks the payout as failed`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`paymentCanceled`})}),_jsx(_components.td,{children:`Payment cancelled in Tipalti`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`paymentGroupDeclined`})}),_jsx(_components.td,{children:`Payment group declined — fails the affected payouts`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`payeeDetailsChanged`})}),_jsx(_components.td,{children:`Payee became payable, blocked or changed payment method`})]})]})]})]})]}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[`Sandbox and production webhooks are configured `,_jsx(_components.strong,{children:`separately`}),` in Tipalti, and the FirstPromoter webhook URL differs\nper environment setting. When you switch from sandbox to production, register the webhook again.`]})}),`\n`,_jsx(_components.p,{children:`Every incoming event is signature-verified with your webhook secret, and repeated deliveries of the same event are\nignored, so Tipalti’s automatic retries are safe.`}),`\n`,_jsx(Heading,{level:`1`,id:`how-promoters-connect`,children:`How promoters connect`}),`\n`,_jsx(_components.p,{children:`Promoters set Tipalti up themselves, from the affiliate portal:`}),`\n`,_jsxs(Steps,{children:[_jsx(Step,{title:`Open payout methods`,children:_jsxs(_components.p,{children:[`The promoter goes to `,_jsx(_components.strong,{children:`My payouts → Payout methods`}),` and adds `,_jsx(_components.strong,{children:`Tipalti`}),`.`]})}),_jsx(Step,{title:`Continue with Tipalti`,children:_jsxs(_components.p,{children:[`They click `,_jsx(_components.strong,{children:`Continue with Tipalti`}),`. FirstPromoter creates the payee in your Tipalti account and redirects them to\nTipalti’s secure page.`]})}),_jsx(Step,{title:`Complete the Tipalti form`,children:_jsx(_components.p,{children:`On Tipalti’s page, the promoter enters their payment method and completes the required tax forms. This information\nis entered on Tipalti and is never handled by FirstPromoter.`})}),_jsx(Step,{title:`Return to the portal`,children:_jsx(_components.p,{children:`Tipalti sends them back to the affiliate portal, where their payout method now shows its current status.`})})]}),`\n`,_jsx(_components.p,{children:`Statuses shown on the payout method:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Badge`}),_jsx(_components.th,{children:`Meaning`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Pending setup`})}),_jsx(_components.td,{children:`The payee exists in Tipalti but is not payable yet — usually a missing payment method, an incomplete tax form or a compliance check still in progress. The reasons Tipalti reports are listed on the payout method.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Ready`})}),_jsx(_components.td,{children:`Tipalti confirms the payee is payable. They can be included in payouts.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Blocked`})}),_jsx(_components.td,{children:`The payee is blocked or suspended in Tipalti, or you disabled the payout method in FirstPromoter. They are excluded from payouts.`})]})]})]}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[`A promoter is only payable once `,_jsx(_components.strong,{children:`Tipalti’s own compliance checks pass`}),`. Finishing the form is not always enough —\ntax form validation and screening can take additional time, and the badge stays `,_jsx(_components.strong,{children:`Pending setup`}),` until Tipalti says\notherwise. Promoters can reopen the Tipalti page at any time from `,_jsx(_components.strong,{children:`Manage in Tipalti`}),` to fix what’s missing.`]})}),`\n`,_jsx(Heading,{level:`1`,id:`paying-promoters`,children:`Paying promoters`}),`\n`,_jsx(_components.p,{children:`Paying works like any other one-click payout method:`}),`\n`,_jsxs(Steps,{children:[_jsx(Step,{title:`Generate the payouts`,children:_jsx(_components.p,{children:`Approve commissions and generate payouts as usual.`})}),_jsx(Step,{title:`Select and pay`,children:_jsxs(_components.p,{children:[`In `,_jsx(_components.strong,{children:`Payouts`}),`, select the Tipalti payouts and start the payment. FirstPromoter creates `,_jsx(_components.strong,{children:`one Tipalti payment batch\nper FirstPromoter batch`}),`.`]})}),_jsx(Step,{title:`Watch the statuses`,children:_jsxs(_components.p,{children:[`The batch goes to `,_jsx(_components.strong,{children:`processing`}),` while Tipalti works through it, and each payout settles on its own as Tipalti\nreports back.`]})})]}),`\n`,_jsx(_components.p,{children:`What the statuses mean:`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Status in FirstPromoter`}),_jsx(_components.th,{children:`When`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Processing`})}),_jsx(_components.td,{children:`Tipalti accepted the instruction and has not reported a final result yet`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Completed`})}),_jsxs(_components.td,{children:[`Tipalti reported the payment as `,_jsx(_components.strong,{children:`paid`}),`. (Tipalti’s later bank-settlement update does not change anything in FirstPromoter — a paid payment is already complete here.)`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.strong,{children:`Failed`})}),_jsx(_components.td,{children:`Tipalti rejected or cancelled the payment. Tipalti’s own message is shown on the payout`})]})]})]}),`\n`,_jsx(_components.p,{children:`Failed payouts stay selectable — fix the cause in Tipalti (or with the promoter) and include them in a new payout run.`}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[_jsx(_components.strong,{children:`Deferred or pending payer funds.`}),` If your Tipalti account does not hold enough funds, Tipalti defers the payments\ninstead of failing them. Those payouts stay `,_jsx(_components.strong,{children:`processing`}),` in FirstPromoter and the batch shows the reason Tipalti\ngave. Fund your Tipalti account and Tipalti releases them by itself — there is nothing to re-send from\nFirstPromoter.`]})}),`\n`,_jsx(_components.p,{children:`Promoters whose payee is not payable at the moment you pay (missing payment method, tax form pending, blocked) are not\nsent to Tipalti at all. Their payouts are marked as failed with the reason Tipalti reports, so you can see exactly who\nneeds to finish their setup.`}),`\n`,_jsx(Heading,{level:`1`,id:`blocking-and-unblocking`,children:`Blocking and unblocking`}),`\n`,_jsx(_components.p,{children:`Blocks are kept in sync in both directions, with a deliberate bias towards safety.`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`What happens`}),_jsx(_components.th,{children:`Effect`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`You block a promoter in `,_jsx(_components.strong,{children:`all`}),` of their campaigns in FirstPromoter`]}),_jsx(_components.td,{children:`The payee is blocked in Tipalti`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`You disable a promoter’s Tipalti payout method in FirstPromoter`}),_jsx(_components.td,{children:`The payee is blocked in Tipalti`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`You accept/unblock the promoter again, and their payout method is active`}),_jsx(_components.td,{children:`The payee is set back to active in Tipalti`})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`Someone blocks the payee `,_jsx(_components.strong,{children:`in Tipalti`})]}),_jsx(_components.td,{children:`The promoter’s Tipalti payout method is disabled in FirstPromoter`})]})]})]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`A block made `,_jsx(_components.strong,{children:`in Tipalti`}),` is never undone from FirstPromoter. Unblocking a promoter in FirstPromoter will not\nreactivate a payee that Tipalti or your team blocked on the Tipalti side — unblock it in Tipalti first.`]})}),`\n`,_jsx(_components.p,{children:`Blocking never touches payments already in flight: Tipalti reports the outcome of those, and FirstPromoter records it\nas usual.`}),`\n`,_jsx(Heading,{level:`1`,id:`troubleshooting`,children:`Troubleshooting`}),`\n`,_jsxs(AccordionGroup,{children:[_jsx(Accordion,{title:`Test connection fails`,id:`test-connection-fails`,children:_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Missing credentials`}),` — one of payer name, client ID, client secret, iFrame key or webhook secret is empty.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Invalid credentials`}),` — the client ID/secret pair is wrong, or it belongs to the other environment. Sandbox\ncredentials never work against production and vice versa.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Missing permissions`}),` — the application is missing one of the six required scopes. Add it in the Tipalti\nDeveloper Hub, then save the credentials in FirstPromoter again.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Tipalti error`}),` — Tipalti rejected the request for another reason; the message shown comes straight from\nTipalti.`]}),`\n`]})}),_jsxs(Accordion,{title:`A promoter sees an invalid hashkey or expired link error on Tipalti`,id:`a-promoter-sees-an-invalid-hashkey-or-expired-link-error-on-tipalti`,children:[_jsxs(_components.p,{children:[`The signed onboarding link is short-lived and single-use by design. If a promoter opens an old link, bookmarks it,\nor leaves the page open too long, Tipalti rejects it. The fix is always the same: go back to `,_jsx(_components.strong,{children:`My payouts → Payout\nmethods`}),` in the affiliate portal and start from `,_jsx(_components.strong,{children:`Continue with Tipalti`}),` / `,_jsx(_components.strong,{children:`Manage in Tipalti`}),` again, which\ngenerates a fresh link.`]}),_jsxs(_components.p,{children:[`A persistent invalid-hashkey error for `,_jsx(_components.em,{children:`every`}),` promoter usually means the `,_jsx(_components.strong,{children:`iFrame key`}),` or `,_jsx(_components.strong,{children:`payer name`}),` in the\nFirstPromoter form does not match the Tipalti account.`]})]}),_jsxs(Accordion,{title:`A payout stays processing, or a payee status looks stale`,id:`a-payout-stays-processing-or-a-payee-status-looks-stale`,children:[_jsxs(_components.p,{children:[`Tipalti retries a failed webhook delivery a limited number of times, so an outage on either side can drop an event.\nFirstPromoter also `,_jsx(_components.strong,{children:`polls Tipalti periodically`}),` for batches that are still processing and for payees that were\nrecently onboarded, so missed events are picked up automatically — it just takes longer than a webhook.`]}),_jsx(_components.p,{children:`If statuses stay stale for a long time, check that the webhook URL is registered in the right Tipalti environment\nand that all seven events listed above are enabled.`})]}),_jsx(Accordion,{title:`Rate limits`,id:`rate-limits`,children:_jsx(_components.p,{children:`Tipalti applies an account-wide API rate limit. FirstPromoter batches its calls (one payment batch per payout run\nrather than one call per promoter) and backs off when Tipalti asks it to, so large payout runs are safe. If you\nalso call the Tipalti API from your own systems, keep in mind that the limit is shared across everything using\nyour Tipalti account.`})}),_jsxs(Accordion,{title:`Moving from sandbox to production`,id:`moving-from-sandbox-to-production`,children:[_jsxs(_components.p,{children:[`Switching the environment does `,_jsx(_components.strong,{children:`not`}),` carry anything over — the two Tipalti environments have separate\napplications, payers, payees and webhooks. To go live:`]}),_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`Create a production application at `,_jsx(_components.code,{children:`developer.tipalti.com`}),` with the same six scopes.`]}),`\n`,_jsxs(_components.li,{children:[`Switch the environment to `,_jsx(_components.strong,{children:`Production`}),` in the FirstPromoter form and re-enter all credentials, including the\nproduction iFrame key and webhook secret.`]}),`\n`,_jsx(_components.li,{children:`Register the webhook URL again in your production Tipalti account and enable the same events.`}),`\n`,_jsxs(_components.li,{children:[`Run `,_jsx(_components.strong,{children:`Test connection`}),`, then `,_jsx(_components.strong,{children:`Enable`}),`.`]}),`\n`]}),_jsx(_components.p,{children:`Promoters who onboarded in sandbox exist only in the sandbox account and will need to connect again.`})]}),_jsx(Accordion,{title:`Can I keep using Tipalti manually as well?`,id:`can-i-keep-using-tipalti-manually-as-well`,children:_jsx(_components.p,{children:`Yes. Payments created directly in Tipalti are unaffected, and FirstPromoter only tracks the payments it submitted\nitself. If you already have payees in Tipalti, set the payee identifier to match your existing reference codes\nbefore any promoter connects, so FirstPromoter reuses them instead of creating duplicates.`})})]}),`\n`,_jsx(Heading,{level:`1`,id:`related`,children:`Related`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/api-reference-v2/api-admin/payouts/get-all-payouts`,children:`Payouts API`})}),`\n`,_jsx(_components.li,{children:_jsx(_components.a,{href:`/api-reference-v2/api-affiliate/payout-methods/get-all-payout-methods-for-current-promoter`,children:`Affiliate payout methods API`})}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Tipalti","description":"Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.","href":"/integrations/payouts/tipalti"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"What it does","slug":"what-it-does","depth":1,"children":[]},{"title":"Requirements","slug":"requirements","depth":1,"children":[]},{"title":"Connecting Tipalti in FirstPromoter","slug":"connecting-tipalti-in-firstpromoter","depth":1,"children":[]},{"title":"Registering the webhook","slug":"registering-the-webhook","depth":1,"children":[]},{"title":"How promoters connect","slug":"how-promoters-connect","depth":1,"children":[]},{"title":"Paying promoters","slug":"paying-promoters","depth":1,"children":[]},{"title":"Blocking and unblocking","slug":"blocking-and-unblocking","depth":1,"children":[]},{"title":"Troubleshooting","slug":"troubleshooting","depth":1,"children":[]},{"title":"Related","slug":"related","depth":1,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/firstpromoter/8ad42af542d542c7/downloadables/fpr-prox.js"],"subdomain":"firstpromoter","siteName":"FirstPromoter Docs","title":"Tipalti - FirstPromoter Docs","navMaps":{"firstHrefInVersion":{"v2":{"href":"/integrations/payouts/tipalti","matchLevel":0},"v1":{"href":"/integrations/billing/stripe","matchLevel":2}},"firstHrefInLanguage":{}},"lastModified":"2026-11-16T12:42:16.119Z","originalFileLocation":"integrations/payouts/tipalti.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.\">\u003cmeta data-mint-head name=\"application-name\" content=\"FirstPromoter Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Tipalti - FirstPromoter Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"FirstPromoter Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.firstpromoter.com/integrations/payouts/tipalti\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://firstpromoter.mintlify.site/_mintlify/api/og/v2?division=Payout+Provider\u0026amp;title=Tipalti\u0026amp;description=Pay+your+promoters+from+your+own+Tipalti+account%2C+one+click+at+a+time%2C+without+leaving+FirstPromoter.\u0026amp;theme=fff9650e72028c28308bb6bc\u0026amp;signature=33df46c54d4a88db846551889e2db40c8769bf7155565403fb5126fd6ccacdf2\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Tipalti - FirstPromoter Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://firstpromoter.mintlify.site/_mintlify/api/og/v2?division=Payout+Provider\u0026amp;title=Tipalti\u0026amp;description=Pay+your+promoters+from+your+own+Tipalti+account%2C+one+click+at+a+time%2C+without+leaving+FirstPromoter.\u0026amp;theme=fff9650e72028c28308bb6bc\u0026amp;signature=33df46c54d4a88db846551889e2db40c8769bf7155565403fb5126fd6ccacdf2\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"FirstPromoter Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2497F3\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.firstpromoter.com/integrations/payouts/tipalti\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/integrations/payouts/tipalti.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.firstpromoter.com/#organization\",\"name\":\"FirstPromoter Docs\",\"url\":\"https://docs.firstpromoter.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/firstpromoter/Qml53iAwCwPGiKRZ/logo/light.svg?fit=max\u0026auto=format\u0026n=Qml53iAwCwPGiKRZ\u0026q=85\u0026s=17d35344b27497f795682da8932295c9\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.firstpromoter.com#website\",\"name\":\"FirstPromoter Docs\",\"url\":\"https://docs.firstpromoter.com\",\"publisher\":{\"@id\":\"https://docs.firstpromoter.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.firstpromoter.com/integrations/payouts/tipalti#webpage\",\"url\":\"https://docs.firstpromoter.com/integrations/payouts/tipalti\",\"name\":\"Tipalti\",\"description\":\"Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.\",\"dateModified\":\"2026-11-16T12:42:16.119Z\",\"isPartOf\":{\"@id\":\"https://docs.firstpromoter.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.firstpromoter.com/integrations/payouts/tipalti#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.firstpromoter.com/integrations/payouts/tipalti#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Integration Options\",\"item\":\"https://docs.firstpromoter.com/integrations/billing/stripe\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Tipalti\",\"item\":\"https://docs.firstpromoter.com/integrations/payouts/tipalti\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.firstpromoter.com/integrations/payouts/tipalti#article\",\"headline\":\"Tipalti\",\"name\":\"Tipalti\",\"description\":\"Pay your promoters from your own Tipalti account, one click at a time, without leaving FirstPromoter.\",\"url\":\"https://docs.firstpromoter.com/integrations/payouts/tipalti\",\"mainEntityOfPage\":{\"@id\":\"https://docs.firstpromoter.com/integrations/payouts/tipalti#webpage\"},\"dateModified\":\"2026-11-16T12:42:16.119Z\",\"publisher\":{\"@id\":\"https://docs.firstpromoter.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.firstpromoter.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"FirstPromoter Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"FirstPromoter Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/integrations/payouts/tipalti.md","siteName":"FirstPromoter Docs","nav":{"global":null,"versions":[{"version":"v2","anchors":[{"anchor":"Documentation","icon":"book-open","tabs":[{"tab":"Documentation","groups":[{"group":"Overview","pages":[{"title":"Introduction","href":"/introduction"},{"title":"How FirstPromoter works","href":"/how-it-works"},{"title":"Quickstart","href":"/quickstart"}]},{"group":"How to guides","pages":[{"title":"Integrate Your Website","href":"/guides/integrate-your-website"},{"title":"Tracking with fpr.js","href":"/guides/tracking-with-fprjs"},{"title":"Tracking without fpr.js","href":"/guides/tracking-without-fprjs"},{"title":"Proxy Setup (Optional)","href":"/guides/proxy-setup"},{"title":"Deep Linking for Mobile Apps (Flutter, iOS, Android, React Native)","href":"/guides/mobile-deep-linking"},{"title":"Mobile Attribution Providers (Branch.io, AppsFlyer, Adjust)","href":"/guides/mobile-attribution-providers"}]},{"group":"Advanced","pages":[{"title":"Embed the Dashboard \u0026 Auto-Login Promoters","href":"/advanced/embed-dashboard-login"},{"title":"Log Promoters Out of the Embedded Dashboard","href":"/advanced/embed-dashboard-logout"}]},{"group":"Scripts","pages":[{"title":"FirstPromoter JavaScript Library (fpr.js)","href":"/script-docs/fpr-js-docs"},{"title":"Advanced use cases \u0026 examples","href":"/script-docs/advanced"},{"title":"Concepts \u0026 Key Terminologies","href":"/script-docs/concepts"}]},{"group":"Integration Options","pages":[{"group":"Billing Provider","pages":[{"title":"Stripe","href":"/integrations/billing/stripe"},{"title":"Chargebee","href":"/integrations/billing/chargebee"},{"title":"Recurly","href":"/integrations/billing/recurly"},{"title":"Paddle","href":"/integrations/billing/paddle"},{"title":"Braintree","href":"/integrations/billing/braintree"},{"title":"API","description":"Tracking sales with API","href":"/integrations/billing/api"}]},{"group":"Payout Provider","pages":[{"title":"Tipalti","href":"/integrations/payouts/tipalti"},{"title":"Wise payouts","description":"Prepare affiliate payout batches with your Wise Business API token, then approve them in Wise.","href":"/integrations/payouts/wise"}]},{"group":"Platform","pages":[{"title":"WordPress","href":"/integrations/tracking/platform/wordpress"},{"title":"Highlevel","href":"/integrations/tracking/platform/highlevel"},{"title":"ClickFunnels","href":"/integrations/tracking/platform/clickfunnels"},{"group":"Stripe","pages":[{"title":"Payment Links","href":"/integrations/tracking/platform/stripe/payment-links"},{"title":"Pricing Table","href":"/integrations/tracking/platform/stripe/pricing-table"}]},{"title":"Ghost","href":"/integrations/tracking/platform/ghost"},{"title":"Webflow","href":"/integrations/tracking/platform/webflow"},{"title":"Kajabi","href":"/integrations/tracking/platform/kajabi"},{"title":"ThriveCart","href":"/integrations/tracking/platform/thrivecart"},{"title":"Samcart","href":"/integrations/tracking/platform/samcart"},{"title":"Kartra","href":"/integrations/tracking/platform/kartra"},{"title":"DropFunnels","href":"/integrations/tracking/platform/dropfunnels"},{"title":"Calendly","href":"/integrations/tracking/platform/calendly"},{"title":"Demio","href":"/integrations/tracking/platform/demio"},{"title":"Kickpages","href":"/integrations/tracking/platform/kickpages"},{"title":"Thinkific","href":"/integrations/tracking/platform/thinkific"},{"title":"HubSpot","href":"/integrations/tracking/platform/hubspot"},{"title":"Jotform","href":"/integrations/tracking/platform/jotform"},{"title":"Typeform","href":"/integrations/tracking/platform/typeform"},{"title":"WebinarJam","href":"/integrations/tracking/platform/webinarjam"},{"title":"Recurly Hosted Pages","href":"/integrations/tracking/platform/recurly-hosted-pages"},{"group":"Chargebee","pages":[{"title":"Drop-in Scripts","href":"/integrations/tracking/platform/chargebee/drop-in-scripts"},{"title":"Hosted Pages","href":"/integrations/tracking/platform/chargebee/hosted-pages"}]}]},{"group":"Custom","pages":[{"title":"JavaScript Tracking","href":"/integrations/tracking/custom/js"},{"title":"API Integration","href":"/integrations/tracking/custom/api"},{"title":"Django","href":"/integrations/tracking/custom/django"},{"title":"PHP","href":"/integrations/tracking/custom/php"},{"title":"Ruby on Rails","href":"/integrations/tracking/custom/rails"},{"title":"Stripe Checkout","href":"/integrations/tracking/custom/stripe-checkout"},{"title":"Paddle Checkout","href":"/integrations/tracking/custom/paddle-checkout"},{"title":"Supabase","href":"/integrations/tracking/custom/supabase"},{"title":"Google Tag Manager","href":"/integrations/tracking/custom/gtm"}]},{"group":"Automation","pages":[{"title":"n8n node","href":"/automation/n8n-node"},{"title":"Zapier","href":"/automation/zapier"},{"title":"Make.com","href":"/automation/make"}]}]},{"group":"Webhooks","pages":[{"title":"Webhooks v2 Overview","href":"/webhooks-v2/overview"},{"title":"Event Types","href":"/webhooks-v2/event-types"},{"title":"Payload Structure","href":"/webhooks-v2/payload"},{"title":"Delivery Tracking \u0026 Retries","href":"/webhooks-v2/deliveries"},{"title":"Non-Monetary Rewards","href":"/webhooks-v2/non-monetary-rewards"}]},{"group":"MCP Server (Experimental)","pages":[{"title":"MCP Server","href":"/mcp/overview"},{"title":"Available Tools","href":"/mcp/tools"}]}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/api-reference-v2/api-admin/introduction"}]},{"tab":"Affiliate API Reference","hidden":true,"pages":[{"title":"Affiliate API Reference","href":"/api-reference-v2/api-affiliate/introduction"}]},{"tab":"Advanced API Reference","hidden":true,"pages":[{"title":"Advanced API Reference","href":"/api-reference-v2/api-advanced/introduction"}]}]},{"anchor":"API Reference","icon":"webhook","href":"https://docs.firstpromoter.com/api-reference-v2/api-admin/introduction"},{"anchor":"Help Center","icon":"square-question","href":"https://help.firstpromoter.com/en/"}]},{"version":"v1","pages":[{"title":"v1","href":"/integrations/billing/stripe"}]}]},"basePath":"","title":"Tipalti - FirstPromoter Docs","buildId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","deploymentId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","dynamics":[],"chunks":[]}