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 app 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 app 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:

Rights Management

Users can have restricted access to an account. Here are the different customizable settings for each account membership:

  • canViewAccount: lets you see the account, its IBAN, its virtual IBANs, its beneficiaries, its mandates, and its transactions

  • canManageBeneficiaries: lets you add or delete a beneficiary

  • canInitiatePayments: lets you initiate a transfer to an already recorded beneficiary

  • canManageAccountMembership: lets you invite, modify or delete an account membership

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 on the Swan app.

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

To secure access to the account, the new member's identity will be verified by Swan app before they can perform sensitive operations. Learn More

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.

    When you do this, make sure you are authentified with anaccessToken using the name of the 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 app. Learn More. Once the Strong Customer Authentication process is finished, the new account membership changes to InvitationSentstatus.

    If the invitation was sent through the API, you must ask the new member to authenticate to your product by using protocol oauth2 authorization code grant with theaccountmembership:bindand theidverifiedscope. Learn More.

When a Swan app user responds to the invitation and connects for the first time, they will need to follow these steps:

  1. Download Swan app, available on Google Play or App Store

    • Via a mobile phone: a deep link redirects to the smartphone's store (Google Play or Apple Store).

    • Via a desktop: the member must download the app from their smartphone's store. If they want, they can receive an SMS redirecting to it.

  2. Create a user account on Swan app using a phone number

  3. Bind with Swan app and the invitation process

    • Via a mobile phone: the deep link contains all the necessary information. The user doesn't have to do anything.

    • Via a desktop: the account holder uses Swan app to scan the QR Code displayed on the authentication page.

  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 authorisation code and thereby obtains an accessTokenThis calls the bindAccountMembership mutation which lets you associate the account membership to the Swan app user. Learn More.

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

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.

Manage Account Membership

Modifying membership data: These very sensitive operations must be confirmed with consent from the Swan app.

To perform this operation by API you must use the updateAccountMembership mutation. While doing this, make sure you are authentified with an accessToken using the name of the user behind the modification. Learn More.

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 app's strong authentication. Learn more.

Once the consent process is completed, the account membership is updated and its attribute version is increased by 1.

Blocking/unblocking an account membership: These operations must be confirmed with consent from the Swan app.

To perform blocking operations by API you must use the suspendAccountMembership mutation while authentified with an accessToken using the name of the user behind the blockage. Learn More.

Once suspended its attribute version is increased by 1.

To perform unblocking operations by API you must use the resumeAccountMembership mutation while authentified with an accessToken using the name of the user behind the unblocking. Learn More.

The request from this mutation returns a newly created consent resource containing consentUrl . The url redirects the user who requested the unblocking to Swan app's Strong Customer Authentication. Learn more.

Once the consent process is completed, the account membership is unblocked and its attribute version is increased by 1.