Credential-less Federal Benefits Switches is a premium offering through which beneficiaries of participating government programs are able to easily update the bank account 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 confirm their legal first name, legal last name, and (partially masked) social security number. They must also attest that they are an eligible beneficiary entitled to receive the payment. 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. 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

To implement Federal Benefits Switches, you pass Pinwheel user PII when creating a Link token.

Prerequisites

Link SDK version 2.3

In order to enable Federal Benefits Switches, the Link SDK used in your application must be upgraded to version 2.3 or later. We recommend upgrading to the latest version for maximum conversion.

API and Webhook Version v2023-11-22.

You must upgrade your API and Webhook versions to v2023-11-22. This may be a breaking change as he direct_deposit_switch.added webhook event params.action is now optional. To determine any other changes needed to be made to update, the list of breaking changes can be found here. In order receive valid webhook events of Federal Benefits Switches, you must create a new webhook with version 2023-11-22 or greater. This can be done by using the Create Webhook endpoint. Old webhooks can be deleted using the Delete Webhook endpoint.

Pass 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 Federal Benefits Switches

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 Federal Benefits Switches are enabled for your account, they will automatically populate when a user selects an enabled government platform in search.

To use Federal Benefits Switches and PreMatch together (strongly recommended), send all end_user.platform_matching data. Using the social_security_number field to pass the full 9-digit Social Security Number is strongly recommended rather than the social_security_number_last_four.

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"
  ]
}

While it is not recommended, you can choose to populate only the following fields when creating a Link Token if your intent is to use the Federal Benefits Switches capability without PreMatch.

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"
  ]
}

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