Direct Connection Users

You can ask users to connect to open banking on your own product via the D•One co-branded Direct Connection journey. The user journey begins on your product. The user is then asked to connect on the D•One co-branded connection journey, and is then returned to your product.

⚠️

Be aware

If you're integrating via a marketplace, you won't need to manage this journey—it's handled entirely by the marketplace. Please visit marketplace integration page.

The user flow

The journey begins when you ask a user to connect their bank account on your product. They will be directed to the D•One co-branded Direct Connection journey which features your branding colours and logo. In this flow, they will provide consent, and connect their bank account. They will then be redirected back to your product.

Integration overview

There are two ways to integrate the Direct Connection journey with your product. The end-to-end flow is the same whichever integration option you pick:

1. Create a user. Call Create User (POST /v1/users). The response contains the D•One userId for that user. Store this userId against your own user record. You'll need it for every later session and data call.

2. Create a session. Call Create Session (POST /v1/sessions) with the userId, your partnerRedirectUrl, and, ideally, a correlationId. The correlationId is your own identifier for the user, up to 256 characters. We return it to you unchanged when the session completes.

3. Launch the journey. Send the user to the connectionUrl from the response for a first-time connection, or the managementUrl to manage existing connections. How you "send" them depends on the option: with the embedded integration you pass the connectionUrl to the package and it loads the journey in an iframe on your page; with click-out you redirect the browser to it. Both options are described below.

4. The user completes the journey. We redirect them to your partnerRedirectUrl with a sessionTerminationToken query parameter appended, for example https://your-app.example/return?sessionTerminationToken=XXXX.

5. Complete the session. From your server, call Complete Session (PUT /v1/sessions/completed) with the sessionTerminationToken in the Authorization header. The response contains the userId and your original correlationId, so you can match the user back to your records.

⚠️

Sessions expire. Check the expiry field in the Create Session response. If a session expires before the user starts the journey, create a new one. Don't reuse the old URLs.

Option 1: Embedded integration (recommended)

Use the Embedded Connection Journey package to show the journey in an iframe overlay on your own site. Initialise it with the connectionUrl and sessionId from Create Session.

There are two ways you learn what happened. In both integration options, a completed journey is signalled by a redirect. In the embedded journey, an exit or error is signalled by a callback you pass to createJourney(). The callbacks are documented in the package's API reference. Here is what happens for each outcome:

📘

onExit only fires when the user leaves without connecting any accounts. If they connected accounts and then close the journey, that counts as completion and they are redirected to partnerRedirectUrl instead.

Because completion navigates the whole page, your partnerRedirectUrl should be a page in your app that can pick the flow back up. It doesn't have to be the page the journey was launched from.

Option 2: Click-out integration

Redirect the user to the connectionUrl, or open it in a new tab. On completion, that tab is redirected to partnerRedirectUrl?sessionTerminationToken=..., the same as above.

With this option there are no exit or error callbacks. If the user abandons the journey, you never receive the redirect. Design your UX so the user can come back and start again, and create a fresh session when they do.

Identifying the user on return

When the user lands on your partnerRedirectUrl:

1. Read the sessionTerminationToken query parameter.
2. From your server (never from the browser), call PUT /v1/sessions/completed with Authorization: Bearer <sessionTerminationToken>.
3. The response contains the sessionId, the D•One userId, and the correlationId you supplied when you created the session. Match the correlationId back to your own user record.

This doesn't depend on the browser. It uses no cookies or local storage and doesn't need the user to return in the same tab, so it works even if they switched browsers or devices part-way through.

Knowing when data is ready

Completing the journey means the user gave consent. It does not mean their transaction data is available yet. There are two ways to find out when it is.

Webhooks (recommended). Subscribe to webhooks. The v1.account_transactions.user_initiated.succeeded event fires for each connected account once its initial data is ready to read.

Polling. Call the Accounts endpoint for the user and check whether their data is available. See Data Availability for what to check.