Giving access to accounts
Swan allows you to give multiple people access to the same payment account, and define precisely how they can use that account.

Add a membership and bind it

At Swan, any user with access to a payment account has an account membership. Access to an account can come in several forms:
  • having a card linked to the payment account
  • being able to initiate SEPA transfers on the account
  • being able to see the account's transactions
  • ...
Account memberships are controlled by the account holder who can invite users, suspend them, and delete them.
You can add account memberships both via the web banking or the API. The only difference between the two is that through the API you'll have to contact the invitee yourself, whereas the web banking will send them an email. The form to add new memberships is available in the Members tab.
Creating an account membership via the web banking
In this example, Jane will receive an email asking her to click a link to access the account. She will then have to follow the standard authentification process, and need to verify her identity. To execute the same through API you will need to use two mutations as described by the following diagram.

Add a single membership

addAccountMembership creates an accountMembership with the specified rights for a unique invitee. When you call the mutation we ask you to provide personal data on the invitee.
Request
Response
1
mutation MyMutation {
2
addAccountMembership(
3
input: {
4
accountId: "{{YOUR_ACCOUNT_ID}}"
6
restrictedTo: {
7
firstName: "Jane"
8
lastName: "Dae"
9
phoneNumber: "+33600000000"
10
}
11
canViewAccount: true
12
canManageBeneficiaries: false
13
canInitiatePayments: false
14
canManageAccountMembership: false
15
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
16
}
17
) {
18
... on AddAccountMembershipSuccessPayload {
19
__typename
20
accountMembership {
21
id
22
statusInfo {
23
... on AccountMembershipConsentPendingStatusInfo {
24
__typename
25
consent {
26
consentUrl
27
}
28
}
29
}
30
}
31
}
32
}
33
}
34
Copied!
1
{
2
"data": {
3
"addAccountMembership": {
4
"__typename": "AddAccountMembershipSuccessPayload",
5
"accountMembership": {
6
"id": "efca9cb7-d01e-4386-8b75-77c68149b7ea",
7
"statusInfo": {
8
"__typename": "AccountMembershipConsentPendingStatusInfo",
9
"consent": {
10
"consentUrl": "https://identity.swan.io/consent?consentId=6c18e53e-9489-45dc-bec8-e90d7fd5ce41&env=Sandbox"
11
}
12
}
13
}
14
}
15
}
16
}
Copied!

Add multiple account memberships

addAccountMemberships creates several accountMembership with the specified rights for each invitee. When you call the mutation we ask you to provide personal data on the invitees. From the payload, you can take the consentUrl from any membership. The url is the same for all memberships as only one consent is required to approve all of them.
Request
Response
1
mutation MyMutation {
2
addAccountMemberships(
3
input: {
4
accountId: "{{YOUR_ACCOUNT_ID}}"
5
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
6
memberships: [
7
{
9
restrictedTo: {
10
firstName: "Jane"
11
lastName: "Dae"
12
birthDate: "1980-02-20"
13
phoneNumber: "+33600000000"
14
}
15
canViewAccount: true
16
canManageBeneficiaries: true
17
canInitiatePayments: true
18
canManageAccountMembership: true
19
}
20
{
21
22
restrictedTo: {
23
firstName: "Brad"
24
lastName: "Johnson"
25
phoneNumber: "+33600000000"
26
}
27
canViewAccount: true
28
canManageBeneficiaries: false
29
canInitiatePayments: false
30
canManageAccountMembership: false
31
}
32
]
33
}
34
)
35
}
36
Copied!
1
{
2
"data": {
3
"addAccountMemberships": {
4
"__typename": "AddAccountMembershipsSuccessPayload",
5
"accountMemberships": [
6
{
7
"id": "de8d46cf-6b15-44aa-bdeb-4a7a136355e7",
8
"statusInfo": {
9
"__typename": "AccountMembershipConsentPendingStatusInfo",
10
"consent": {
11
"consentUrl": "https://identity.demo.swan.io/consent?consentId=b7e0685b-677b-483c-ab7a-2942f2f71c0d&env=Sandbox"
12
},
13
"status": "ConsentPending"
14
}
15
},
16
{
17
"id": "cfe078c3-4603-4f76-a20f-a3d335f76b92",
18
"statusInfo": {
19
"__typename": "AccountMembershipConsentPendingStatusInfo",
20
"consent": {
21
"consentUrl": "https://identity.demo.swan.io/consent?consentId=b7e0685b-677b-483c-ab7a-2942f2f71c0d&env=Sandbox"
22
},
23
"status": "ConsentPending"
24
}
25
}
26
]
27
}
28
}
29
}
Copied!
Once you called the mutation addAccountMemberships, you can reconcile the created memberships matching the email or the phone number and then save the MembershipID that you will use to bind the membership.

