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.

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

Note: 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):

1. 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 be processing. This denotes that the switch has been submitted and is currently being processed and checked for accuracy, fraud, etc. If unsuccessful, the outcome will be error or failure.
   1. You can expect government switches to be processed within 1 business day
2. 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 be sent. If unsuccessful, the outcome will be error or failure.

// 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.