We value your privacy

We use cookies to enhance your browsing experience, serve personalized ads or content, and analyze our traffic. By clicking "Accept All", you consent to our use of cookies. Read More

Skip to main content

Account memberships

Representation of the rights, also referred to as access and permissions, of Swan users to an account. While location is restricted for account holders, accounts members can be located anywhere in the world.

Overview​

The Swan user who performs the account's onboarding is the first account member and becomes the account's legal representative. All Swan accounts have at least one account member: the legal representative. The legal representative can grant other Swan users permission to perform certain actions for the account; each of these users is an account member.

Consider a real-life example

A grandparent wants their grandchild to have access to an account to purchase groceries. The grandparent is the legal representative (and an account member), and the grandchild is an account member.

Inviting members​

The invitation process allows you to grant account access to new users. When you invite someone to become an account member, they receive an email notification asking them to accept the invitation and bind their Swan user to their account membership in order to grant access to the account on which you invited them.

You can invite account members by phone number or by verified email. Use the API to add one membership or multiple memberships. If you use Swan's Web Banking interface, your users can invite members directly from the app.

Invitation flow:

  1. A user with an account membership (the inviter) with the canManageAccountMembership permission creates a new account membership (for the invitee) using the API or our Web Banking interface.
  2. The new membership is created with the status ConsentPending or InvitationSent, depending on whether consent is required.
  3. We send an email invitation to the invited member (depending on your notification configuration).
  4. The invited member clicks the link in the email, signs in or signs up to Swan, and accepts the invitation.
  5. The user is bound to the account membership and the status changes to Enabled or BindingUserError.
MethodExplanation
Inviter provides phone number and email
Inviter provides email only
  • Account member's verified email serves as the authentication factor. The membership isn't enabled until user verifies their email.
  • Account member can only be assigned the canViewAccount and canManageCards memberships permissions.
  • Swan confirms the member's email during the sign-up process.
  • Swan collects the user's phone number during the sign-up process so the member can perform sensitive operations such as initiating payments, ordering cards, and viewing sensitive card information.

Company accounts​

Account memberships are especially useful for company accounts. The legal representative grants permissions to other employees. Employees can then manage their own payments, such as software or sales expenses, independently. The company's accountant can use their membership to access account statements. With enough permissions, managers can add cards for their team. How you use account memberships and the corresponding permissions is up to you—the possibilities are almost endless to fulfill your use case.

Unlimited memberships​

Swan users can have memberships to an unlimited number of Swan accounts.

Consider the following example, where Sasha Oliveira has account memberships to accounts for MyBrand and eFounders. Based on their membership permissions, Sasha can access and manage memberships for both accounts, but only manage cards for one.

Visual depiction of multiple account memberships with different permissions

Membership permissions​

Account members can be assigned different rights to an account, allowing access to only the desired actions and information. These rights are referred to as permissions in the Swan API and Web Banking interface.

Swan doesn't offer role-base access control (RBAC). Instead, you choose exactly what each account member can see and do on a member-by-member basis.

PermissionAccount member can...
canViewAccountView the account and some information about the account, including but not limited to: main and virtual IBANs, trusted beneficiaries, payment mandates, and transactions and transaction details.

Cardholders with the canViewAccount permission can view their own transaction history, even if they have no other permissions.
canManageBeneficiariesAdd or remove beneficiaries, and save beneficiaries as trusted.
canInitiatePaymentsInitiate (send) credit transfers to trusted beneficiaries.
canManageAccountMembershipAdd, update, suspend, resume, and disable account memberships, and view the list of account members.
canManageCardsView, add, and update their own cards and cards for account memberships they manage.

Granting permissions​

In order to grant permissions to other account members, the account member must have the permission canManageAccountMembership. They can only grant permissions they already have.

For example, if an account member doesn't have the canManageCards permission, they can't grant it to another account member. If they try to grant the canManageCards permission anyway, the API returns a PermissionCannotBeGrantedRejection error.

Managing cards​

Whether your account members can manage cards and for whom depends on both canManageAccountMembership and canManageCards permissions. Please note that cardholders without the canViewAccount permission can view their own transaction history, even if they have no other permissions.

Support Status Legend

