MagicDoorAPI
SupportOpen MagicDoor
Bank accounts (Portal)

Connect a bank account to a payment provider

Starts onboarding this bank account with Plaid or Stripe so it can send and receive money. A Plaid connection needs bank statements attached; a Stripe connection returns either a hosted onboarding link or a client secret for an embedded onboarding page.

POST
https://api.portal.magicdoor.com/company-app/bank-accounts/{bankAccountId}/connections/{type}

Authorization

Authorizationstringrequired
Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Path parameters

bankAccountIdstringrequired

The bank account to connect. A Snowflake id sent as a decimal string.

example: 1801556677120004096
typeenum<string>required

Which provider to connect to.

example: stripeplaidstripe

Body

application/json

Which properties matter depends on type.

statementUploadSessionIdsstring[]

Upload sessions holding the bank statements that back a Plaid connection. Create them with the statement upload session endpoint first. Required for a Plaid connection; at least two.

statementFileIdsstring[]deprecated

The older way of attaching statements, by the id of an already-uploaded file. Use statementUploadSessionIds instead. At least two.

companyBusinessInfoIdstring

Which of the company's business records to onboard with, for a Plaid connection. Left out, the company's primary business record is used.

isEmbeddedboolean

Stripe only. true returns a clientSecret for embedding Stripe's onboarding page in your own UI; otherwise a hosted link is returned for the user to open.

Response

200 · Onboarding has been started. Which property is filled in depends on the provider and on `isEmbedded`; both may be absent for a Plaid connection, which needs no hand-off.

linkstring

A Stripe-hosted onboarding page to send the user to. Absent when isEmbedded was true, and for Plaid.

clientSecretstring

An opaque Stripe token for embedding the onboarding page in your own UI. Absent unless isEmbedded was true. Treat it as a secret and do not parse it.

401 · The access token is missing, expired, or does not belong to a property manager.

404 · No bank account with that id exists for the caller's company. One belonging to another company reads the same way.

422 · The account cannot be connected as asked — for example the statements attached to a Plaid connection do not meet the requirements, or the provider rejected the request. The `detail` says what went wrong.