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.
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.
| Method | Explanation |
|---|---|
| Inviter provides phone number and email |
|
| Inviter provides email only |
|
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 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. |
canManageBeneficiaries | Add or remove beneficiaries, and save beneficiaries as trusted. |
canInitiatePayments | Initiate (send) credit transfers to trusted beneficiaries. |
canManageAccountMembership | Add, update, suspend, resume, and disable account memberships, and view the list of account members. |
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:
- The email your account members receive inviting them to accept an account membership.
- The letter included with the account member's physical card.
- 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)
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:
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:
|
InvitationSent | An invitation was sent to the invited account member. Next steps:
|
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:
|
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.
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.
Refer to the guide to fix a user binding error for more information.
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.
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, or send user new authorization URL to verify email. |
idVerifiedMatchError | The user wasn't assigned the right identification level. | The user needs to complete another identification process. |
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:
canManageAccountMembershipcanInitiatePaymentscanManageBeneficiaries
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 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).