Implement SelfID for Federal Benefits
SelfID for Federal Benefits is a premium offering through which beneficiaries of participating government programs are able to easily switch where they receive their payments.
Unlike Pinwheel’s standard Direct Deposit Switch product, in this scenario users do not need to know or input their username and password credentials for the Federal program or agency - improving conversion.
How It Works
User Experience
After a user searches for and selects an eligible Federal Benefits program in the Pinwheel Link modal, they are prompted to enter their legal first name, legal last name, and social security number. This is in lieu of requiring them to provide their username and password credentials. Once the user confirms their information, Pinwheel will submit their switch instructions to the selected Federal program or agency. Updates typically take effect in 1-2 payment cycles.
This feature is suitable for updating the direct deposit instructions of a beneficiary that is already enrolled in a given program, not for their initial registration and setup with the program. At this time only full allocations, not partial, are supported.
Supported Federal Government Benefits programs include:
- Social Security (including Retirement, Disability, Survivor, and Supplemental Security Income)
- Various Veterans benefits
- Reserve Education Assistance Program
- Civil Service Retirement
- Railroad Retirement
Implementation
There are two ways to implement SelfID for Federal Benefits: you may pass Pinwheel the key pieces of user PII when creating a Link token, or your users can type it in themselves after selecting the government agency they are paid by.
[Recommended] Option 1: Passing user information by Link Token
Like PreMatch, you can pass your users's PII when creating a Link token to maximize your user's conversion and minimize fraud risks. This implementation follows the same overall flow as our normal Deposit Switch and PreMatch implementations, so for brevity this guide only shows the deviations from that implementation.
Create a Link token for SelfID for Federal Benefits
To send user's data through the backend, populate the end_user.platform_matching
field when creating a Link token with Create Link Token . If this field is populated and SelfID for Federal Benefits are enabled for your account, they will automatically populate when a user selects an enabled government platform in search.
While all fields are optional, populating them will improve conversion.
Key in end_user.platform_matching | Type | Description |
---|---|---|
social_security_number (optional) | string | Full 9-digit social security number of the user. Required if social_security_last_four is omitted. Using full SSN will improve conversion. |
first_name (optional) | string | The user's first name. |
last_name (optional) | string | The user's last name. |
POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-Api-Secret: YOUR-API-SECRET
Pinwheel-Version: 2023-11-22
{
"org_name": "YOUR APP NAME",
"end_user_id": "my_user_12345",
"end_user": {
"platform_matching": {
"social_security_number": "123456789",
"first_name": "John",
"last_name": "Smith"
}
},
"allocation": {
"targets": [
{
"type": "checking",
"routing_number": "07464755",
"account_number": "193464372203"
}
]
},
"required_jobs": [
"direct_deposit_switch"
]
}
To use SelfID for Federal Benefits and PreMatch together, send all end_user.platform_matching
data together.
POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
X-Api-Secret: YOUR-API-SECRET
Pinwheel-Version: 2023-11-22
{
"org_name": "YOUR APP NAME",
"end_user_id": "my_user_12345",
"end_user": {
"platform_matching": {
"social_security_number": "123456789",
"mobile_phone_number": "0123456789",
"home_address_zip_code": "12345",
"first_name": "John",
"last_name": "Smith",
"date_of_birth": "1999-12-31",
"email": "[email protected]"
}
},
"allocation": {
"targets": [
{
"type": "checking",
"routing_number": "07464755",
"account_number": "193464372203"
}
]
},
"required_jobs": [
"direct_deposit_switch"
]
}
Option 2: Let users type in PII themselves
This path will get you up and running faster and does not require any additional technical work. However, it may lead to lower conversion. Please talk with your account manager to determine if this path makes sense for your organization.
Best Practices
Use end_user_id
when creating a Link token
end_user_id
when creating a Link tokenNote: this field is required for API version v2023-07-18
and above.
In the Link token you should provide an end_user_id
, which is your internal reference to a specific user. It will be used to determine whether a single person has made multiple switch attempts. More details can be found here.
POST /v1/link_tokens
Host: api.getpinwheel.com
Content-Type: application/json
x-api-secret: YOUR-API-SECRET
{
"org_name": "BankApp",
"required_jobs": [
"direct_deposit_switch"
],
"end_user_id": "myUser12345",
"allocation": {
"targets": [
{
"type": "checking",
"routing_number": "07464755",
"account_number": "193464372203"
}
]
},
"disable_direct_deposit_splitting": false
}
Responding to webhook events
After a switch is submitted, we will publish two (2) types of webhook events. You should update your handling of Pinwheel webhooks to account for the new job outcome types detailed below.
account.added
{
"event": "account.added",
"event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
"payload": {
"account_id": "03bbc20e-bc39-464a-b4dc-4b63ffb7213d",
"end_user_id": "myUser12345",
"link_token_id": "7c4ac4be-4a0e-4468-ab26-c42b249b233b",
"platform_id": "fce3eee0-285b-496f-9b36-30e976194736",
"platform_name": "Supplemental Security Income",
"created_at": "2021-01-12T02:36:01.287148+00:00",
"connected": false,
"monitoring_status": "unavailable",
}
}
direct_deposit_switch.added
If the direct deposit switch was submitted successfully, this event will be published twice, with two separate updates about the switch. The expected job outcomes are as follows (note the new job outcome types):
- Switch submission: the first
direct_deposit_switch.added
webhook event will be sent when the switch is submitted to Pinwheel. If successful, the outcome will beprocessing
. This denotes that the switch has been submitted and is currently being processed and checked for accuracy, fraud, etc. If unsuccessful, the outcome will beerror
orfailure
.- You can expect government switches to be processed within 1 business day
- Sending the switch to the government agency: the second
direct_deposit_switch.added
webhook event will be sent when the switch is submitted to the government agency. If successful, the outcome will besent
. If unsuccessful, the outcome will beerror
orfailure
.
// outcome = processing
{
"event": "direct_deposit_switch.added",
"event_id": "3477cc9-467e-41d2-9243-e56cc30a2ad7",
"payload": {
"id": "abc20d88-d681-4f9c-ba81-8c80f38d392a",
"account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
"end_user_id": "myUser12345",
"link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
"name": "direct_deposit_switch",
"timestamp": "2021-01-12T02:36:01.287148+00:00",
"outcome": "processing",
"params": {
"action": "full_switch"
}
}
}
//outcome = sent
{
"event": "direct_deposit_switch.added",
"event_id": "5a141122-4235-4fa1-bd76-0628573880b0",
"payload": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
"end_user_id": "myUser12345",
"link_token_id": "4787acbc-11cf-4db3-998c-5ea7c4feebcd",
"name": "direct_deposit_switch",
"timestamp": "2021-01-12T02:36:01.287148+00:00",
"outcome": "sent",
"params": {
"action": "full_switch"
}
}
}
Considerations
We do not yet support multiple accounts for Federal Government Benefits switching, so if you include multiple target accounts in your link token we will default to the first listed account.
Getting started
Please contact your Pinwheel Account Manager or [email protected] for pricing details and to go live.
Updated 7 days ago