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're using Swan's Web Banking interface, your users can invite members directly from the app.

Method	Explanation
Inviter provides phone number and email	Account member's mobile SIM card serves as the authentication factor. Account member can be assigned all membership permissions. Swan confirms the member's phone number during the sign-up process.
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.

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.

Permission	Account member can...
canViewAccount	View the account and information about the account, including but not limited to: main and virtual IBANs, trusted beneficiaries, payment mandates, transactions and transaction details, and account members. Cardholders with the canViewAccount permission can view their own transaction history, even if they have no other permissions.
canManageBeneficiaries	Add or remove beneficiaries, and save beneficiaries as trusted.
canInitiatePayments	Initiate (send) credit transfers to trusted beneficiaries.
canManageAccountMembership	Add, modify, or remove account memberships.
canManageCards	View, 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.

canManage...	AccountMembership = true	AccountMembership = false
Cards = true	✓ View, add, and update cards for self ✓ View, add, and update cards for others∗	✓ View, add, and update cards for self ☒ Can't view, add, or update cards for others
Cards = false	✓ View their own cards ✓ If they have an existing virtual card, they can print a physical card for self ☒ Can't add virtual cards for self ☒ Can't update any cards for self ☒ Can't view, add, or update cards for others
Cards = not provided	✓ View, add, and update cards for self ✓ View, add, and update cards for others	✓ View their own cards ✓ If they have an existing virtual card, they can print a physical card for self ☒ Can't add virtual cards for self ☒ Can't update any cards for self ☒ Can't view, add, or update cards for others

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

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 status	Explanation
ConsentPending	Request to add an account membership was sent with the addAccountMembership mutation and is waiting for the account holder'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 membership with the addAccountMembership mutation. Next steps: If the invited account member consents, the status moves to InvitationSent If the invited account member doesn't consent, the status moves to Disabled
InvitationSent	An 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
Enabled	All 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.
BindingUserError	The 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.
Suspended	Account 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
Disabled	Account 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:

• The information you submitted about the invited account member doesn't match the information they provided when signing up for an account.
• The user hasn't completed identification.
• If you invited the account member by verified email, the email you provided might not match the email they used to sign up, or they might not have verified their email yet.

At least one of the following booleans must be true for an account membership to have a user binding error:

Error	If true	Update
firstNameMatchError	There's a mismatch with the first or given name.	Update restrictedTo > firstName.
lastNameMatchError	There's a mismatch with the last or family name.	Update restrictedTo > lastName.
birthDateMatchError	There's a mismatch with the birth date.	Update restrictedTo > birthDate.
mobilePhoneMatchError	There's a mismatch with the phone number.	Update restrictedTo > phoneNumber.
emailVerifiedMatchError	There's a mismatch with the email, or the user didn't verify their email.	Update email.
idVerifiedMatchError	The user wasn't assigned the right identification level.	The user needs to complete another identification process.

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.

Other account members with the canManageAccountMembership permission and status Enabled can fix the mismatch. If fraud is suspected, suspend the membership instead.

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 with identification removed, only memberships with certain permissions can bypass identification.

✓ Can bypass identification	☒ Can't bypass identification
canViewAccount canManageCards	canManageAccountMembership canInitiatePayments canManageBeneficiaries

Note that memberships created before identification is removed still need to verify their identity. Adding this configuration isn't retroactive. 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 includes including 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

• Add a membership
• Add multiple memberships
• Update a membership (use to fix a user binding error)
• Suspend (temporarily block) or resume a membership
• Disable (permanently block) a membership