Skip to main content

Payments (Tipalti™) Integration Guide

Presented by Exchange Solutions | October 2, 2025

Overview​

Tipalti™ provides a global payment platform with automated end-to-end loyalty points redemptions, enabling instant payouts across multiple currencies and jurisdictions.

For example, a client loyalty member initiates redemption through the loyalty program interface (external to ES Loyalty™). The external system transmits relevant data points to an ES Loyalty API endpoint. The ES Loyalty system validates eligibility, redeems the points, creates transaction records, creates a payment batch, and transmits the payment batch to Tipalti for payment processing. A Client Support Representative (CSR) can view transaction and payment details in both Tipalti and the ES Loyalty platform, ensuring a complete audit trail.

The core capabilities of the ES Loyalty–Tipalti integration include:

  1. Automated eligibility validation: Real-time verification of member payout eligibility.
  2. Multi-member batch processing: Support for member-household-based payouts.
  3. Global payment processing: Tipalti handles currency conversion and local banking.
  4. Comprehensive audit trail: Complete transaction history generated for compliance.
  5. Error handling and notification: Failure detection and member notification.

This guide helps clients understand the roles involved—including the Exchange Solutions TSA and Client Administrator—in setting up and enabling the Tipalti payment provider integration within their loyalty program. The integration lets loyalty members redeem points for cash equivalents, processed via Tipalti.

note

The integration supports ad-hoc redemption transactions only.

Transaction and payment flow​

caution

Understanding how the integration works is essential for successful client implementation and troubleshooting.

The integration is configured to work with ad-hoc redemption transactions in both household and non-household-based loyalty programs. An ad-hoc redemption is a real-time request for redemption from a member. When an ad-hoc redemption transaction is performed for a household with several loyalty members, the following steps occur:

  1. A query is made to Tipalti to verify that all contributing loyalty members in a household have corresponding accounts (known as Payees) in Tipalti and that these members are eligible to be paid out. An eligible member is one who has been successfully registered in the Tipalti platform. This status generally means that the member has provided a suitable payment method and uploaded the necessary tax forms. For further information about eligible Payees, direct client questions to Tipalti Customer Support.

  2. If all contributing members are eligible:

    • An ad-hoc redemption transaction is executed.
    • The payment marker is stamped to the transaction.
    • At the end of the business day, all marked transactions are assembled as payment instructions and sent to Tipalti.

  3. If even one contributing member is ineligible:

    • A 400 error response is returned during the reservation portion of the ad-hoc redemption flow.
    • No ad-hoc redemption transaction is created.
    • No payment instructions are sent to Tipalti.
    • The front end must capture the error and display a generic message about member eligibility issues.
    • The Client Loyalty Administrator must identify and help onboard the ineligible member.

Key features of the integration​

  1. All-or-nothing approach: If any member in a household redemption is ineligible for payment, the transaction request fails.
  2. Real-time member payment eligibility validation: Payment eligibility is checked at transaction time, not when the payment is processed.
  3. Daily batch processing: Successful transactions are batched and sent to Tipalti at the end of the business day.
  4. Error handling: Front-end applications must handle and display eligibility errors appropriately.
  5. Use of iFrame: In some implementations, banking details are captured and the member's payment history is presented via an iFrame embedded in a member-accessible website page. This lets members self-serve redemption initiation and review their payments.
    note

    ES Loyalty's external identifier (for example, the Payee ID) must be pre-populated in the Tipalti iFrame, as this value is recorded in Tipalti's system and used in downstream integration. The iFrame example shown during setup does not represent the client's final version, which is subject to their own styling guidelines.

Pre-setup processes​

Pre-setup work must be completed for every new client.

Step 1: Complete the KYC process​

Before beginning the Tipalti integration setup, clients must complete Tipalti's Know Your Customer (KYC) process. The Exchange Solutions Technical Solutions Architect (TSA) provides support during this process.

