Comment on page
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.
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.
#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. 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}}",
}
}
}
}
The newly created
onboardingUrl
is unique; give it to your user so they can open an account.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}}"
}
}
}
}
The newly created
onboardingUrl
is unique; give it to your user so they can open an account.If an account holder already exists, you can add another account for that holder. The account holder still needs to be "officially" verified by Swan, but verification is quick as Swan already knows the account holder.
- 1.Run the
OnboardCompanyAccountHolder
mutation, using the account holder's information from their other Swan account. - 2.Finalize the onboarding with the new
onboardingID
and the legal rep's user access token. - 3.You'll get a new
accountId
and a newaccountHolder
, both with the statusPending
, which is possible because the legal rep already completed ID verification for the first account. - 4.Swan will verify the account. Since Swan already knows the account holder, verification should be quick.
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"
}
}
}
]
}
}
}
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.
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.
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 representativeidentificationLevels
meets theaccount.legalRepresentativeMembership.AcceptedIdentificationLevels
false
: if the legal representativeidentificationLevels
meets theaccount.legalRepresentativeMembership.AcceptedIdentificationLevels
accountHolder.verificationStatus
: provides information on the account holder compliance review progress
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"
}
},
}
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.Please let your Technical Account Manager know how you'd like your account holders to be notified of their
Verified
status:- Swan emails your account holders directly
- Swan emails you
- No email is sent
Last modified 2mo ago