# Deposit Switch
source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md
Deposit Switch is a seamless, automated solution that allows users to effortlessly switch their direct deposits from one bank account to another. Designed with ease of use and efficiency in mind, this service simplifies the process of managing direct deposits, reducing administrative burdens, enhancing user satisfaction, and driving account primacy.
With Deposit Switch, you can:
1. Trigger recurring account funding by inviting your customers to instantly update their direct deposit information.
2. Provide a seamless, easy to use switching journey embedded in the account onboarding process.
3. Let your customers allocate their full or partial paycheck to an account at your bank.
Warning: This product may not be used for purposes subject to the Fair Credit Reporting Act.
## Use Cases {#use-cases}
* **Fund new accounts** such as retail bank accounts and digital wallets by enabling direct payroll deposit. Deposit switch enables direct deposit for any type of accounts: checking, savings, retirement, etc. This can be used either during an account opening flow, or after onboarding is complete.
* **Fund existing accounts** by switching payroll deposits from incumbent banks to our customer/FI. This could be to a new account not yet linked to Open Finance .
## How It Works {#how-it-works}
Customers will use your app to launch a Connect Transfer session to establish a connection enabling the direct deposit switch with their payroll provider. The Connect Transfer experience differs from the regular Data Connect experience since it allows end users to login and authenticate with payroll providers (note we use Atomic, a partner of Mastercard, for parts of the user experience).
Diagram deposit-switch
You must have already created a [customer](https://developer.mastercard.com/open-finance-us/documentation/access-and-config/customers/index.md) record using your partnerId to use this service. Note that the endpoints require [authentication](https://developer.mastercard.com/open-finance-us/documentation/access-and-config/auth/index.md).
Tip: For testing in Sandbox with [Test Customers](https://developer.mastercard.com/open-finance-us/documentation/access-and-config/customers/index.md#test-customers), note that the final screen in the Connect Transfer flow will prompt the user to "Return to Partner App" during Sandbox testing. When you move to Production, the screen will instead use the application name associated with your experience ID, if provided.
### Integration Options {#integration-options}
You can either generate a Deposit Switch Connect Transfer URL and embed the experience in an iframe (or secure web container) using the [Data Connect Web SDK](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#using-deposit-switch-with-the-connect-web-sdk), or for mobile you can generate the URL and pass it to the [Connect Transfer mobile SDKs](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/connect-transfer/index.md) that we provide.
The Connect Transfer mobile SDKs provide iOS, Android and React Native versions of the Atomic user experience, which is not supported by the regular Data Connect mobile SDKs. The Connect Transfer SDKs also support TrueAuth authentication of the end user with the payroll provider, rather than OAuth.
## Generate a Connect Transfer URL {#generate-a-connect-transfer-url}
In order to allow customers to be able to set up deposit switches, you will need to offer them a specific Data Connect user experience which allows them to set up the switch. This user experience will allow them to, for example, search for their payroll provider or employer, login to the provider with their credentials and select a direct deposit allocation. This is different from the usual Data Connect experience which just allows customers to connect bank accounts.
API Reference: `POST /connect/generate/transfer/deposit-switch`
Note that the Connect Transfer experience uses Atomic, a partner of Mastercard, for parts of the user experience.
See the [Experience Design Guide section on Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/experience-design-guide/deposit-switch/index.md) for more details of the user flow.
Note: This endpoint now supports passing an `external` object for in-branch deposit switching. See [Deposit Switch In-Branch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#deposit-switch-in-branch) on this page.
## Get Deposit Switches by Customer ID {#get-deposit-switches-by-customer-id}
Retrieve a list of the Deposit Switches that are defined for a given customer ID.
For each deposit switch the ID, status, date of creation, and if applicable any status is returned.
API Reference: `GET /transfer/customers/{customer_id}/deposit-switches`
## Get Deposit Switches by External ID {#get-deposit-switches-by-external-id}
Retrieve a list of the Deposit Switches that are defined for a given external ID,
which is your identifier for the employee or branch associated with an In-Branch
switch. See [Deposit Switch In-Branch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#deposit-switch-in-branch) on this page.
For each deposit switch the ID, status, date of creation, and if applicable any status is returned.
API Reference: `GET /transfer/externals/{external_id}/deposit-switches`
## Get Deposit Switch Details {#get-deposit-switch-details}
Retrieve the details of a specific deposit switch, once you know the ID of the switch.
A successful response will include details of the status of the switch and also details of the provider, the bank / FI, and last four digits of the customer's account number for the account which will be credited.
API Reference: `GET /transfer/customers/{customer_id}/deposit-switches/{switch_id}`
## Connect Transfer Webhooks {#connect-transfer-webhooks}
The following [Data Connect webhook events](https://developer.mastercard.com/open-finance-us/documentation/webhooks/webhooks-connect/webhooks-events-connect/index.md) can be generated during the Connect Transfer flow:
* `ping` - Sent when Connect Transfer begins (to check that your webhook receiver is responding). Your receiver must return a 200 series or the Generate Connect Transfer URL call fails.
* `started` - Sent when the Connect Transfer application is loaded and the landing web page is displayed.
* `depositSwitchUpdate` - Sent when the payroll flow is used to add or update a deposit switch. This event applies only to Deposit Switch (details below).
* `done` - Sent when the deposit switch user flow ends and control is returned to the partner application.
#### depositSwitchUpdate {#depositswitchupdate}
| Name | Data Connect Support | Supported Processes | Description |
|---------------------|----------------------|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| depositSwitchUpdate | Connect Transfer | Payroll Deposit Switch | Sent during the Connect Transfer flow (for deposit switching). The `switchId` field can be used later to obtain further details of a specific switch. The `switchStatus` field indicates the current state of progress (e.g., "processing", "completed", "failed") The `failureReason` field is only used in case of error, to indicate the problem encountered (e.g., "account-unusable", "bad credentials", etc.). The Connect Transfer user experience will show a suitable message to the end user so these `failureReason` values are just for information. |
* JSON
```JSON
{
"customerId": "7020614888",
"eventType": "depositSwitchUpdate",
"eventId": "1728492399880-aa3fc8a4c7a0a5441f44ca2b",
"payload": {
"switchId": "6706b36911c92b37335b0287",
"switchStatus": "completed",
"createdDate": "2024-10-09T16:46:33Z",
"authenticated": true,
"provider": {
"id": "5f0f23d0acd6870007be180d",
"name": "Amazon Fulfillment"
},
"distributions": [
{
"type": "total",
"bankIdentifier": "110000000",
"accountNumberEndsWith": "3963"
}
]
}
}
```
The `depositSwitchUpdate` JSON message contains details within the `payload` field which relate to the specific Deposit Switch that the end user is setting up. In addition to the switch ID and the status (was the switch set up successfully or not), you can also see who the provider is, whether the user authenticated, and the `distributions` field contains details of the switch such as whether the switch is for the total amount, a percentage, or a fixed amount (which will be specified). See the [Get Deposit Switch Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#get-deposit-switch-details) endpoint for descriptions of the data returned. You can use this endpoint to obtain the details of any switch at a later stage.
## How to Test Deposit Switch {#how-to-test-deposit-switch}
To test the Deposit Switch functionality, follow these steps:
1. Set up a suitable webhook listener so you can receive webhook events.
2. Make sure you already have a suitable partner ID and test customer which has at least one bank account connected (see the Quick Start Guide).
3. Generate a suitable URL for testing the user flow by calling Connect Transfer URL. You will need to provide details of your webhook listener and your partner ID, the customer ID and details of the bank account which the end user will be transferring a direct deposit to.
4. Load the Connect Transfer URL in a browser and agree to the Terms and Conditions and Privacy Policy by clicking *Next*.
5. This will then show the Atomic user experience where you can select an employer or payroll provider.
### Testing details {#testing-details}
When testing the Deposit Switch flow, you can use the following usernames to test various scenarios. Enter the username shown for any employer or payroll provider (you can use any password). If an email address is required for authentication, append `@example.com` to the username.
#### Successful operation {#successful-operation}
Test where the user's credentials are correct and the task completes. When answering MFA questions, any answer will be accepted.
| Username | Phone Number | Description |
|-------------------|----------------|--------------------------------------------------------------------|
| test-good | (555) 555-0100 | Test a successful operation. |
| test-code-mfa | (555) 555-0101 | Test an authentication that includes a device code based MFA flow. |
| test-push-mfa | (555) 555-0102 | Test an authentication that simulates push-based MFA. |
| test-question-mfa | (555) 555-0103 | Test an authentication that simulates question-based MFA. |
#### Error establishing connection {#error-establishing-connection}
Test where the user encounters an issue connecting to the third-party system.
| Username | Phone Number | Description |
|-------------------------|----------------|-----------------------------------------------------------------------------------------------------------------------------------|
| test-system-unavailable | (555) 555-0104 | Test the user experience during a third-party system outage. |
| test-unknown-failure | (555) 555-0105 | Test the user experience when there is an unexpected error. |
| test-session-timeout | (555) 555-0106 | Test the user experience when the auth session has timed out. |
| test-connection-error | (555) 555-0107 | Test the user experience when there is a connection error caused by a network failure. |
| test-high-latency | (555) 555-0108 | Test the flow which occurs when there is high latency communicating with backend systems. |
| test-post-auth-delay | (555) 555-0109 | Test the flow when there is a post-auth delay happening. This may occur due to an unanticipated change in the third-party system. |
| test-failure | (555) 555-0110 | Test a failure that occurs after a successful authentication. |
#### Payroll system configuration {#payroll-system-configuration}
Test where the user encounters an issue with their payroll system configuration or access.
| Username | Phone Number | Description |
|-----------------------------------|----------------|--------------------------------------------------------------------------------------------|
| test-distribution-not-supported | (555) 555-0111 | Test a user who enters an unsupported deposit amount. |
| test-routing-number-not-supported | (555) 555-0112 | Test a user whose payroll system rejects the routing number of the target deposit account. |
| test-product-not-supported | (555) 555-0113 | Test a user whose payroll system does not allow the operation. |
#### User issue {#user-issue}
Test where there is an error that occurs due to an action of the user.
| Username | Phone Number | Description |
|-------------------------------|----------------|-------------------------------------------------------------------------------|
| test-bad | (555) 555-0114 | Test an unsuccessful authentication. |
| test-lockout | (555) 555-0115 | Test a user who has been locked out of their account. |
| test-account-unusable | (555) 555-0116 | Test a user whose payroll account rejects the target deposit account. |
| test-enrolled-in-paycard | (555) 555-0117 | Test a user enrolled in a paycard, which prevents payment via direct deposit. |
| test-expired | (555) 555-0118 | Test a user whose payroll password has expired. |
| test-transaction-pending | (555) 555-0119 | Test a user who already has a direct deposit change in progress. |
| test-account-setup-incomplete | (555) 555-0120 | Test a user who has not fully onboarded to their employee payroll system. |
| test-work-status-terminated | (555) 555-0121 | Test a user who is not an active employee in the payroll system. |
## Using Deposit Switch with the Data Connect Web SDK {#using-deposit-switch-with-the-data-connect-web-sdk}
You can use Connect Transfer for Deposit Switch with the [Data Connect Web SDK](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/index.md).
This usage is very similar to using the Web SDK with for Data Connect Full, except there are some additional [Connect Transfer specific user events](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#data-connect-transfer-user-events).
The Web SDK provides the following events which you must provide handlers for:
| Event | Description |
|------------|-------------------------------------------------------------------------|
| `onDone` | Sent when the user successfully completes the Data Connect application. |
| `OnCancel` | Sent when the user cancels the Data Connect application. |
| `onError` | Sent when there is an error during the Data Connect application. |
Optionally, you can also provide handlers for the following events:
| Event | Description |
|-----------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `onLoad` | Sent when the Data Connect web page is loaded and ready to display. |
| `onRoute` | Sent when the user navigates to a new route or screen in Data Connect. |
| `onUser` | Sent when a user performs an action. User events provide visibility into what action a user could take within the Data Connect application. |
For more details on handling Web SDK events in general, see [Data Connect Web SDK Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-websdk-events/index.md) in the main Data Connect documentation (note that the optional `onUrl` event described there is not relevant for Deposit Switch).
The user events which are relevant to Connect Transfer and Deposit Switch are described below.
### Connect Transfer User Events {#connect-transfer-user-events}
The following user event messages can be received by your implementation of the `onUser()` listener / callback.
* InitializeTransfer
* TermsAccepted
* InitializeDepositSwitch
* SearchPayrollProvider
* SelectPayrollProvider
* ExternalLink
* SubmitCredentials
* ChangeDefaultAllocation
* SubmitAllocation
* TaskCompleted
* Unauthorized
* End
#### InitializeTransfer {#initializetransfer}
This event message is sent to `onUser()` when the connect opens within WebSDK. For example:
{
action = InitializeTransfer;
customerId = CUSTOMER_ID;
partnerId = PARTNER_ID;
sessionId = SESSION_ID;
timestamp = 1737092848275;
ttl = 1737179248275;
type = transferDepositSwitch;
}
#### TermsAccepted {#termsaccepted}
This event message is sent to `onUser()` when the user accepts the terms of use on the Data Connect Landing Screen within WebSDK. For example:
{
action = TermsAccepted;
}
#### InitializeDepositSwitch {#initializedepositswitch}
This event message is sent to `onUser()` when the user initiates a Transfer Session. For example:
{
action = InitializeDepositSwitch;
product = 'deposit'
}
#### Search Payroll Provider {#search-payroll-provider}
This event message is sent to `onUser()` when the user searches by company. For example:
{
action = SearchPayrollProvider;
searchTerm = "home depot";
}
#### Select Payroll Provider {#select-payroll-provider}
This event message is sent to `onUser()` when the user selects a provider from the Search by Company page. For example:
{
action = SelectPayrollProvider;
payrollProvider = Workday;
}
#### External Login Recovery {#external-login-recovery}
This event message is sent to `onUser()` when user clicks the external login recovery link from the login help page. For example:
{
action = ExternalLink;
buttonName = "Login Help ";
}
#### Submit Credentials {#submit-credentials}
This event message is sent to `onUser()` when user clicks the button to start authentication. For example:
{
action = SubmitCredentials;
inputType = username;
}
#### Change Default Allocation {#change-default-allocation}
This event message is sent to onUser() when user clicks Continue from the Percentage Deposit Amount page. For example:
{
action = ChangeDefaultAllocation;
depositAllocation = 222;
depositOption = fixed;
}
#### SubmitAllocation {#submitallocation}
This event message is sent to `onUser()` when user clicks Continue from the Fixed Deposit Amount page. For example:
{
action = SubmitAllocation;
depositAllocation = 222;
depositOption = fixed;
}
#### TaskCompleted {#taskcompleted}
This event message is sent to `onUser()` when user views the task completed page. For example:
{
action = TaskCompleted;
status = completed;
}
#### Unauthorized {#unauthorized}
This event message is sent to `onUser()` when the user's Atomic session is unauthorized because of an expired or invalid Atomic Token. For example:
{
action = Unauthorized;
expired = false;
}
#### End {#end}
This event message is sent to `onUser()` when the Connect Transfer flow ends, and contains details about the Connect Transfer flow which will not be provided by the `onDone()` event.
{
action = End;
code = 200;
company = {
"_id" = COMPANY_ID;
branding = {
color = "#F96302";
logo = {
url = "https://cdn-public.atomicfi.com/b2ad42c5-1348-4bfd-a19d-250583791e8c.png";
};
};
name = "The Home Depot";
};
customerId = CUSTOMER_ID;
distributionAmount = 222;
distributionType = fixed;
identifier = CUSTOMER_ID;
partnerId = PARTNER_ID;
reason = complete;
sessionId = SESSION_ID;
taskId = 6789ef56fe459a9cc2fafc43;
taskWorkflowId = 6789ef56fe459a9cc2fafc4a;
timestamp = 1737092848275;
ttl = 1737179248275;
type = transferDepositSwitch;
}
## Deposit Switch In-Branch {#deposit-switch-in-branch}
Note: This feature is currently in beta. Contact your sales representative or account manager to learn more.
Deposit Switch In-Branch enables you to deliver a Direct Deposit
Switch URL to customers, with tracking of the
branch or employee associated with the switch, and the link delivery
method.
To support In-Branch, [Generate a Connect Transfer URL for Deposit Switch](https://developer.mastercard.com/open-finance-us/documentation/api-reference/index.md#GenerateTransferDepositSwitchUrl) has
a new `external` parameter object with the following fields:
* `id` -- your identifier for the branch or employee initiating the switch
(type: string).
* `context` -- describes how you are using the Mastercard Data Connect
link. This can be one of four values: `EMAIL`, `SMS`, `WEB`, or `MOBILE`
(type: string).
Both fields must be provided if your request includes `external`.
API Reference: `POST /connect/generate/transfer/deposit-switch`
* Use a separate experience ID for each channel (web, mobile and in-branch).
* Use a separate partner ID only if you need billing to be separated by channel.
You can search for completed deposit switches by external ID with the following endpoint:
API Reference: `GET /transfer/externals/{external_id}/deposit-switches`
This endpoint supports retrieving switch records and statuses within a 31-day window.
There are three options for integrating In-Branch:
* [Integration with Mobile Links](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#in-branch-integration-with-mobile-links) (recommended)
* [Integration with a Link to Your Site](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#in-branch-integration-with-a-link-to-your-site)
* [Integration with a Data Connect Link](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#in-branch-integration-with-a-data-connect-link)
### In-Branch Integration with Mobile Links {#in-branch-integration-with-mobile-links}
We recommend using In-Branch URLs by linking into your mobile app instead
of modifying API flows, using a
[universal link (iOS)](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/ios/ios-sdk/index.md#app-to-app-support)
or an [app link (Android)](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/android/android-sdk/index.md#app-to-app-support).
This provides the best user experience and success rate due to the ability to
use TrueAuth on-device authentication, and provides a compelling reason for
new customers to download your app.
* **Increased Conversion Rates**: Financial institutions using this strategy observe a significant increase in completed user journeys by encouraging users to download and engage with the mobile app, rather than directing them straight to a deposit setup experience outside of the mobile app.
* **Higher Success Rates and Mobile App Downloads**: Deep linking users into the app drives the highest success rates with availability of on-device authentication (TrueAuth) that you can successfully leverage via the Mastercard Direct Deposit functionality on mobile SDKs as a key value-add and a compelling reason for new customers to download the app.
* **Account Opening Engagement**: Success is largely driven by strong account opening incentives, competition, and educational efforts within branches. This on-the-ground engagement proves critical to driving deposit switch completion rates in the mobile app.
* **Customer Behaviors**: Data shows that most new account holders are not ready to commit to complete a direct deposit switch immediately at the branch. On average, direct deposit setup happens about two weeks after account opening. This delay is often due to customers needing time to unwind existing financial obligations (for example, recurring payments, previous direct deposits) from their old accounts before switching.
* **No Additional Training**: Branch staff do not require additional upskilling or training to support the use of deposit switching tools via the In-Branch channel. The platform is designed to be intuitive and seamlessly integrated into existing workflows, ensuring minimal disruption and faster adoption.
### In-Branch Integration with a Link to Your Site {#in-branch-integration-with-a-link-to-your-site}
In this scenario, when a user clicks on the link in an email/SMS, they are
redirected to a page on a website you control. This page loads the
Connect Transfer URL using the Data Connect Web SDK.
#### Event Notifications {#event-notifications}
* If you have integrated with the Web SDK, your app can listen to
user events as described in the Data Connect documentation:
* [Web SDK Callback Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/web-sdk/sdk/index.md#callback-events)
* [Connect User Events](https://developer.mastercard.com/open-finance-us/documentation/connect/integrating/sdk/events/connect-user-events/index.md)
Diagram standard-auth-web-only-sdk
### In-Branch Integration with a Data Connect Link {#in-branch-integration-with-a-data-connect-link}
In this scenario, you need to pass the following additional parameters
while generating the Connect Transfer URL:
* `redirectUri`-- address on a site you control where Data Connect redirects once the user flow is completed.
* `webhook` -- endpoint where you want to receive notifications from Data Connect Server.
When the user clicks on the link in the email/SMS, they are redirected to a
domain/page owned by Finicity, a Mastercard company (for example,
`connect2.finicity.com/`).
On completion of the flow, the user is redirected to your domain as
specified by the `redirectUri` value.
#### Event Notifications {#event-notifications-1}
* The `redirectUri` includes `code` and `reason` in query params which
you can read to indicate if the flow was completed successfully.
* The Mastercard Data Connect Server sends [Connect Transfer Webhook
Events](https://developer.mastercard.com/open-finance-us/documentation/products/pay/switch/deposit-switch/index.md#connect-transfer-webhooks).
Diagram standard-auth-web-non-sdk