Submit the following to Tipalti:

  • Business information
  • Identity verification details
  • Bank account details
  • Tax forms
  • Any other details communicated by Tipalti

Duration: This process may take several weeks.

Step 2: Setup and configuration form​

Once KYC is complete, Tipalti provides a form to capture details from the client. The Exchange Solutions TSA may need to collect the following information from the client:

  • Payment entity name (to display in Tipalti)
  • Supported payment methods
  • Preferred payment currency
  • Notification email addresses

Step 3: Instance provisioning and QA​

  • Tipalti provisions the new instance based on the submitted form.
  • Tipalti performs initial QA checks to confirm correct setup.

Step 4: Integration validation and certification​

  • Exchange Solutions demonstrates that the integration is functioning.
  • Once validated, Tipalti certifies the integration. Re-certification is required if a new API endpoint is introduced or new Tipalti capabilities are used.
  • The TSA can then proceed with the remaining setup steps.

Setup checklist​

The following table summarizes the steps required to set up the Tipalti instance correctly.

#DetailsAction by
1Set up Tipalti production applicationClient Tipalti Administrator
2Provide payer entity to Exchange SolutionsClient Tipalti Administrator
3Provide client ID and client secret to Exchange SolutionsClient Tipalti Administrator
4Provide webhook listener endpoints to TipaltiExchange Solutions TSA
5Set up webhook in TipaltiClient Tipalti Administrator
6Provide webhook secret to Exchange SolutionsClient Tipalti Administrator
7Create custom fields in Tipalti (to help troubleshoot payment issues)Client Tipalti Administrator
8Provide custom field identifiers to Exchange SolutionsClient Tipalti Administrator

1. Set up the Tipalti production application​

The first step in enabling the Exchange Solutions integration with Tipalti is to have the client technical team set up a production application. This application must be created in the production instance.

  1. Create this application in the Production Developer hub.
  2. Fulfill Tipalti's requirement as noted in the Quick Start documentation: you must create your user in Sandbox, and again in the Production environment.
  3. A Tipalti user with a Dev Hub Admin role is required to access the Developers hub and create the required application.
  4. The Dev Hub Admin must create an application that uses the Client credentials flow for authorization. For more information, review the Quick Start documentation from Tipalti.
  5. Name the application: ESLoyaltyWeb.
  6. Grant all scopes to the application.

2. Provide payer entity to Exchange Solutions​

  1. The client provides the Payer ID of the Tipalti instance to Exchange Solutions.

  2. Query the payer-entities endpoint (reference: Get list of payer entities). If the Exchange Solutions TSA is requested to assist, they will need the client ID, the client secret of the production application, and the production API URL.

  3. After querying, retrieve the Payer ID Value for the required payer entity and send it to Exchange Solutions in the following format:

    #Payer IDPayer ID Value
    1Tipalti Payer ID(example: 13166956595405700454190000)
    note
    • The Payer ID refers to the business entity handling the payments. All payments are drawn from the virtual accounts belonging to the Payer ID provided.
    • The Tipalti integration requires that all payments be processed through a single payer entity for a given loyalty instance. A client who wants to process payments using different payer entities for different business entities requires a separate loyalty instance for each.
    • Examples:
      • BUYCO US → BUYCO US Loyalty Instance → Tipalti BUYCO US Payer Entity
      • BUYCO CA → BUYCO CA Loyalty Instance → Tipalti BUYCO CA Payer Entity

3. Provide client ID and client secret to Exchange Solutions​

After creating the production application (see step 1), provide the following to the Exchange Solutions TSA:

#ItemValue
1Client ID
2Client Secret
3Scope

4. Exchange Solutions provides webhook endpoints to Tipalti administrator​

  1. Exchange Solutions sets up a webhook per client for each Tipalti payment event.
  2. Once the endpoints are set up, the TSA provides the following webhook URLs to the Tipalti Administrator:
