Create new accounts

To create a new payment account via Swan you need to go through a process. It starts with an onboarding form and ends when the account is opened and all initial limits are lifted.
Create an onboarding link
To onboard your user and create a new account, the first step is to fill an online form that lets Swan instantly create a payment account. The features of a new account are limited until the verification process is over. 
 There are two different types of forms for opening accounts: individual and company.
​Discover more on the onboarding process​
#nocode 
To onboard your users, give them an onboardingUrl. They just have to click it to start opening an account. If you want to do it the #nocode way, just visit the Onboarding tab on the dashboard. You'll find ready-to-go generic URLs for each type of account. Add those URLs to your product and your account opening process will be live in 2 minutes. Alternatively, you can generate a dedicated URL for each individual user. This URL is unique and allows you to pre-fill the form for your user. A benefit of providing dedicated URLs is that it prevents users from inadvertently creating several accounts. 
Individual onboarding
To generate a unique link to the individual onboarding form use the onboardIndividualAccountHolder mutation. You can pre-fill the fields of the form with existing user data.
The following request creates a unique onboardingUrl for Jon Doe, you just need to replace {{YOUR_REDIRECT_URL}}  with a URL to your website. If you don't input your own website, we will redirect the user to our white-label web banking interface.
You need to register the URL in the Dashboard, in API > Redirect URLs.
Request
Response
mutation MyMutation {
  onboardIndividualAccountHolder(
    input: {
      accountCountry: FRA
      accountName: "{{YOUR_ACCOUNT_NAME}}"
      email: "{{YOUR_EMAIL}}"
      employmentStatus: Craftsman
      language: "{{YOUR_LANGUAGE}}"
      monthlyIncome: Between500And1500
      redirectUrl: "{{YOUR_REDIRECT_URL}}"
      residencyAddress: {
        addressLine1: "{{YOUR_ADDRESS}}"
        addressLine2: "{{YOUR_ADDRESS_DETAILS}}"
        city: "{{YOUR_CITY}}"
        country: "{{YOUR_COUNTRY}}"
        postalCode: "{{YOUR_POSTAL_CODE}}"
        state: "{{YOUR_STATE}}"
      }
      taxIdentificationNumber: "{{YOUR_TAX_IDENTIFICATION_NUMBER}}"
    }
  ) {
    ... on OnboardIndividualAccountHolderSuccessPayload {
      __typename
      onboarding {
        id
        statusInfo {
          status
        }
      }
    }
    ... on ForbiddenRejection {
      __typename
      message
    }
    ... on ValidationRejection {
      __typename
      fields {
        code
        message
        path
      }
      message
    }
  }
}
​
{
  "data": {
    "onboardIndividualAccountHolder": {
      "__typename": "OnboardIndividualAccountHolderSuccessPayload",
      "onboarding": {
        "id": "{{ONBOARDING_ID}}",
      }
    }
  }
}
​Try it now on the API Explorer​
The newly created onboardingUrl is unique; give it to your user so they can open an account.
Company onboarding
To generate a unique link to the company onboarding form use the onboardCompanyAccountHolder mutation. You can pre-fill the fields of the form with existing user data.
The following request creates a unique onboardingUrl for the MyBrand company, which is 50% owned by John Doe directly, and 50% owned by Thomas Dupont through a holding company. To use it you just need to replace {{YOUR_REDIRECT_URL}}  with your website's URL. If you don't do this, we will redirect the user to our white-label web banking interface.
You need to register the URL in the Dashboard, in API > Redirect URLs.
GraphQL
Reponse
mutation MyMutation {
  onboardCompanyAccountHolder(
    input: {
      accountCountry: FRA
      accountName: "{{YOUR_ACCOUNT_NAME}}"
      businessActivity: AdministrativeServices
      businessActivityDescription: "{{YOUR_BUSINESS-ACTIVITY-DESCRIPTION}}"
      companyType: Association
      email: "{{YOUR_EMAIL}}"
      individualUltimateBeneficialOwners: {
        type: HasCapital
        birthCity: "{{UBO_BIRTH_CITY}}"
        birthCityPostalCode: "{{UBO_BIRTH_POSTAL_CODE}}"
        birthCountryCode: "{{UBO_BIRTH_COUNTRY}}"
        birthDate: "{{UBO_BIRTH_DATE}}"
        direct: true
        firstName: "{{UBO_FIRST_NAME}}"
        indirect: false
        lastName: "{{UBO_LAST_NAME}}"
        residencyAddress: {
          addressLine1: "{{UBO_ADDRESS}}"
          addressLine2: "{{UBO_ADDRESS_DETAILS}}"
          city: "{{UBO_CITY}}"
          country: "{{UBO_COUNTRY}}"
          postalCode: "{{UBO_POSTAL_CODE}}"
          state: "{{UBO_STATE}}"
        }
        taxIdentificationNumber: "{{UBO_TAX_IDENTIFICATION_NUMBER}}"
        totalCapitalPercentage: 1.5
      }
      isRegistered: true
      language: "{{YOUR_LANGUAGE}}"
      legalRepresentativePersonalAddress: {
        addressLine1: "{{LEGAL_REPRESENTATIVE_ADDRESS}}"
        addressLine2: "{{LEGAL_REPRESENTATIVE_ADDRESS_DETAILS}}"
        city: "{{LEGAL_REPRESENTATIVE_CITY}}"
        country: "{{LEGAL_REPRESENTATIVE_COUNTRY}}"
        postalCode: "{{LEGAL_REPRESENTATIVE_POSTAL_CODE}}"
        state: "{{LEGAL_REPRESENTATIVE_STATE}}"
      }
      monthlyPaymentVolume: MoreThan100000
      name: "{{YOUR_ORGANISATION_NAME}}"
      redirectUrl: "{{YOUR_REDIRECT_URL}}"
      registrationNumber: "{{ORGANISATION_REGISTRATION_NUMBER}}"
      residencyAddress: {
        addressLine1: "{{ORGANISATION_ADDRESS}}"
        addressLine2: "{{ORGANISATION_ADDRESS_DETAILS}}"
        city: "{{ORGANISATION_CITY}}"
        country: "{{ORGANISATION_COUNTRY}}"
        postalCode: "{{ORGANISATION_POSTAL_CODE}}"
        state: "{{ORGANISATION_STATE}}"
      }
      taxIdentificationNumber: "{{ORGANISATION_TAX_IDENTIFICATION_NUMBER}}"
      vatNumber: "{{ORGANISATION_VAT_NUMBER}}"
      typeOfRepresentation: LegalRepresentative
    }
  ) {
    ... on OnboardCompanyAccountHolderSuccessPayload {
      __typename
      onboarding {
        id
      }
    }
    ... on BadRequestRejection {
      __typename
      message
    }
    ... on ForbiddenRejection {
      __typename
      message
    }
    ... on ValidationRejection {
      __typename
      fields {
        code
        message
        path
      }
      message
    }
  }
}
​
​
   
