User experience


Paycheck-linked loans product (product=pll) can be useful for deducting loan payment directly from a paycheck.

Citadel's Paycheck-linked loans product allows your users to repay loans by redirecting a specified dollar amount from their pay check to your bank account.

Paycheck Linked Loans requires routing number, account number, user-friendly bank name, account type (checking or savings), deposit type and deposit amount to initiate Citadel Bridge.

User flow

We recommend to initiate Citadel Bridge only after you confirmed that we have MappingMapping - a persistent link between employer and payroll provider. and a partial dollar switch available for the employer.

When you have information about employer, you can use Search mapped companies endpoint to find company_mapping_id and skip employer search step.


We recommend embedding typeahead search in your application to improve number of mapped companies.

Reach out to [email protected] for suggested UX and copy.

Successful connection

Show successful status and let user close the Bridge right after login (takes 5-10s on average). You would need to subscribe to Webhooks or poll Citadel's backend API to check the status of the data readiness.


The best practice is wait only for the login to succeed and send a notification to the user when their account was successfully switched.

Unsuccessful connection

If user was not able to connect their account, best practice is to present an alternative way of switching direct deposit by showing a manual form or another method.

User education

Citadel Bridge is a new way to switch direct deposit so majority of users connect their payroll account for the first time. To increase conversion rates we recommend educating your users about Citadel Bridge by explaining benefits and setting the right context before initializing Citadel Bridge.

Your app

Before showing Citadel Bridge, we suggest explaining how Citadel API works step-by-step and providing user the comfort that the process is private and secure.

Users need to understand how they can benefit from connecting their account. Explaining that they can instantly complete direct deposit split instead of manually updating information with their employer or sending manual forms.

For examples reach out to [email protected].

Citadel Bridge

If explaining benefits and setting context doesn't fit into your application UI, you can use "How it works tutorial". Visit White labeling section in dashboard to enable the screen in Citadel Bridge.

Did this page help you?