Account Membership

Definition
We've already explained that an account has an account holder.
When an account is opened for a physical person, it is often linked to just one person. But not necessarily. Take for example an account with guardianship ⇒ A grandma can give rights to her grandson to go buy her groceries. In this case, the account owner is grandma. Her grandson is just a user; he has an account membership.
An account membership represents the rights of a Swan user to use a given account. Every account is administered by a member that has legal representative status. The administrator can give multiple users rights to the account; each of these users would have an account membership.
The Swan user that initiated the onboarding of an account receives the first account membership and becomes legal representative.
When an account is opened for a legal person (such as a company or association), the legal representative will commonly delegate rights to the account to other members. Colleagues may receive an account membership if they often need to make payments autonomously, or a bookkeeper may receive an account membership in order to access the account statement.
A user can also access multiple accounts belonging to different account holders, like in the example below:
Membership permissions
Account members can be assigned different rights to an account, restricting access to only the desired actions. These rights are referred to as permissions in the Swan API and frontend.
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:
Main IBAN and virtual IBANs
Beneficiaries
Payment mandates
List of transactions and transaction details
canManageBeneficiaries
Add or remove beneficiaries
canInitiatePayments
Initiate transfers to saved beneficiaries
canManageAccountMembership
Add, modify, or remove account memberships
canManageCards
Manage their own cards cards and cards for account memberships they manage
Creating cards
Whether your account members can create cards and for whom depends on both canManageAccountMembership and canManageCards permissions.
canManage...
AccountMembership = true
AccountMembership = false
Cards = true
✓ Create cards for self
✓ Create cards for others*
✓ Create cards for self
☒ Can't create cards for others
Cards = false
☒ Can't create cards for self
☒ Can't create cards for others
☒ Can't create cards for self
☒ Can't create cards for others
Cards = optional
✓ Create cards for self
✓ Create cards for others
☒ Can't create cards for self
☒ Can't create cards for others
*others → other account memberships
Invitation process
Single invitation
Only a pre-authorized member with the canManageAccountMembershipright can invite new members to their account by using theaddAccountMembership mutation. This very sensitive operation can be confirmed by Strong Customer Authentication through the user's smartphone.
For each invitation, you must transmit the following information to Swan: the user's email, firstName, lastName, phoneNumber, birthDate (optional), and their rights.
The birthDate field is obligatory when the account membership has these rights:
canManageBeneficiaries
canInitiatePayments
canManageAccountMembership
CanManageCards
To secure access to the account, the new member's identity will be verified by Swan before they can perform sensitive operations. Learn More​
For some use-cases we can remove the identity verification requirement on account membership. It will requires additional security on your side.
Please get in touch with [email protected] to learn more about this.
Overview of the process to add and bind an accountMembership
To invite a new member, there are two options:
#nocode: you can use the interface to email the new member a URL invitation to the white-label bank.
by API: you can integrate the new member into your system by using the addAccountMembership mutation. If canManageCards is empty, it will inherit the value of canManageAccountMembership.
When you do this, make sure you are authentified with anaccessToken using the identity of a member who has the canManageAccountMembership right. The new account membership is thus created with the ConsentPending status and a consentUrl is returned which invites the user to carry out Strong Customer Authentication with Swan. Learn More. Once the Strong Customer Authentication process is finished, the new account membership changes to InvitationSentstatus. You will need to store the new accountMembershipId in order to bind a user to it.
If the membership was added by API, we won't send an email to the new member, you will need to contact them and give them the procedure (see below) to create a user account. You must authenticate the new member using the protocol oauth2. Learn More.
When a Swan user responds to the invitation and connects for the first time, they will need to follow these steps:
1.Enters their phone number on the web page
If onboarding via a mobile phone: a verification code will be sent to confirm the phone number
If onboarding via a desktop: a link will be sent to confirm the phone number and open the verification process on the smartphone
2.On their smartphone enter some personal data like first name, last name and birthdate
3.Select a 6-digit passcode (and FaceID / TouchID, if applicable) that will be used every time we need to ask a consent to the user
4.Identity verification: a combination of identity documentation and biometric face recognition. This step can be performed later.
5.Start using Swan.
nocode: if the invitation was sent through the white-label web banking, the user is redirected to the web banking.
by API: if the invitation was sent through the API, the user is redirected to the oauth2 redirect URL which fetches the oauth2 authorization code and thereby obtains an accessToken. Using this token you need to call the  bindAccountMembership mutation with the accountMembershipId you stored after the call to addAccountMembership. This associates the account membership to the Swan user. Learn More.
A pre-existing user will only need to go through steps 3 to 5.

