Overview

DD Customers & Their Value

Green Dot Direct Deposit (DD) customers have shown greater engagement and provide more lifetime value (LTV) than non-DD customers. On average, Green Dot accounts enrolled with DD have ~11x lifetime value over accounts not enrolled with direct deposit.

While many banks and businesses offer a DD feature for their customers, the user experience for manual setup can often be difficult, time-consuming, and prone to user error.

Green Dot’s DD Switch

Green Dot’s Direct DD Switch feature helps partners simplify the DD enrollment process for account holders by letting them set up DD without leaving their banking app. With this integration, customers can conveniently log in to their employer or payroll provider account using their existing credentials and complete every step of their DD setup within the partner’s app. Those account holders will then enjoy a fast, secure, simplified experience that decreases the friction typically involved with manual DD enrollment, encouraging a more successful and continued engagement with the app.

Customer Experience & Flow

With this streamlined DD Switch process, the customer experience can be distilled to only four simple steps:

1. Without leaving their banking app, the customer can search for their employer or payroll provider from a comprehensive list of top employers, payroll companies, gig-worker platforms, federal agencies, and state unemployment agencies.
2. The customer will login using their company/agency credentials.
3. The customer determines how much of their paycheck to deposit per pay period.
4. The customer submits the request.

DD Switch Integration Guide & API Reference

If you are interested in learning more about integrating DD Switch, please continue to the Integration Guide below. For specific API details related to DD Switch, refer directly to the API Endpoints.

Integration Guide

Green Dot has integrated with a third-party DD switch provider using its Software Development Kit (SDK) for both Web and App. For Green Dot partners to offer this DD Switch feature to their customers, partners only need to integrate with the SDK, as Green Dot will provide the access token for SDK integration and handle all the backend calls (webhooks, switch attempts, partner notifications, etc.).

DD Switch Flowchart

Integration Steps

1. Partner requests the SDK key from Green Dot through the Create Switch Attempt API found in the API Reference section.

2. Partner creates their own User Interface (UI) surrounding and leading into the SDK experience.

   1. To provide an example of what the experience can look like before invoking the SDK, the following are screenshots of Green Dot’s GO2bank Direct deposit UI and user flow. Partners can build their own UI and user flow to provide a similar experience.
   

📘

Green Dot can also customize in-app messaging shown in the SDK experience.

3. Partner directly invokes the SDK. Please refer to the third-party SDK documentation for reference material and code samples.
4. Partner’s client app calls the Update Switch Attempt API to upload the status of the SDK response.
5. Green Dot listens to SDK Webhooks and sends them to the partner via webhooks or notifications based on the partner’s configuration.
6. Green Dot stores all switch attempts and allows partners to view them through the Get all Switch Attempts API endpoint.
7. Green Dot will send Direct Deposit Switch status information to the partner.
   1. Partner receives the webhook and notifies their customers of switch status (through push notification, email, SMS, etc).
   2. Partner’s customer will receive notification switch status, if configured to receive notification directly from Green Dot.
8. Green Dot provides fallback options to help customers complete their DD setup, when a DD Switch fails.
   1. Customers can download a Direct Deposit form pre-filled with their account information, which can be submitted to their employer as an alternative way to set up DD in the event of a failed switch.
   2. Green Dot can provide instructions on manual setup by using customer’s account and routing numbers information for those who can't use DD Switch or where DD Switch fails (optional- this service must be opted into).

Direct Deposit Switch API Endpoints

Required Headers

Route Parameters

Common Objects

Switch Attempt

Response Details

Generate Manual Form

This API is used to generate a direct deposit request form with the user’s name, address, and account number prefilled. The end user will download, print, and submit it to their payroll provider.

API Call Structure

POST /programs/{programCode}/accounts/{accountIdentifier}/directdeposit/manualform

Request Body

{
  "fullName": "string",
  "accountNumber": "string",
  "routingNumber": "string",
  "bankName": "string",
  "addressLine1": "string",
  "addressLine2": "string"
}