✓ Supported: Feature is available.
✗ Unsupported: Feature is not available.
ActioncanManageCards = truecanManageCards = falsecanManageCards = not provided
canManageAccountMembership = true
View, add, update cards for self✓✗✓
View, add, update cards for others*✓✗✓
View own cards only-✓-
Print physical card from existing virtual-✓-
canManageAccountMembership = false
View, add, update cards for self✓✗✗
View, add, update cards for others*✗✗✗
View own cards only-✓✓
Print physical card from existing virtual-✓✓

* others → other account members

No permissions​

You can add account members without granting them any membership permissions. For example, if you want to give a user a card associated with the account, but you don't want them to view account information or perform any actions for the account, you'd add an account membership with no permissions.

In this case, all membership permission booleans are false. This type of invitation doesn't require consent from the account holder and skips the status InvitationSent.

Country requirements for account memberships​

To invite an account member, you must provide specific account membership fields.

Requirements vary depending on the IBAN country. Swan automatically sets these requirements based on the member's permissions, accountCountry, and residencyAddress.country.

Field Requirements Legend

● REQ Required:Must be completed.
◐ CND Conditional:Required only in specific situations.
○ OPT Optional:Isn't required; may have a default value.
API field🇫🇷
France		🇧🇪
Belgium		🇩🇪
Germany		🇳🇱
Netherlands		🇪🇸
Spain		🇮🇹
Italy
accountID● REQ● REQ● REQ● REQ● REQ● REQ
canInitiatePayments● REQ● REQ● REQ● REQ● REQ● REQ
canManageAccountMembership● REQ● REQ● REQ● REQ● REQ● REQ
canManageBeneficiaries● REQ● REQ● REQ● REQ● REQ● REQ
canManageCards○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
canViewAccount● REQ● REQ● REQ● REQ● REQ● REQ
consentRedirectUrl● REQ● REQ● REQ● REQ● REQ● REQ
email● REQ● REQ● REQ● REQ● REQ● REQ
language○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
residencyAddress.addressLine1○ OPT○ OPT◐ CND◐ CND○ OPT● REQ
residencyAddress.addressLine2○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
residencyAddress.city○ OPT○ OPT◐ CND◐ CND○ OPT● REQ
residencyAddress.country○ OPT○ OPT◐ CND◐ CND○ OPT● REQ
residencyAddress.postalCode○ OPT○ OPT◐ CND◐ CND○ OPT● REQ
residencyAddress.state○ OPT○ OPT○ OPT○ OPT○ OPT○ OPT
restrictedTo.firstName● REQ● REQ● REQ● REQ● REQ● REQ
restrictedTo.lastName● REQ● REQ● REQ● REQ● REQ● REQ
restrictedTo.phoneNumber◐ CND◐ CND◐ CND◐ CND◐ CND◐ CND
restrictedTo.birthDate◐ CND◐ CND◐ CND◐ CND◐ CND◐ CND
taxIdentificationNumber○ OPT○ OPT◐ CND○ OPT○ OPT◐ CND
🇫🇷
France		🇧🇪
Belgium		🇩🇪
Germany		🇳🇱
Netherlands		🇪🇸
Spain		🇮🇹
Italy

Detailed optional and conditional requirements​

Birthdate​

The restrictedTo.birthDate field is required if any of the following account membership permissions are set to true:

  • canManageBeneficiaries
  • canInitiatePayments
  • canManageAccountMembership
  • canManageCards

Membership permissions​

If no value is provided for canManageCards, it defaults to the value of canManageAccountMembership.

Phone number​

The restrictedTo.phoneNumber field is required if any of the following account membership permissions are set to true:

  • canManageBeneficiaries
  • canInitiatePayments
  • canManageAccountMembership

Residency address fields​

The addressLine1, city, country, and postalCode fields are required regardless of residencyAddress.country, in the following cases:

  • The accountCountry is 🇮🇹 Italy.
  • The accountCountry is 🇩🇪 Germany or 🇳🇱 Netherlands, and one or both of the following account membership permissions are set to true:
    • canViewAccount
    • canInitiatePayments

Tax identification number​

