Implement Earnings Stream

To implement Earnings Stream, you can subscribe to webhook events, create a Link token with the paystubs job, launch Link, and collect data.

Prerequisites

Link SDK version 2.4

In order to enable Earnings Stream, the Link SDK used in your application must be upgraded to version 2.4 or later. We recommend upgrading to the latest version for maximum conversion.

API and Webhook Version v2023-11-22

To use the latest functionality of Earnings Stream, you should upgrade to v2023-11-22. Breaking changes for each API version upgrade are listed in our breaking change list. Functionality of older versions can be found by using the API version dropdown in the top left corner of this page.

1. Subscribe to the webhook events

Subscribe to the following webhook event to receive an alert when the updated earnings stream becomes available or Monitoring detects a change to a user's Earnings Stream.

• earnings_stream.payouts.refreshed: Notifies you when information about the earnings stream is refreshed and updated. Specify this webhook in enabled events.

Register a webhook endpoint using Pinwheel's Create Webhook endpoint, as the following example illustrates.

POST /v1/webhooks
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "url": "https://your-domain.com/webhook_endpoint",
  "status": "ACTIVE",
  "enabled_events": ["earnings_stream.payouts.refreshed"]
}

⚙️

Development Tip

Use a tool like Webhook.site to see webhook events in real-time without writing any code. Once you've developed a webhook endpoint, use a tool like ngrok to run it on your local machine and receive webhook events.

2. Connect an account

Launch the Pinwheel Link that your customers can use to connect a new account. To initialize Pinwheel Link, your server-side code generates a short-lived Link token by sending a POST request to the /link_tokens endpoint. Link tokens are intended to be single-use and expire after 15 minutes. Your server must generate a new link token each time you want to launch Pinwheel Link.

Link tokens define your user experience and tell Pinwheel what jobs must be completed.

Provide an end_user_id and set paystubs in required_jobs when creating the Link Token to enable earnings stream. Earnings Stream is built on your User Model since it can leverage cross-account data.

See the Implementation Guide for additional customization parameters for Link.

POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
  "org_name": "YOUR APP NAME",
  "end_user_id": "my_user_12345",
  "required_jobs": ["paystubs"]
}

Pass the token from the response to one of the Link SDKs to launch a Link session inside your application.

⚙️

Development Tip

Test this flow without writing any code using the Console to create a Link Token and launch a Link session in the Dashboard.

3. Retrieve data

After you've subscribed to the webhook events, you receive earnings_stream.payouts.refreshed webhook events at your webhook endpoint in these instances:

• After your user connects an account with link or performs an on demand update
• Whenever monitoring detects a change to the underlying information in Earnings Stream.

The webhook event includes metadata about the Earnings Stream, indicating which components are available or unavailable. If unavailable, it includes an unavailable_reason summarizing why.

See Earnings Stream Webhook Events for further details.

{
    "event": "earnings_stream.payouts.refreshed",
    "event_id": "e9d5660b-52cc-4b66-adba-67eed17447fe",
    "payload": {
        "end_user_id": "my_user_12345",
        "updated_at": "2022-01-01T00:00:00+0000",
        "refreshed_at": "2022-01-02T00:00:00+0000",
        "availability": {
            "payouts_estimated": {"status": "available", "unavailable_reason": null}
        }
    }
}

Use end_user_id in the payload to query the get earnings stream payouts to fetch the most up-to-date payouts data. The data from disconnected accounts are excluded.

See the Get Earnings Stream Payout topic for a detailed breakdown of the schema and the Understand Payout Entities topic for a walkthrough of the different components.

4. Use the data

To estimate the size of someone’s next payout—for example, if you want to provide an Earned Wage Access cash advance to a user that you’d repay from their next direct deposit, select Payouts where status = estimated, then sum up net_pay.amount for all the earnings where confidence_score meets your requirements (for example,≥ 0.71). The confidence score is a decimal value from 0 to 1 that's generated using shifts, paystubs, and historical pay information to help you make an informed decision on how to use the earnings data.

Please contact [email protected] for access to our Dashboard.