#Tipalti payment eventWebhook URL
1Payment Error
2Payment Completed
3Payment Submitted
4Payment Cancelled
5Payment Deferred

Example webhook URL format:

https://api2-us-east-1.stage.exchangesolutions.com/<client-partner>/webhooks/partners/TIPALTI/events/<Tipalti_Payment_Event>

5. Set up a webhook in Tipalti​

  1. Once the webhook URLs are received from Exchange Solutions, the Tipalti Administrator sets up the webhooks so that payment events are sent to ES Loyalty and reflected in members' transaction histories.
  2. A client user with the Tipalti Administrator privilege logs in to Tipalti's Account hub and navigates to Administration > API Integration.
  3. The Administrator sets up a webhook for each Tipalti payment event. Refer to the completed table in step 4 to configure each webhook.

6. Provide webhook secrets to Exchange Solutions​

The Client Tipalti Administrator provides the Webhook Secret Key Value to Exchange Solutions.

#Webhook secret keyValue
1Webhook Secret Key

7. Create custom fields in Tipalti​

  1. The Client Tipalti Administrator must add the following custom fields to enable additional metadata to be transferred:

    • eslAccountID
    • eslTransactionID

    By attaching these metadata attributes, the Client Tipalti Administrator can work with the Exchange Solutions TSA to investigate any issues related to the loyalty redemption (ad-hoc redeem) transaction that contributed to a payment.

  2. In the Tipalti Console, navigate to Administration > General in the sidebar menu.

  3. Select the Custom Fields tab.

  4. Click Add Custom Field and create the following custom fields:

    #Custom field nameDisplay nameDescriptionEntityValue typeDisplay options
    1eslAccountIDeslAccountIDeslAccountIDPaymentStringShow in Payment History iFrame
    2eslTransactionIDeslTransactionIDeslTransactionIDPaymentStringShow in Payment History iFrame
    note

    These custom fields are available in the Payment Details section in Tipalti.

8. Provide custom field identifiers to Exchange Solutions​

  1. The client provides the numeric identifiers for the above custom fields to Exchange Solutions. If the Exchange Solutions TSA is required to assist, they will need the client ID and client secret of the production application, as well as the production API URL.

  2. Query the Custom Field endpoint (reference: Get list of custom fields).

  3. After querying, retrieve the id for both custom fields and send it to Exchange Solutions:

    #Custom field nameCustom field ID
    1eslAccountID(example: 14641514788318013193090000)
    2eslTransactionID

Payment troubleshooting scenarios​

The following failed payment scenarios can occur. Possible causes and remediation steps are listed for each. The relevant remediation is communicated to the client when they contact Exchange Solutions for assistance.

Scenario 1: Individual payment cancelled from within Tipalti Console​

When can this happen?

  • The Client Tipalti Administrator cancels a payment from within the Tipalti Console.
  • The Client Administrator may do this for various reasons—for example, a member called to report a mistaken redemption, or there are business reasons not to issue cash payouts.

Possible remediation options:

The client tracks the payment amount requested and either processes it manually or issues discretionary points to the member to correct the account balance.

Scenario 2: Payment is deferred​

When can this happen?

  • The member was initially eligible for payment but has since become unpayable.
  • The member is payable but uses a payment method that isn't configured in Tipalti.

Possible remediation options:

  • The Client Tipalti Administrator advises the member to use a supported payment method.
  • The Client Tipalti Administrator creates a payment batch file manually and issues payment through a manual batch upload, or issues discretionary points to the member's account and asks the member to go through the redemption process again.

Scenario 3: Entire payment batch declined from within Tipalti Console​

When can this happen?

  • The Client Tipalti Administrator declines the entire batch of payments.
  • This is a rare case that most likely reflects an extraordinary business event.