The taxIdentificationNumber field is required in the following cases:

  • If both accountCountry and residencyAddress.country are 🇮🇹 Italy, and the account membership has the canInitiatePayments permission set to true.
  • If both accountCountry and residencyAddress.country are 🇩🇪 Germany, and one or both of the following account membership permissions are set to true:
    • canViewAccount
    • canInitiatePayments

Validation rules​

Certain account membership fields must follow specific validation patterns.

First name and last name​

The restrictedTo.firstName and restrictedTo.lastName fields must match the following validation pattern:

/^(?:[A-Za-zÀ-ÖÙ-öù-ƿDŽ-ʯʹ-ʽΈ-ΊΎ-ΡΣ-ҁҊ-Ֆա-ևႠ-Ⴥა-ჺᄀ-፜፩-ᎏᵫ-ᶚḀ-῾ⴀ-ⴥ⺀-⿕ぁ-ゖゝ-ㇿ㋿-鿯鿿-ꒌꙀ-ꙮꚀ-ꚙꜦ-ꞇꞍ-ꞿꥠ-ꥼＡ-Ｚａ-ｚ]| |'|-|Ά|Ό|,)*$/

This pattern accepts the following characters:

  • Unicode letters from various scripts, including Latin, Cyrillic, Greek, Armenian, Georgian, Korean, Japanese, and Chinese.
  • Spaces.
  • Apostrophes (').
  • Hyphens (-).
  • Commas (,).
  • Special Greek characters (Ά, Ό).
Aligned with user creation

These validation rules are the same as those applied when creating users.

Membership language​

You can choose and update the language used for account memberships. The following communications use the account membership language:

  1. The email your account members receive inviting them to accept an account membership.
  2. The letter included with the account member's physical card.
  3. When using their physical card, payment terminals and point of service (POS) screens.

By default, account memberships inherit the same language as the account. It's possible, however, that not all account members prefer the language chosen by the account holder.

You can update the language for each account membership with the API. If you use Swan's Web Banking interface, eligible account members can choose the preferred language when inviting new account members through the app. Account members can also use the app to update their preferred language independently.

Supported languages​

Several languages are available for account memberships:

  • Dutch (nl)
  • English (en)
  • Finnish (fi)
  • French (fr)
  • German (de)
  • Italian (it)
  • Portuguese (pt)
  • Spanish (es)
Finnish (fi)

Finnish is a supported account language and account membership language with certain limitations:

  • Finnish isn't available as a card language. When the account language is Finnish, the card language defaults to English, which includes card packaging and the language displayed on payment terminals.
  • Finnish isn't available for the bank details document. When the account language is Finnish, the bank details document is generated in English.

Physical cards & membership language​

The language used for physical cards can't be updated. Language choice, just like the four-digit PIN, is coded on the card's chip. The card's language can't be updated for a renewed card, either, because the expiring card's chip is replicated for the new card and can't be changed.

If an account member has a physical card that doesn't use their preferred language, you or the cardholder needs to complete the following steps:

  1. Update the account membership language.
  2. Cancel the physical card.
  3. Order a new physical card.

Account membership statuses​

Final status
Can use membership
Disabled
Enabled
Account
membership
added
ConsentPending
InvitationSent
BindingUserError
Suspended
Account membership statusExplanation
ConsentPendingAn account membership request was sent using the addAccountMembership mutation and is waiting for the inviter's consent.

Memberships with the status ConsentPending can't be updated. If there's an error in the invited account member's information, cancel the invitation and add a new account membership with the addAccountMembership mutation.

Next steps:
  • If the invited account member consents, the status moves to InvitationSent
  • The account membership status moves to Disabled if the inviter opens the consent flow but doesn't consent, or if the invitation expires before the invited member consents.
  • For Disabled memberships because of expired consent, querying AccountMembershipDisabledStatusInfo shows the reason as InvitationExpired.

If you're subscribed to the AccountMembership.Updated webhook, you'll receive a notification when a membership is Disabled.
InvitationSentAn invitation was sent to the invited account member.

Next steps:
  • If the invited account member accepts the invitation and provides personal information that matches the information Swan already has about them, the status moves to Enabled
  • If the invited account member accepts the invitation, but provides personal information that doesn't match the information Swan already has about them, the status moves to BindingUserError
  • If the invited account member declines the membership, the status moves to Disabled
EnabledAll user information matches, the account member has been awarded the correct identification level, and the account member can use their account membership and corresponding permissions.
BindingUserErrorThe personal information you submitted about the invited account member doesn't match the information they provide during the sign-up process. The mismatch must be solved before continuing.

Refer to the section on binding user errors for more information.
SuspendedAccount membership is suspended and not available for use.

Account memberships can be suspended for various reasons, including a request from you or the account's legal representative, or a Swan action in the case of suspicious activity.

Next steps:
  • Restore the account membership's previous status with the API
  • Cancel the account membership with the API
DisabledAccount membership is disabled, is no longer available for use, and can't be restored.

When an account member's membership is disabled, their recurring SingleUseVirtualCards are automatically reassigned to the account's Legal Representative.

Binding user errors​

The account membership status can be BindingUserError for several reasons, including the following scenarios:

Account members whose membership status is BindingUserError can still access basic account and card information, but they can't perform any sensitive operations, such as making a transfer or viewing their card numbers.

To fix binding errors, refer to the guide to fix a user binding error for detailed resolution steps based on the specific error type.

Updating account members

After an account member's status is Enabled, updating their personal details doesn't cause a user binding error. If fraud is suspected, suspend the membership.

Removing identification​

Verifying your account members' identity is a required step in most circumstances. However, with a detailed agreement with Swan, you might be allowed to bypass identification for certain membership permissions.

Even if your project is configured to remove identification, memberships with the following permissions can't bypass it:

  • canManageAccountMembership
  • canInitiatePayments
  • canManageBeneficiaries

Note that this configuration is retroactive. Memberships created before identification was removed no longer need to verify their identity. Contact your PIM (Product Integration Manager) to ask about removing identification.

Closed accounts and memberships​

When Swan accounts are closed, the account memberships are impacted as well.

As soon as an account status changes to Closing, account members can no longer manage account memberships and beneficiaries or initiate payments (except to empty the account). When the account status changes to Closed, account members can view the account for one year, after which all memberships to the closed account are Disabled.

Versioning​

Account memberships have a version attribute.

When a new membership is added, the version is 0, then increases by a factor of 1 with each change. Changes include suspending, resuming, and updating the membership.

Sequence diagram​

Adding account memberships

SwanPartner (you)Requester∗InviteeSwanPartner (you)Requester∗InviteeRequests account access for invitee1Calls `addAccountMembership` mutation2Sends request for consent3Provides consent4Returns `accountMembershipId`5Sends login URL to invitee6Logs into Swan with OAuth 2.07Redirects to Partner's interface with OAuth 2.0 access code8Redirected to Partner's interface with OAuth 2.0 access code9Requests invitee's user access token10Returns invitee's user access token11Calls `bindAccountMembership` mutation with`accountMembershipId` using invitee's user access token12Confirms account membership success,meaning invitee is bound to account13

∗ The requester can be the account holder, the account's legal representative, or an account member with the canManageAccountMembership permission. The requester provides consent (diagram line 4).

Notifications​

Swan sends email notifications to users when account memberships are managed.

The sender for all notifications is do-not-reply@swan.io. Notifications are branded with your logo and accent colors configured in your Dashboard under Settings > Branding.

Join your banking space​

When you invite someone to become an account member, Swan sends them an email invitation with a link to accept the membership.

Trigger: The invitation email is sent when you create a new account membership with the status InvitationSent. Depending on your integration approach, this happens automatically through Swan's Web Banking interface or requires an additional API call when using the API.

Configuration: The invitation notification is sent based on your integration setup:

  • Swan Web Banking: Invitations are sent automatically when using Swan's no-code Web Banking interface, unless the canAddNewMembers web banking setting is disabled in your Dashboard.
  • Swan Web Banking forked: If you've forked Swan's no-code Web Banking frontend, invitations are sent automatically.
Forked Web Banking migration

If you forked Swan's Web Banking before the migration to partner-branded notifications on Thursday, March 12, 2026, you must update your forked Web Banking to continue relying on Swan to send the invitation notification by email.

The email is sent to the account member's email address in their preferred language (or the account's default language if not set).

If an invited member doesn't receive their invitation, you can resend it up to five times per day using the same mutation, as long as the membership status remains InvitationSent.

Guides​