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.
![](https://files.readme.io/6093e38-Sequence_Diagram_1.jpg)
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 inenabled 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.
Updated 26 days ago