Unirail

Link sessions and user actions

Linking a customer's bank account, and every kind of step a provider can ask your user to take.

A link session (lnk_…) is one attempt to connect a customer's bank account through a provider. It ends with the linked accounts, or with a reason it didn't work.

const session = await unirail.linkSessions.create(
  {
    customer: customer.id,
    country: "GB",
    institution: "ins_8XkQ2mPz4r", // optional: let the policy pick a provider for this bank
    channel: "web",
    returnUri: "https://example.com/bank-link/done",
  },
  { context: { idempotencyKey: `link:${attempt.id}` } },
);

Lifecycle

  1. requires_action. The session has a nextAction for your user, such as a redirect to their bank. Show any disclosures first: some providers require you to display their terms before the user continues.
  2. The user acts and comes back. They land on your returnUri, or the provider SDK hands you a result.
  3. Advance. Call linkSessions.advance with what you received: returnParams (the query parameters on your return URI, verbatim) or sdkResult (for example Plaid's public token).
  4. completed with accounts (the new acct_… ids), or failed, cancelled or expired with a failure explanation.

Unirail also emits link_session.completed and link_session.failed, so a session the user finished on another device still reaches you.

User actions

nextAction (on link sessions and payment intents) is one of these:

kindWhat your app does
redirectSend the user to url. They come back to your returnUri.
sdkOpen the provider's SDK named in provider (for example Plaid Link) with token, then advance with sdkResult.
decoupledThe user approves somewhere else, usually their banking app. Show message and wait for the event.
qrRender payload as a QR code for the user to scan with their banking app.
app-handoffOpen url, which hands off to another app on the device.
funding-instructionsShow the payto address, reference and amount the user should pay.
formAsk the user for the listed fields.
add-payee-in-bankThe user has to add the payee in their own bank first. Show instructions.
noneNothing to do; wait for the next event.

Actions that expire carry expiresAt. Set channel: "native" when your user is in a mobile app rather than a browser.

On this page

LifecycleUser actions