Integrations

Tipalti payment integration

This section outlines the integration process between Revelator and Tipalti, introducing two essential workflows:

Payor Flow
Payee Flow

In order for any transactions to be a success both flows need to be completed by the involved parties (Payor and Payee).

Payor Flow

You will need to complete this flow once between a Revelator Parent Account and your Tipalti Account.

Complete the Payor component of the Tipalti integration in your parent account, as described below:

Navigate to Account > Integrations > Payment > Tipalti within the UI.
- Staging URL: https://staging.revelator.pro/en/account/integrations?type=payments
- Production URL: https://app.revelator.pro/en/account/integrations?type=payments

Show instructions

↓

Authorize Revelator from your Tipalti account
- Click on Authorize Access
- Follow the provided flow
- Once completed, you will be redirected back

Show instructions

↓

FIll in your Tipalti API Key and Tipalti Partner Name into the form from Step 2
- This information can be found on the Tipalti Administration > API integration page

Show instructions

↓

Your Tipalti integration will show as connected.

Payee Flow

This flow must be completed for each Revelator Payee individually. Payees that dont’t complete this flow will not be eligible for payment via Tipalti.

If you are redirecting users to a white label, this flow is completed at Account > Integrations > Payee settings > Payment Method (field). In this case, the following information is not relevant.

Setting up a Payee directly without the use of an iFrame (as described in the following flow) may work, but we cannot guarantee the success of this approach or future support.

Retrieve the Revelator payeeId from your own user database.
Generate an iFrame hashkey

Use POST /integrations/tipalti/generateIframeHashkey with the payee user access token to generate the hashkey

Show instructions

↓

For more information on the parameters themselves, check Step 3.

Request body

Query Param	Type	Description
`pairs` required	array of objects	Contains a single entry of for each of the expected values in exact order.
`pairs.name` required	string	Name of the field
`pairs.value` required	string	Value

Example Body

{
	"pairs": [
		{ "name": "idap", "value": "12345" },
		{ "name": "payer", "value": "PayerName" },
		{ "name": "ts", "value": "1706384360" },
		{ "name": "uiculture", "value": "en" }
	]
}

Display the Tipalti iFrame to the Payee user

The iFrame needs to be displayed with the same data used to generate the hashkey, with the addition of the hashkey itself.

Show instructions

↓

iFrame url

URL Type	URL
Sandbox URL	`https://ui2.sandbox.tipalti.com/payeedashboard/home`
Production URL	`https://ui2.tipalti.com/payeedashboard/home`

iFrame query params

Query Param	Description
`idap` required	Revelator Payee ID retrieved in the Payee Flow - Step 1
`payer` required	Partner Name used in the Payor Flow - Step 3
`ts` required	Unix timestamp in seconds of the moment iFrame is opened. Offset of more than 10 minutes will return an error.
`uiculture` optional	See tipalti documentation for available cultures
`hashkey` required	Hash key generated based on all other query string parameters. Payee Flow - Step 2

Example iFrame

<iframe 
src="https://ui2.sandbox.tipalti.com/payeedashboard/home?idap=12345&payer=PayerName&ts=1706384360&uiculture=en&hashkey=853c4d06a130c45d2fed954f7769d7feb5a2b2a350dbcab3cec5560972c6ed3e" 
width="734" 
height="640" 
frameborder="0" 
style="display: block;"></iframe>

Visit tipalti documentation for more information

Wait for the Payee completes the iFrame form by filling in their information.
- Identification information
- Adress
- Payment method
- Tax Forms
Update the payment method for the Payee within the Revelator system.

Use POST /accounting/payee/save with the payee user access token.

Show instructions

↓

Since we don’t support partial updates, you will first need to retrieve all payee information by calling GET /accounting/payee/{payeeId}

Update endpoint

POST /accounting/payee/save

Fields to update

URL Type	Description	Value
`paymentProviderId`	An ID that corresponds to a payment provider.	`1`
`paymentProviderName`	A string that corresponds to a payment provider name.	`Tipalti`
`paymentUserId`	A string that corresponds to a Tipalti user ID or a pending value. Only update if the previous payment provider was not Tipalti	`null`

Example request body

{
    // Fields to update
    "paymentProviderId": 1,
	"paymentProviderName": "Tipalti",

    // Optional field to update
	"paymentUserId": null,

    // Other values retrieved from `GET /accounting/payee`
	"contact": {
		"address": null,
		"address2": null,
		"artistId": null,
		"city": null,
		"contactId": 12345,
		"countryId": 244,
		"currencyCode": null,
		"email": "[email protected]",
		"image": null,
		"imageId": null,
		"isActive": false,
		"labelId": null,
		"location": null,
		"name": "Example",
		"phone": null,
		"publisherId": null,
		"state": null,
		"zipcode": null
	},
	"licensors": null,
	"referrer": null,
	"autoSendStatements": false,
	"balance": 0,
	"companyName": "Example Companz",
	"companyOrIndividualID": null,
	"contactId": 12345,
	"contractsNames": [],
	"currencyCode": "USD",
	"enterpriseId": 0,
	"isBlocked": false,
	"isCompany": true,
	"isEnterpriseVip": false,
	"isEnterpriseWhiteListed": false,
	"isInvitationAccepted": null,
	"isInvited": false,
	"isLockedOut": false,
	"isPortalPayee": true,
	"isRoyaltyTokenPayee": false,
	"kountStatusId": null,
	"kountStatusName": null,
	"lastPayementDate": "2024-01-17T13:03:38.85",
	"lastPaymentStatus": "",
	"lastStatementDate": null,
	"lastStatementSentDate": null,
	"minimumPayment": 0,
	"notesCount": 0,
	"payeeId": 12345,
	"paymentInfoRequestedAt": null,
	"payorEnterpriseCurrencyCode": "USD",
	"referrerId": null,
	"role": "",
	"status": 1,
	"taxDomicileCountryId": 244,
	"taxIdNumber": null,
	"userId": "12345abc-12345abc-12345abc-12345abc-12345abc",
	"vatNumber": null,
	"vendorId": null
}

The Payee is now ready to recieve payments via Tipalti.

Make sure the order of params in Step 2 and Step 3 is correct. If the order doesn’t match, the generated hashkey will be invalid.

If the payee doesn’t complete the iFrame form, any transaction attempts in the future will fail. At this point redirect the payee back to the iFrame.

Revenue

Royalty Tokens