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​

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.

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		🇩🇪
Germany		🇳🇱
Netherlands		🇪🇸
Spain		🇮🇹
Italy
accountID● REQ● REQ● REQ● REQ● REQ
canInitiatePayments● REQ● REQ● REQ● REQ● REQ
canManageAccountMembership● REQ● REQ● REQ● REQ● REQ
canManageBeneficiaries● REQ● REQ● REQ● REQ● REQ
canManageCards○ OPT○ OPT○ OPT○ OPT○ OPT
canViewAccount● REQ● REQ● REQ● REQ● REQ
consentRedirectUrl● REQ● REQ● REQ● REQ● REQ
email● REQ● REQ● REQ● REQ● REQ
language○ OPT○ OPT○ OPT○ OPT○ OPT
residencyAddress.addressLine1○ OPT◐ CND◐ CND○ OPT● REQ
residencyAddress.addressLine2○ OPT○ OPT○ OPT○ OPT○ OPT
residencyAddress.city○ OPT◐ CND◐ CND○ OPT● REQ
residencyAddress.country○ OPT◐ CND◐ CND○ OPT● REQ
residencyAddress.postalCode○ OPT◐ CND◐ CND○ OPT● REQ
residencyAddress.state○ OPT○ OPT○ OPT○ OPT○ OPT
restrictedTo.firstName● REQ● REQ● REQ● REQ● REQ
restrictedTo.lastName● REQ● REQ● REQ● REQ● REQ
restrictedTo.phoneNumber◐ CND◐ CND◐ CND◐ CND◐ CND
restrictedTo.birthDate◐ CND◐ CND◐ CND◐ CND◐ CND
taxIdentificationNumber○ OPT◐ CND○ OPT○ OPT◐ CND
🇫🇷
France		🇩🇪
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

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​

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.

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 Technical Account 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

∗ 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).

Guides​