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

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
mutation MyMutation {
addAccountMembership(
input: {
accountId: "{{YOUR_ACCOUNT_ID}}"
email: "[email protected]"
restrictedTo: {
firstName: "Jane"
lastName: "Dae"
phoneNumber: "+33600000000"
}
canViewAccount: true
canManageBeneficiaries: false
canInitiatePayments: false
canManageAccountMembership: false
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
}
) {
... on AddAccountMembershipSuccessPayload {
__typename
accountMembership {
id
statusInfo {
... on AccountMembershipConsentPendingStatusInfo {
__typename
consent {
consentUrl
}
}
}
}
}
}
}
{
"data": {
"addAccountMembership": {
"__typename": "AddAccountMembershipSuccessPayload",
"accountMembership": {
"id": "{{YOUR_ACCOUNT_MEMBERSHIP_ID}}",
"statusInfo": {
"__typename": "AccountMembershipConsentPendingStatusInfo",
"consent": {
"consentUrl": "{{YOUR_CONSENT_URL}}"
}
}
}
}
}
}
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
mutation MyMutation {
addAccountMemberships(
input: {
accountId: "{{YOUR_ACCOUNT_ID}}"
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
memberships: [
{
email: "[email protected]"
restrictedTo: {
firstName: "Jane"
lastName: "Dae"
birthDate: "1980-02-20"
phoneNumber: "+33600000000"
}
canViewAccount: true
canManageBeneficiaries: true
canInitiatePayments: true
canManageAccountMembership: true
}
{
email: "[email protected]"
restrictedTo: {
firstName: "Brad"
lastName: "Johnson"
phoneNumber: "+33600000000"
}
canViewAccount: true
canManageBeneficiaries: false
canInitiatePayments: false
canManageAccountMembership: false
}
]
}
)
}
{
"data": {
"addAccountMemberships": {
"__typename": "AddAccountMembershipsSuccessPayload",
"accountMemberships": [
{
"id": "{{YOUR_ACCOUNT_MEMBERSHIP_ID}}",
"statusInfo": {
"__typename": "AccountMembershipConsentPendingStatusInfo",
"consent": {
"consentUrl": "{{YOUR_CONSENT_URL}}"
},
"status": "ConsentPending"
}
},
{
"id": "{{YOUR_ACCOUNT_MEMBERSHIP_ID}}",
"statusInfo": {
"__typename": "AccountMembershipConsentPendingStatusInfo",
"consent": {
"consentUrl": "{{YOUR_CONSENT_URL}}"
},
"status": "ConsentPending"
}
}
]
}
}
}
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. 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
mutation MyMutation () {
bindAccountMembership(
input: {
accountMembershipId: "{{YOUR_ACCOUNTMEMBERSHIP_ID}}"
}
) {
... on BindAccountMembershipSuccessPayload {
__typename
accountMembership {
id
version
canInitiatePayments
canManageAccountMembership
canManageBeneficiaries
canViewAccount
createdAt
email
legalRepresentative
statusInfo {
status
... on AccountMembershipBindingUserErrorStatusInfo {
__typename
birthDateMatchError
firstNameMatchError
idVerifiedMatchError
lastNameMatchError
restrictedTo {
birthDate
firstName
lastName
phoneNumber
}
status
}
... on AccountMembershipConsentPendingStatusInfo {
__typename
status
consent {
consentUrl
createdAt
expiredAt
id
purpose
redirectUrl
requireSCA
startedAt
status
updatedAt
}
}
... on AccountMembershipDisabledStatusInfo {
__typename
reason
status
}
... on AccountMembershipEnabledStatusInfo {
__typename
status
}
}
updatedAt
}
}
}
}
{
"data": {
"bindAccountMembership": {
"__typename": "BindAccountMembershipSuccessPayload",
"accountMembership": {
"id": "{{YOUR_ACCOUNTMEMBERSHIP_ID}}",
"version": "2",
"canInitiatePayments": false,
"canManageAccountMembership": false,
"canManageBeneficiaries": false,
"canViewAccount": true,
"createdAt": "2021-10-05T13:30:47.070Z",
"email": "[email protected]",
"legalRepresentative": false,
"statusInfo": {
"status": "BindingUserError",
"__typename": "AccountMembershipBindingUserErrorStatusInfo",
"birthDateMatchError": false,
"firstNameMatchError": true,
"idVerifiedMatchError": false,
"lastNameMatchError": true,
"restrictedTo": {
"birthDate": null,
"firstName": "Jane",
"lastName": "Dae",
"phoneNumber": "+33600000000"
}
},
"updatedAt": "2021-10-05T13:30:55.639Z"
}
}
}
}
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.
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
query MyQuery {
accountMembership(id: "{{YOUR_ACCOUNTMEMBERSHIP_ID}}") {
user {
firstName
birthDate
lastName
mobilePhoneNumber
}
}
}
mutation MyMutation {
updateAccountMembership(
input: {
accountMembershipId: "{{YOUR_ACCOUNT_MEMBERSHIP_ID}}"
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
restrictedTo: {
birthDate: ""
firstName: ""
lastName: ""
phoneNumber: ""
}
}
) {
... on UpdateAccountMembershipSuccessPayload {
__typename
consent {
consentUrl
}
}
}
}
{
"data": {
"updateAccountMembership": {
"__typename": "UpdateAccountMembershipSuccessPayload",
"consent": {
"consentUrl": "{{YOUR_CONSENT_URL}}"
}
}
}
}
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
mutation MyMutation {
updateAccountMembership(
input: {
accountMembershipId: "{{YOUR_ACCOUNTMEMBERSHIP_ID}}"
consentRedirectUrl: "{{YOUR_REDIRECT_URL}}"
canManageBeneficiaries: false
canManageAccountMembership: false
canInitiatePayments: true
canViewAccount: true
}
) {
... on UpdateAccountMembershipSuccessPayload {
__typename
consent {
consentUrl
}
}
}
}
{
"data": {
"updateAccountMembership": {
"__typename": "UpdateAccountMembershipSuccessPayload",
"consent": {
"consentUrl": "{{YOUR_CONSENT_URL}}"
}
}
}
}
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
mutation MyMutation {
suspendAccountMembership(
input: { accountMembershipId: "{{ACCOUNTMEMBERSHIP_ID}}" }
) {
... on SuspendAccountMembershipSuccessPayload {
__typename
accountMembership {
id
}
}
}
}
g
{
"data": {
"suspendAccountMembership": {
"__typename": "SuspendAccountMembershipSuccessPayload",
"accountMembership": {
"id": "{{ACCOUNTMEMBERSHIP_ID}}"
}
}
}
}
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