Request Parameters

Response Body

{
 "output": "string",
 "responseDetails": [
  {
   "code": 0,
   "subCode": 0,
   "description": "string",
   "url": "string"
  }
 ]
}

Response Parameters

Create New Switch Attempt

This API generates an access token to load the SDK and starts tracking the user’s progress through the setup flow.

API Call Structure

POST /programs/{programCode}/accounts/{accountIdentifier}/directdeposit/switches

Response Body

{
 "vendorToken": "string",
 "switchId": "string",
 "vendorName": "string",
 "responseDetails": [
  {
   "code": 0,
   "subCode": 0,
   "description": "string",
   "url": "string"
  }
 ]
}

Response Parameters

Get All Switch Attempts

This API returns details about each time a user attempted to set up direct deposit using the automated flow.

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/directdeposit/switches

Response Body

{
 "accountData": {
  "id": "string",
  "referenceNumber": "string",
  "client": "string",
  "latestSwitch": {
   "referenceNumber": "string",
   "id": "string",
   "vendor": "string",
   "vendorReference": "string",
   "amount": "string",
   "amountType": "string",
   "status": "string",
   "statusReason": "string",
   "lastEventDateUtc": "2023-06-15T22:19:24.413Z",
   "depositor": "string",
   "eventIds": [
    "string"
   ]
  },
  "switchIds": [
   "string"
  ]
 },
 "switchAttempts": [
  {
   "referenceNumber": "string",
   "id": "string",
   "vendor": "string",
   "vendorReference": "string",
   "amount": "string",
   "amountType": "string",
   "status": "string",
   "statusReason": "string",
   "lastEventDateUtc": "2023-06-15T22:19:24.413Z",
   "depositor": "string",
   "eventIds": [
    "string"
   ]
  }
 ],
 "responseDetails": [
  {
   "code": 0,
   "subCode": 0,
   "description": "string",
   "url": "string"
  }
 ]
}

Response Parameters

Update Switch Attempt

This API allows a switch attempt to be updated with a new status or additional details.

API Call Structure

PATCH /programs/{programCode}/accounts/{accountIdentifier}/directdeposit/switches/{switchId}

Request Body

{
 "patchObj":
 {
 "amount": "string",
 "amountType": "string",
 "status": "string",
 "statusReason": "string",
 "depositor": "string"
 }
}

Request Parameters

Note: Valid statuses for partners to send are “Submitted” when the user completes the vendor flow, and “Aborted” when a user abandons the vendor flow. Transitioning to these states is not required and will not affect downstream processing.

Response Body

{
 "referenceNumber": "string",
 "id": "string",
 "vendor": "string",
 "vendorReference": "string",
 "amount": "string",
 "amountType": "string",
 "status": "string",
 "statusReason": "string",
 "lastEventDateUtc": "2023-06-15T22:37:55.510Z",
 "depositor": "string",
 "responseDetails": [
  {
   "code": 0,
   "subCode": 0,
   "description": "string",
   "url": "string"
  }
 ]
}

Response Parameters

Get Latest Switch Attempt

This API returns details for the most recent time a user attempted to set up direct deposit using the automated flow.

API Call Structure

GET /programs/{programCode}/accounts/{accountIdentifier}/directdeposit/switches/latest

Response Body

{
 "referenceNumber": "string",
 "id": "string",
 "vendor": "string",
 "vendorReference": "string",
 "amount": "string",
 "amountType": "string",
 "status": "string",
 "statusReason": "string",
 "lastEventDateUtc": "2023-06-15T22:37:55.510Z",
 "depositor": "string",
 "responseDetails": [
  {
   "code": 0,
   "subCode": 0,
   "description": "string",
   "url": "string"
  }
 ]
}

Response Parameters

Supported Deposit Amount Types & Statuses

Deposit Amount Types (as supported by the employer or payroll provider)

• All
• Amount
• Percent

Statuses

• Started
• Submitted
• Aborted
• Failed
• Completed
• Manual