{
  "data": {
    "onboardCompanyAccountHolder": {
      "__typename": "OnboardCompanyAccountHolderSuccessPayload",
      "onboarding": {
        "onboardingUrl": "https://api.banking.sandbox.swan.io/projects/{{PROJECT_ID}}/onboardings/{{ONBOARDING_ID}}"
      }
    }
  }
}
​Try it now with the API Explorer​
The newly created onboardingUrl is unique; give it to your user so they can open an account.
Follow the onboarding process
To complete the onboarding process and open an account, your user must go through our white-label interface. Pre-filling the form streamlines the process for them, so all they have to do is confirm the information is correct.
Onboarding process for individuals and companies
We update the onboarding object in our database every time the user validates a step. Therefore, with a very simple query, you can keep track of all ongoing onboardings. You can use this to send a reminder to clients that have not yet completed the onboarding (and include a link to finish it), create an admin dashboard on your end, get statistics about completion rate, etc.
Request
Response
query MyQuery {
  onboardings {
    edges {
      node {
        onboardingState
        email
        onboardingUrl
        info {
          type
        }
      }
    }
  }
}
​
{
  "data": {
    "onboardings": {
      "edges": [
        {
          "node": {
            "onboardingState": "Completed",
            "email": "{{YOUR_EMAIL}}",
            "onboardingUrl": "https://api.banking.sandbox.swan.io/projects/{{PROJECT_ID}}/onboardings/{{ONBOARDING_ID}}",
            "info": {
              "type": "Individual"
            }
          }
        },
        {
          "node": {
            "onboardingState": "Ongoing",
            "email": null,
            "onboardingUrl": "https://api.banking.sandbox.swan.io/projects/{{PROJECT_ID}}/onboardings/{{ONBOARDING_ID}}",
            "info": {
              "type": "Individual"
            }
          }
        },
        {
          "node": {
            "onboardingState": "Completed",
            "email": "{{YOUR_EMAIL}}",
            "onboardingUrl": "https://api.banking.sandbox.swan.io/projects/{{PROJECT_ID}}/onboardings/{{ONBOARDING_ID}}",
            "info": {
              "type": "Company"
            }
          }
        },
        {
          "node": {
            "onboardingState": "Ongoing",
            "email": "{{YOUR_EMAIL}}",
            "onboardingUrl": "https://api.banking.sandbox.swan.io/projects/{{PROJECT_ID}}/onboardings/{{ONBOARDING_ID}}",
            "info": {
              "type": "Company"
            }
          }
        }
      ]
    }
  }
}
​Try it now with the API Explorer ​
First authentication and callback
At Swan, a user (the actual human behind the screen) is identified using their phone number. During the first login we verify the phone number by SMS, and attach the user's profile to it. When we ask the user to authenticate using their smartphone what we do is bind the onboarding process to the user. 
Authentication works differently depending on the device used:
on mobile: a verification code will be sent to confirm the phone number;
on desktop: a link will be sent to confirm the phone number and open the verification process on the smartphone.
Once the authentication is done we will redirect the user to either:
1.our white-label web banking interface if you used the public URL or didn't specify a redirectUrl in the API;
2.the provided redirectUrl if you created an onboarding through the API.
 In the second case, we will add two query parameters to the URL :