Possible remediation options:

  • The Client Tipalti Administrator navigates to payment history, reviews cancelled payments, and identifies all affected members and their requested payout amounts.
  • The Client Administrator creates a payment batch file manually and issues payment through a manual batch upload to Tipalti, or issues discretionary points to affected members and asks them to go through the redemption process again.

Scenario 4: Payment batch fails on resubmission​

A payment batch is resubmitted as part of ES Loyalty's internal retry mechanism but still fails.

When can this happen?

  • The Tipalti payment gateway is undergoing maintenance or is unavailable.
  • There are network issues on Exchange Solutions servers.

Possible remediation options:

The failed payment instructions roll over into the next payment batch. By that time, network or system issues are typically resolved and payment proceeds.

If payment instructions continue to fail, additional work is required within Exchange Solutions to remove the payment markers so that the failed instructions are not continuously sent to Tipalti. If this persists, a joint investigation with Tipalti is needed to identify and resolve the issue.

Enabling the integration: Exchange Solutions provider configuration​

Once the above configuration details are received, the Exchange Solutions TSA follows internal instructions for payment provider integration. Integration is also guided by the following Tipalti documentation:

Examples of user stories​

The following examples illustrate how the ES Loyalty / Tipalti integration can be used.

User story 1: Individual redeems loyalty points, receives direct-deposit payment​

The member initiates a redemption request using a Tipalti iFrame embedded in the client's website. The iFrame is pre-populated with ES Loyalty's external identifier, as this value is recorded in the Tipalti system and used in downstream integration.

As a loyalty member, I want to self-redeem my loyalty points and receive the payout via direct deposit so that I don't have to spend time cashing cheques.

Acceptance criteria:

  1. Member initiates a redemption through the external loyalty interface (the iFrame).
  2. System validates eligibility in real time.
  3. System redeems points. Transaction history is available in the ES Loyalty Console.
  4. Payment is processed.
  5. Member receives the payout via direct deposit to their account.

User story 2: Household redeems loyalty points, receives direct-deposit payments​

As a loyalty account head of household (the primary member), I want to redeem points for household members and issue payment via direct deposit so that I no longer need to issue cheques to household members. Payment is proportional to each member's contribution to the household balance.

Acceptance criteria:

  1. The head of household (the primary member) initiates redemptions on behalf of household members through the external loyalty interface.
  2. The system validates eligibility in real time.
  3. The system redeems points and transaction history is available in the ES Loyalty Console for each member, including the head of household.
  4. Payment is processed.
  5. Each member in the household receives payment.

User story 3: CSR checks member transaction history for payment verification​

As a Customer Service Representative (CSR), I want to query a loyalty member's transaction history for payout metadata so that I can verify whether the payout was successfully processed in Tipalti.

Acceptance criteria:

  1. The CSR can view Tipalti payment metadata for a member who requested payment (or for whom payment was requested).
  2. Payment status at time of submission, batch ID, and payment reference codes are visible.

User story 4: Member receives detailed message on redemption failure​

As a loyalty member performing a redemption, I want to receive appropriate messaging if the payout was not processed so that I can make the necessary corrections before attempting the redemption again.

Acceptance criteria:

Members interacting on the web app are presented with specific error messages for different failure types. The API response returned by ES Loyalty provides the specific error message or messages.

User story 5: CSR awards discretionary points to resolve payment issues​

As a CSR, I want to award discretionary points to resolve payment issues reported by loyalty members so that their account balances are correct.

Acceptance criteria:

  1. Issue a discretionary transaction with a reason code specific to remedying a payment issue.
  2. Discretionary transactions are created in ES Loyalty with the payment reason code.

User story 6: Member retrieves payment details​

As a loyalty member, I want to view transaction history details (including payment details) from my app or loyalty page so that I can retrieve payment details related to transactions where a payout was requested.

Acceptance criteria:

Member can view transaction details with payment information in the app.

tip

Need additional resources? Supporting documentation for this integration is available through your TSA. Reach out to them if you need reference materials beyond what's covered here.

Last updated on