Implement Credential-less Direct Deposit Switch for Federal Government Benefits
Credential-less Direct Deposit Switch for Federal Government Benefits is a premium offering through which beneficiaries of participating Federal 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 Government 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
For the best experience, the following implementation changes are recommended (but not required).
Recommendation 1: provide end_user_id
end_user_id
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. Also note that 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.
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
}
Recommendation 2: responding to webhook events
After a switch is submitted, we will publish 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"
}
}
}
Getting started
Enabling this feature for your users does not require any incremental technical effort beyond implementing Direct Deposit Switch and considering the two recommendations above. However, you will need to contact your Pinwheel Account Manager or [email protected] for pricing details and to go live.
Updated 5 months ago