state: the one you configured in the mutation to create the onboarding URL, it allows you to link the onboarding to the user created
code: an authorization code to get a user access token.
​Discover more about authentication at Swan​
When the authentication is done you need to store both the user access token and the refresh token. That allows you to execute queries and mutations on behalf of the user, without having them authenticate every time they use your product. Of course, we will ask for confirmation through the smartphone for sensitive operations.
Verification Process
Two mandatory steps make up the verification process at Swan (also known as KYC/Know Your Customer):
identity verification: done automatically during SCA, we verify that the user is really who they say they are;
compliance review: done by our compliance department, we collect and validate documents to be sure that a user is allowed to open a Swan account for themselves or their company.
At Swan, document collection is handled in two ways. The first way is to request the required documents by email, to either the end-user or the partner. The second way is by exposing the request in our API, allowing our partner to maintain their existing relationship with their user. Find more information about the documents we ask for from either an individual or a company.  
In the API, these two mandatory steps are represented by these data: 
account.legalRepresentativeMembership.hasRequiredIdentificationLevel:
true:  if the legal representative identificationLevels meets the account.legalRepresentativeMembership.AcceptedIdentificationLevels
false: if the legal representative identificationLevels meets the account.legalRepresentativeMembership.AcceptedIdentificationLevels
accountHolder.verificationStatus: provides information on the account holder compliance review progress
​Discover more on the KYC process​
Request
Response
query MyQuery {
  accountHolders {
    edges {
      node {
        accounts {
          edges {
            node {
              legalRepresentativeMembership {
                hasRequiredIdentificationLevel
              }
            }
          }
        }
        verificationStatus
      }
    }
  }
}
​
{
  "data": {
    "accountHolders": {
      "edges": [
        {
          "node": {
            "accounts": {
              "edges": [
                {
                  "node": {
                    "legalRepresentativeMembership": {
                      "hasRequiredIdentificationLevel": false
                    }
                  }
                }
              ]
            },
            "verificationStatus": "NotStarted"
          }
        },
        {
          "node": {
            "accounts": {
              "edges": [
                {
                  "node": {
                    "legalRepresentativeMembership": {
                      "hasRequiredIdentificationLevel": true
                    }
                  }
                }
              ]
            },
            "verificationStatus": "Pending"
          }
        },
        
}
​Try it now with the API Explorer​
In the Sandbox, you can simulate different use cases through the Dashboard using this data:
identificationLevels : go to Sandbox Users > Edit and select the status on the identification status and identification level fields;
verificationStatus : go to Event Simulator > Account Holder input the Account Holder Id and select the status on the Verification Status field.
When the verificationStatus is Verified, then the account is unlimited, and all available banking features may be used.
​
Next steps
Learn how to manage accounts and access account data.​
Or you can also get a more in-depth view of the payment account.​
Guide - Previous
Use our API
Next - Guide
Manage accounts and IBANs
Last modified 2mo ago