Bind a membership

Then you need to ask the invitee to login to Swan and use his access token to call the mutation bindAccountMembership. This will effectively associate the user identity to the accountMembership. If the personal data are matching between what you expected and what the user entered then the invitee can instantly start using your services.
To use this request just replace {{YOUR_ACCOUNTMEMBERSHIP_ID}} by your accountMembershipId.
Request
Response
1
mutation MyMutation () {
2
bindAccountMembership(
3
input: {
4
accountMembershipId: "{{YOUR_ACCOUNTMEMBERSHIP_ID}}"
5
}
6
) {
7
... on BindAccountMembershipSuccessPayload {
8
__typename
9
accountMembership {
10
id
11
version
12
canInitiatePayments
13
canManageAccountMembership
14
canManageBeneficiaries
15
canViewAccount
16
createdAt
17
email
18
legalRepresentative
19
statusInfo {
20
status
21
... on AccountMembershipBindingUserErrorStatusInfo {
22
__typename
23
birthDateMatchError
24
firstNameMatchError
25
idVerifiedMatchError
26
lastNameMatchError
27
restrictedTo {
28
birthDate
29
firstName
30
lastName
31
phoneNumber
32
}
33
status
34
}
35
... on AccountMembershipConsentPendingStatusInfo {
36
__typename
37
status
38
consent {
39
consentUrl
40
createdAt
41
expiredAt
42
id
43
purpose
44
redirectUrl
45
requireSCA
46
startedAt
47
status
48
updatedAt
49
}
50
}
51
... on AccountMembershipDisabledStatusInfo {
52
__typename
53
reason
54
status
55
}
56
... on AccountMembershipEnabledStatusInfo {
57
__typename
58
status
59
}
60
}
61
updatedAt
62
}
63
}
64
}
65
}
Copied!
1
{
2
"data": {
3
"bindAccountMembership": {
4
"__typename": "BindAccountMembershipSuccessPayload",
5
"accountMembership": {
6
"id": "{{YOUR_ACCOUNTMEMBERSHIP_ID}}",
7
"version": "2",
8
"canInitiatePayments": false,
9
"canManageAccountMembership": false,
10
"canManageBeneficiaries": false,
11
"canViewAccount": true,
12
"createdAt": "2021-10-05T13:30:47.070Z",
13
"email": "[email protected]",
14
"legalRepresentative": false,
15
"statusInfo": {
16
"status": "BindingUserError",
17
"__typename": "AccountMembershipBindingUserErrorStatusInfo",
18
"birthDateMatchError": false,
19
"firstNameMatchError": true,
20
"idVerifiedMatchError": false,
21
"lastNameMatchError": true,
22
"restrictedTo": {
23
"birthDate": null,
24
"firstName": "Jane",
25
"lastName": "Dae",
26
"phoneNumber": "+33600000000"
27
}
28
},
29
"updatedAt": "2021-10-05T13:30:55.639Z"
30
}
31
}
32
}
33
}
Copied!
This mutation is special. During the oAuth login you need to addaccountmembership:bind and idverified to the scope, otherwise the mutation won't execute.
As you can see in the request, the mutation was successful but some errors were encountered during the binding. The information provided by both you and the user must match.

Update a membership

To correct a binding user error

