Tremendous for Platforms

Tremendous for Platforms lets you issue payouts on behalf of your customers while staying out of the flow of funds. Onboard your customers seamlessly onto Tremendous and give them access to global payouts, all while staying compliant and maintaining an on-brand user experience.

Who this is for

Consider Tremendous for Platforms if both of the following are true:

Your organization issues payouts on behalf of your customers
Your organization does not wish to be in the flow of funds. Meaning that your customers will fund the payouts directly.

Example use cases include:

A survey platform that wants to build embedded payouts to survey participants, without handling client funds themselves
A referral marketing platform that wants to integrate referral payouts for its customers without obtaining or storing any payment data

The best way to determine whether Tremendous for Platforms is right for you is to contact our team - [email protected]. We will also need to enable this feature for your both your sandbox and production accounts.

How it works

With Tremendous for Platforms, your customers can create a Tremendous account, complete onboarding, and start sending payouts — all without leaving your product. Here's the typical flow:

Generate an onboarding link Create a unique link that directs your customers to Tremendous to complete onboarding.
Customer onboarding Your customers fill out KYB (Know Your Business) and compliance forms, then add a funding source to their account.
Receive API credentials Once onboarding is complete and the organization is approved, you’ll receive an OAuth token tied to that customer. You can use this token to manage the customer's balance and issue payouts on their behalf.
Provide ongoing access If a customer needs to update payment information, review balances, or see their transaction history, you can request a pre-authenticated URL via API. This takes them directly to their Tremendous dashboard.

Concepts

Features

Tremendous for Platforms consists of 3 separate features:

An onboarding flow. You’ll generate a custom onboarding URL for each new customer you want to enroll in Tremendous for Platforms.
Programmatic access to a customer’s account on Tremendous. You’ll receive an OAuth Access Token that allows you to issue API calls on behalf of the account created by your customer, letting send rewards or read a transaction history.
An embedded dashboard. If your customer wants to update their payment methods or access a visual transaction history, you can generate a URL that allows them to perform these actions without logging in.

Authentication

You’ll use two forms of authentication to get started.

OAuth application. You’ll use the OAuth client ID and OAuth secret to generate OAuth access tokens for this client.
API key. This is used to set up and verify signatures of webhooks.

Resources

Under the hood, there are two core resources within Tremendous for Platforms:

Connected organization. Represents a customer on your application– a team or company who wishes to issue payouts.
Connected organization member. Represents a “user” of each customer. This is an individual with an email address that likely is employed at the customer.

Steps to integrate

We recommend starting with a sandbox account to test the flow. Once ready, you can register a new developer app in your production account.

Obtaining credentials

Log into your Tremendous account.
In the left navigation menu, access Team settings → Developers. You’ll need to be an admin in order to access this.
In the "Developer apps" section, click "Register app" and follow the steps in the modal.
Note the client ID, client secret, and redirect URI.

Setting up webhooks

You’ll want to set up a webhook that will notify you of account-related events.

curl --request POST \
     --url https://testflight.tremendous.com/api/v2/webhooks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR-API-KEY' \
     --header 'content-type: application/json' \
     --data '{"url": "YOUR_ENDPOINT_TO_PROCESS_WEBHOOKS_HERE"}'

Onboarding accounts

To onboard a new account to send payouts on Tremendous, you’ll need to have them complete an onboarding form.

In this form, they’ll perform three key actions

Provide business information required for compliance review
Agree to Tremendous’ T&Cs
Add a payment method and fund their account

To onboard a new customer, you’ll need to do the following:

Create the “connected organization” that represents the customer in your app that wishes to send payments

curl --url 'https://testflight.tremendous.com/api/v2/connected_organizations' \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '{"client_id": "YOUR-OAUTH-CLIENT-ID"}'

Create the “connected organization member” that represents the individual user who is signed into your application, and will be performing onboarding actions.

curl --url 'https://testflight.tremendous.com/api/v2/connected_organization_members' \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '
     {
        "connected_organization_id": "CONNECTED-ORGANIZATION-ID-RETURNED-IN-PREVIOUS-STEP",
        "external_email": "USER-NAME",
        "external_name": "USER-EMAIL"
     }
     '

Create a session URL for that user, which provides you the URL that you will redirect this individual user to. You’ll then redirect your user to this URL where they will complete onboarding.

curl --url 'https://testflight.tremendous.com/api/v2/connected_organization_members/CONNECTED-ORGANIZATION-MEMBER-SESSION-ID-FROM-PREVIOUS-STEP/sessions' \
     --header 'Authorization: Bearer YOUR-API-KEY' \
     --header 'Content-Type: application/json' \
     --data '
     {
        "return_url": "WHERE-TREMENDOUS-SHOULD-REDIRECT-USER-TO-ON-COMPLETION"
     }
     '

You should store all the IDs returned in the steps above on your persistent storage. You’ll need those IDs to query the data for each one of those resources, or to generate new session URLs at a later date. Session URLs should not be stored as they are temporary only. They should be generated on each access.

Listening for onboarding completion

When a user finishes onboarding, they’ll be returned to the return_url included in the session object.

At the same time, you’ll receive a webhook notification (CONNECTED_ORGANIZATIONS.REGISTERED) from Tremendous.

This webhook’s payload has the same data as the API’s connected organization resource.

Listening for connected organizations being approved

Tremendous’ compliance team reviews newly created organizations. You’ll receive a webhook notification CONNECTED_ORGANIZATIONS.STATUS.APPROVED). You’ll need to wait for the CONNECTED_ORGANIZATIONS.OAUTH.GRANTED event to get the OAuth grant token that allows you to fetch the first access and refresh tokens.

Listening for connected organizations being rejected

Tremendous’ compliance team may reject an organization upon review. You’ll receive a webhook notification CONNECTED_ORGANIZATIONS.STATUS.REJECTED if that happens.

This webhook’s payload has the same data as the API’s connected organization resource.

Listening for OAuth grant token

Once the organization is approved, you’ll receive a webhook notification CONNECTED_ORGANIZATIONS.OAUTH.GRANTED with the OAuth grant token that allows you to fetch the first access and refresh tokens. These are the tokens that will allow you to make API calls on behalf of the organization. This webhook’s payload has the same data as the API’s connected organization resource, with an additional oauth_code code field. To finish the OAuth setup for that organization, use that code and follow the instructions in the OAuth integration guide from step 4:

curl --url 'https://testflight.tremendous.com/oauth/token' \
     --header 'Content-Type: application/json' \
     --data '
{
  "client_id": "YOUR-APPS-CLIENT-ID",
  "client_secret": "YOUR-APPS-CLIENT-SECRET",
  "redirect_uri": "https://www.example.com/oauth/callback",
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION-CODE-RECEIVED-IN-WEBHOOK"
}
'

Sending rewards on behalf of your customers

At this point, you’ll have the ability to perform all actions on your customer’s Tremendous account under the hood. You’ll simply make calls to our REST API using the OAuth Access Token associated with the customer.

Authenticating your API calls with an OAuth token
Checking funding sources
Setting up custom branding
Sending a reward

Sample app

A complete sample app is available on GitHub. It demonstrates how to integrate with Tremendous for Platforms.