State diagram of an account membership status
For an account membership to be Enabled the user data must match the membership data and the user must be idverified=true.
When the account membership status is Enabled the user has access to all of their rights.
If the data doesn't match, the user hasBindingUserError status and one or more of the boolean fields below has  true status:
mobilePhoneMatchError
firstNameMatchError
lastNameMatchError
birthDateMatchError
idVerifiedMatchError
When the account membership status is BindingUserError the user can access the account and their cards but cannot make any sensitive operations (such as make a transfer or consult their card numbers).
When the account membership is BindingUserError, a member that is pre-authorized with the canManageAccountMembership right to this account can update the account membership data (If a typo occurred when the invitation was sent out) or suspend the account membership (if fraud is suspected)
It can happen that an account membership has no rights on the account, in which case:
canViewAccount=false
canManageBeneficiaries=false
canInitiatePayments=false
canManageAccountMembership=false
CanManageCards=false
This is the case when you want to give just one card to a user. In this case, the account membership is created straightaway with the InvitationSent status, without requiring consent from the account administrator.  
You can test this sequence as often as you'd like from your sandbox.
Create as many Sandbox users as you want, to simulate as many cases as possible. Learn More.
Bulk invitations
Using our API, the mutation AddAccountMemberships will add several members at once. If at least one of the members has one of the below rights, a strong customer authentication will be required:
canManageBeneficiaries
canInitiatePayments
canManageAccountMembership
canViewAccount
CanManageCards
When you do this, make sure you are authenticated with anaccessToken using the identity of a member who has the canManageAccountMembership right. The new account memberships are thus created with the ConsentPending status and a consentUrl is returned which invites the user to carry out Strong Customer Authentication with Swan. Learn More. Once the Strong Customer Authentication process is finished, the new account memberships change to InvitationSentstatus. You will need to store all new accountMembershipId in order to bind a user to them.
As the memberships were added by API, we won't send an email to the new members, you will need to contact them and give them the procedure to create a user account. You must authenticate the new members using the protocol oauth2. Learn More. For the rest of the process, please refer to Single invitation as once created, all memberships will follow the process detailed for single invitations.
To learn more about bulk invitations, please check this guide.
For performance reasons, bulk invitations are limited to 200 memberships per API call
ID verification removal
Identity verification can be removed for some B2B cases only after making an agreement with our compliance. It is only possible to skip identity verification for users with an account membership. Here are the requirements: 
canManageAccountMembership=false
canInitiatePayments=false
canManageBeneficiaries=false
canViewAccount=false or true
CanManageCards=false or true
To invite a member, you must use the API method and authenticate him by removing the idverified scope. Learn more. 
If the Swan user connects for the first time, the idVerified user's parameter remains at false.

If ever the mobile phone doesn't match, the user status will be BindingUserError the field mobilePhoneMatchError will say  true. 
When the account membership status is BindingUserError , that user can access their account and cards but cannot make any sensitive operations (such as consulting their card numbers).
Manage Account Membership
Modifying membership data: These very sensitive operations must be confirmed with consent.
A newly added account membership still in consent pending status cannot be updated. If the membership information is incorrect, it must be cancelled, and a new account membership should be created.
To perform this operation by API you must use the updateAccountMembership mutation. While doing this, make sure you are authenticated with an accessToken using the name of the user behind the modification. Learn More. To modify, the user must have the canManageAccountMemberships right. The users won't be able to give a permission they don't have themselves to another membership. Furthermore, the legal representative's accountMembership can only be updated by themselves.
The request from this mutation returns a newly created consent resource containing the consentUrl. The url allows you to redirect the user making the modification to Swan's strong authentication. Learn more.
Once the consent process is completed, the account membership is updated and its attribute version is increased by 1.
Suspend or reactivate account memberships: These operations must be confirmed with consent.
To perform suspending operations by API you must use the suspendAccountMembership mutation while authenticated with an accessToken using the name of the user behind the suspension. Learn More.
Once suspended its attribute version is increased by 1.
To perform reactivation operations by API you must use the resumeAccountMembership mutation while authenticated with an accessToken using the name of the user behind the reactivation. Learn More.
The request from this mutation returns a newly created consent resource containing a consentUrl . The url redirects the user who requested to be reactivated to Swan's Strong Customer Authentication. Learn more.
Once the consent process is completed, the account membership is reactivated and its attribute version is increased by 1.
Disable an account membership
To disable an account membership, which will revoke the access to the account the user had, you must call the disableAccountMembership mutation. This mutation is non-sensitive and does not require consent. The accountMembership will be moved to the Disabled status.
Disabling is referred to as permanently blocking on the Web Banking interface.
Canceled accounts and memberships
As soon as an account is closed, account members can no longer initiate payments or manage account memberships and beneficiaries.
Account members can still see the account for one year, after which all account memberships linked to the canceled account are disabled.

Permission	Account member can...
`canViewAccount`	View the account and information about the account, including: Main IBAN and virtual IBANs Beneficiaries Payment mandates List of transactions and transaction details
`canManageBeneficiaries`	Add or remove beneficiaries
`canInitiatePayments`	Initiate transfers to saved beneficiaries
`canManageAccountMembership`	Add, modify, or remove account memberships
`canManageCards`	Manage their own cards cards and cards for account memberships they manage

Last modified 4h ago

`canManage`...	`AccountMembership` = true	`AccountMembership` = false
`Cards` = true	✓ Create cards for self ✓ Create cards for others*	✓ Create cards for self ☒ Can't create cards for others
`Cards` = false	☒ Can't create cards for self ☒ Can't create cards for others	☒ Can't create cards for self ☒ Can't create cards for others
`Cards` = optional	✓ Create cards for self ✓ Create cards for others	☒ Can't create cards for self ☒ Can't create cards for others