Correcting a binding user error is necessary if you want the new member to gain full access to Swan's services. To correct this problem you can use our web banking interface or the updateAccountMembership mutation. This action must be performed by someone who is authorized to manage members, meaning that he has the canManageAccountMemberships right.
To do the same through the API we suggest you use the following query to get the information provided by the user, and then use the updateAccountMembership mutation. Replace{{YOUR_ACCOUNTMEMBERSHIP_ID}} by your accountMembershipId and {{YOUR_REDIRECT_URL}} with the URL you want to redirect the user to.
Query
Request
Response
1
query MyQuery {
2
accountMembership(id: "{{YOUR_ACCOUNTMEMBERSHIP_ID}}") {
3
user {
4
firstName
5
birthDate
6
lastName
7
mobilePhoneNumber
8
}
9
}
10
}
Copied!
1
mutation MyMutation {
2
updateAccountMembership(
3
input: {
4
accountMembershipId: "{{YOUR_ACCOUNTMEMBERSHIP_ID}}"
5
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
6
restrictedTo: {
7
birthDate: ""
8
firstName: ""
9
lastName: ""
10
phoneNumber: ""
11
}
12
}
13
) {
14
... on UpdateAccountMembershipSuccessPayload {
15
__typename
16
consent {
17
consentUrl
18
}
19
}
20
}
21
}
Copied!
1
{
2
"data": {
3
"updateAccountMembership": {
4
"__typename": "UpdateAccountMembershipSuccessPayload",
5
"consent": {
6
"consentUrl": "https://identity.swan.io/consent?consentId=7b25e294-d361-44e8-8a14-5ab8c61553fb&env=Sandbox"
7
}
8
}
9
}
10
}
Copied!

To manage rights

You can grant or revoke rights to a user. This is done using the edit feature in the Members tab on the web banking feature, or by using the mutation updateAccountMembership.
Replace{{YOUR_ACCOUNTMEMBERSHIP_ID}} by your accountMembershipId and {{YOUR_REDIRECT_URL}} with the URL you want to redirect the user to.
Request
Response
1
mutation MyMutation {
2
updateAccountMembership(
3
input: {
4
accountMembershipId: "{{YOUR_ACCOUNTMEMBERSHIP_ID}}"
5
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
6
canManageBeneficiaries: false
7
canManageAccountMembership: false
8
canInitiatePayments: true
9
canViewAccount: true
10
}
11
) {
12
... on UpdateAccountMembershipSuccessPayload {
13
__typename
14
consent {
15
consentUrl
16
}
17
}
18
}
19
}
Copied!
1
{
2
"data": {
3
"updateAccountMembership": {
4
"__typename": "UpdateAccountMembershipSuccessPayload",
5
"consent": {
6
"consentUrl": "https://identity.swan.io/consent?consentId=82fc0dda-d211-45e7-ad02-75f02a0dbb65&env=Sandbox"
7
}
8
}
9
}
10
}
Copied!

Suspend and delete an account membership

There are two ways to lock a user out of an account:
  • suspend the account membership: they will not be able to use the account while being suspended
  • delete the account membership: this will permanently remove the user's account access
Both those actions are available in the web banking interface in the Members tab. Click on the members and you will have the ability to first suspend them, then to delete them.
To achieve the same results through our API you can use the suspendAccountMembership and disableAccountMembership mutations.Try
Request
Response
1
mutation MyMutation {
2
suspendAccountMembership(
3
input: { accountMembershipId: "{{ACCOUNTMEMBERSHIP_ID}}" }
4
) {
5
... on SuspendAccountMembershipSuccessPayload {
6
__typename
7
accountMembership {
8
id
9
}
10
}
11
}
12
}
13
g
Copied!
1
{
2
"data": {
3
"suspendAccountMembership": {
4
"__typename": "SuspendAccountMembershipSuccessPayload",
5
"accountMembership": {
6
"id": "{{ACCOUNTMEMBERSHIP_ID}}"
7
}
8
}
9
}
10
}
Copied!

Next steps

That's it, you are done with the guides of all our current banking features. Now can you easily integrate our services in your product !
There is just one more guide for a technical feature which allows you to be notified instantly about anything happening to your users' accounts: webhooks.
Last modified 2mo ago