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. 
​Discover more about account membership​
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
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}}"
          }
        }
      }
    }
  }
}
​Try it now on the API Explorer​
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
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"
          }
        }
      ]
    }
  }
}
​Try it now on the API Explorer​
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
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"
            }
        }
    }
}
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
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}}"
      }
    }
  }
}
​Try it now on the API Explorer​
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.
​Discover more about rights​
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}}"
      }
    }
  }
}
​Try it now on the API Explorer​
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
mutation MyMutation {
  suspendAccountMembership(
    input: { accountMembershipId: "{{ACCOUNTMEMBERSHIP_ID}}" }
  ) {
    ... on SuspendAccountMembershipSuccessPayload {
      __typename
      accountMembership {
        id
      }
    }
  }
}
g
{
  "data": {
    "suspendAccountMembership": {
      "__typename": "SuspendAccountMembershipSuccessPayload",
      "accountMembership": {
        "id": "{{ACCOUNTMEMBERSHIP_ID}}"
      }
    }
  }
}
​Try it now on the API Explorer​
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 7mo ago