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: {
email: "{{YOUR_EMAIL}}"
employmentStatus: Employee
language: "en-US"
monthlyIncome: Between500And1500
redirectUrl: "{{YOUR_REDIRECT_URL}}"
}
) {
... on OnboardIndividualAccountHolderSuccessPayload {
__typename
onboarding {
id
onboardingUrl
onboardingState
}
}
... on ForbiddenRejection {
__typename
message
}
}
}
{
"data": {
"onboardIndividualAccountHolder": {
"__typename": "OnboardIndividualAccountHolderSuccessPayload",
"onboarding": {
"id": "{{ONBOARDING_ID}}",
"onboardingUrl": "https://api.banking.sandbox.swan.io/projects/{{PROJECT_ID}}/onboardings/{{ONBOARDING_ID}}",
"onboardingState": "Ongoing"
}
}
}
}
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: {
accountName: "MyBrand account"
businessActivity: InformationAndCommunication
businessActivityDescription: "MyBrand is a marketing company."
companyType: Company
email: "[email protected]"
individualUltimateBeneficialOwners: [
{
type: HasCapital
birthCity: "New York"
birthCityPostalCode: "10001"
birthDate: "01/01/1980"
direct: true
birthCountryCode: "USA"
firstName: "John"
lastName: "Doe"
totalCapitalPercentage: 50
}
{
type: HasCapital
birthCity: "Paris"
birthCityPostalCode: "75001"
birthDate: "01/01/1990"
birthCountryCode: "FRA"
firstName: "Thomas"
lastName: "Dupont"
totalCapitalPercentage: 50
indirect: true
}
]
isRegistered: true
language: "en"
monthlyPaymentVolume: MoreThan100000
name: "MyBrand"
redirectUrl: "{{REDIRECT_URL}}"
registrationNumber: "123456789"
}
) {
... on OnboardCompanyAccountHolderSuccessPayload {
__typename
onboarding {
onboardingUrl
}
}
... on BadRequestRejection {
__typename
message
}
... on ForbiddenRejection {
__typename
message
}
... on ValidationRejection {
__typename
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.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 it's smartphone what we do is bind the onboarding process to the user.
The authentication is different based 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 specified a
redirectUrlin the API; - 2.the provided
redirectUrlif you created an onboarding through the API.
In the second case, we will add two query parameters to the URL :
- state : is the one you configured in the mutation to create the onboarding URL, it allows you to link the onboarding to the user created
- code : is 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 query and mutation 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 any sensitive operation.
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 bank account for themselves or their company.
At Swan, document collection is handled in two ways. We ask for the required documents by either emailing the end-user directly or emailing the partner so they can maintain their existing relationship with their user. Find more information about the documents we ask for in our user support documentation for an individual or a company.
In the API, these two mandatory steps are represented by two data:
idVerified and verificationStatus. The first one is a boolean while the second one describes all the steps of the compliance review.Request
Response
query MyQuery {
user {
id
idVerified
}
accountHolders {
edges {
node {
verificationStatus
id
}
}
}
}
{
"data": {
"user": {
"id": "{{YOUR_USER_ID}}",
"idVerified": true
},
"accountHolders": {
"edges": [
{
"node": {
"verificationStatus": "Pending",
"id": "{{YOUR_USER_ID}}"
}
}
]
}
}
}
In the Sandbox, both data are editable through the Dashboard:
identificationStatus: go to Sandbox Users > Edit and select the status on the Identification Status field;verificationStatus: go to Event Simulator > Account Holder input the Account Holder Id and select the status on the Verification Status field.
When
identificationStatusis ValidIdentity and verificationStatus is Verified, then the account is unlimited, and all available banking features may be used.Last modified 1mo ago