Guide
API
PROCESS
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 can 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. 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
1
mutation MyMutation {
2
onboardIndividualAccountHolder(
3
input: {
4
email: "[email protected]"
5
employmentStatus: Employee
6
language: "us-US"
7
monthlyIncome: Between500And1500
8
redirectUrl: "{{YOUR_REDIRECT_URL}}"
9
}
10
) {
11
... on OnboardIndividualAccountHolderSuccessPayload {
12
__typename
13
onboarding {
14
id
15
onboardingUrl
16
onboardingState
17
}
18
}
19
... on ForbiddenRejection {
20
__typename
21
message
22
}
23
}
24
}
25
Copied!
1
{
2
"data": {
3
"onboardIndividualAccountHolder": {
4
"__typename": "OnboardIndividualAccountHolderSuccessPayload",
5
"onboarding": {
6
"id": "{{ONBOARDING_ID}}",
7
"onboardingUrl": "https://api.banking.sandbox.swan.io/projects/{{PROJECT_ID}}/onboardings/{{ONBOARDING_ID}}",
8
"onboardingState": "Ongoing"
9
}
10
}
11
}
12
}
Copied!
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
1
mutation MyMutation {
2
onboardCompanyAccountHolder(
3
input: {
4
accountName: "MyBrand account"
5
businessActivity: InformationAndCommunication
6
businessActivityDescription: "MyBrand is a marketing company."
7
companyType: Company
8
email: "[email protected]"
9
individualUltimateBeneficialOwners: [
10
{
11
type: HasCapital
12
birthCity: "New York"
13
birthCityPostalCode: "10001"
14
birthDate: "01/01/1980"
15
direct: true
16
birthCountryCode: "USA"
17
firstName: "John"
18
lastName: "Doe"
19
totalCapitalPercentage: 50
20
}
21
{
22
type: HasCapital
23
birthCity: "Paris"
24
birthCityPostalCode: "75001"
25
birthDate: "01/01/1990"
26
birthCountryCode: "FRA"
27
firstName: "Thomas"
28
lastName: "Dupont"
29
totalCapitalPercentage: 50
30
indirect:true
31
}
32
]
33
isRegistered: true
34
language: "en-EN"
35
monthlyPaymentVolume: MoreThan100000
36
name: "MyBrand"
37
redirectUrl: "{{YOUR_REDIRECT_URL}}"
38
registrationNumber: "123456789"
39
}
40
) {
41
... on OnboardCompanyAccountHolderSuccessPayload {
42
__typename
43
onboarding {
44
onboardingUrl
45
}
46
}
47
}
48
}
49
Copied!
1
{
2
"data": {
3
"onboardCompanyAccountHolder": {
4
"__typename": "OnboardCompanyAccountHolderSuccessPayload",
5
"onboarding": {
6
"onboardingUrl": "https://api.banking.sandbox.swan.io/projects/{{PROJECT_ID}}/onboardings/{{ONBOARDING_ID}}"
7
}
8
}
9
}
10
}
Copied!
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.
GraphQL
1
query MyQuery {
2
onboardings {
3
edges {
4
node {
5
onboardingState
6
email
7
onboardingUrl
8
info {
9
type
10
}
11
}
12
}
13
}
14
}
15
Copied!
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 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.
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 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
1
query MyQuery {
2
user {
3
id
4
idVerified
5
}
6
accountHolders {
7
edges {
8
node {
9
verificationStatus
10
id
11
}
12
}
13
}
14
}
15
Copied!
1
{
2
"data": {
3
"user": {
4
"id": "2f90e409-fae7-40f6-af47-6320f31c5bd9",
5
"idVerified": true
6
},
7
"accountHolders": {
8
"edges": [
9
{
10
"node": {
11
"verificationStatus": "Pending",
12
"id": "649f7c44-2c03-4231-9b2a-95b09934a91d"
13
}
14
}
15
]
16
}
17
}
18
}
Copied!
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.Next steps
Last modified 3mo ago