Swan User Signup Implementation Guide

Swan's User Signup workflow creates verified individuals who can access banking services through your application. The process includes phone verification, personal information collection, passcode creation, and conditional identification requirements.

Prerequisites

• Swan Dashboard and project access
• Authentication configured in Dashboard

Signup Flow Overview

View end-user journey

Signup Implementation

Phase 1: Initiate Authentication

Generate the OAuth2 signup URL

Create the authorization URL that starts the user signup process.

Basic signup example

https://oauth.swan.io/oauth2/auth?response_type=code&client_id=$YOUR_CLIENT_ID
&redirect_uri=$YOUR_REDIRECT_URI&scope=openid%20offline&state=$YOUR_STATE_PARAMETER

Important Notes

• Authorization codes expire after 10 minutes
• Redirect URI must exactly match Dashboard registration
• State parameter is required for CSRF protection
• PKCE is supported but requires contacting Swan to enable

URL construction guide →

With pre-filled user data

https://oauth.swan.io/oauth2/auth?response_type=code&client_id=$YOUR_CLIENT_ID
&redirect_uri=$YOUR_REDIRECT_URI&scope=openid%20offline&state=$YOUR_STATE_PARAMETER
&phoneNumber=%2B33689788967&firstName=Jean&lastName=Dupont&birthDate=1990-05-15

Phone Number

If you don't provide their number in the pre-filled data, the user will be prompted to manually enter it for verification. Remember to encode the phone number's + symbol like so: %2B

Optional parameters →

With forced identification

https://oauth.swan.io/oauth2/auth?response_type=code&client_id=$YOUR_CLIENT_ID
&redirect_uri=$YOUR_REDIRECT_URI&scope=openid%20offline&state=$YOUR_STATE_PARAMETER
&identificationLevel=Auto

When to Include Identity Verification

Add the identificationLevel parameter when you need users to complete identity verification during signup. This ensures verified users before they access your application features.

User opens signup link

The user clicks the generated URL to begin the Swan signup process.

Integration Notes

• This step initiates the signup process, which is then automated by Swan
• Refer to Phase 3 and Phase 5 for important friction reduction concerns
• Refer to the next integration steps to skip the user journey altogether

Phase 2: Phone Verification

Phone verification steps depend on the device type, however all users ultimately end up on their mobile device for PSD2 compliance and to enable biometric authentication for future logins:

🖥️ Desktop Users:

• Receive SMS with verification link
• Must open link on mobile device to continue verification

📱 Mobile Users:

• Receive SMS with 6-digit verification code
• Enter code directly to verify number

SMS delivery is handled automatically by Swan. Verification success triggers continuation to Phase 3.

Phase 3: Personal Information Collection

Friction Reduction

If you include this information when creating the sign-up link, the user won't need to enter it again during the signup process. This information must match the information that appears on their identity documents.

For all available pre-filling parameters, see Optional URL Parameters.

User provides core personal details required for account creation:

Field	Required	OAuth Parameter	Format	Purpose
First name	✅	firstName	String	User's legal first name
Last name	✅	lastName	String	User's legal last name
Birth date	✅	birthDate	YYYY-MM-DD	Date of birth for verification

Critical Data Accuracy

Be very careful to collect the correct information if you use pre-filling parameters. This data will be used to reset the passcode should the user forget it.

Phase 4: Passcode Setup

The user sets a 6-digit passcode. It is linked to their mobile phone number and is the same for all projects. Swan can request it anytime the user needs to consent to a sensitive operation.

Branching Point

• If a user isn't required to complete identification, they skip to Phase 8. They may need to complete verification later to access certain features.
• If a user is required to complete identification, they continue with Phases 5 and 6

Phase 5: Extended Information Collection

Identification Flow Only

This only triggers when the user is required to complete identification

Phase 5.a: Birth Information Collection

User provides additional birth details:

Field	API Parameter	Format	Purpose
Birth city	birthCity	String	City where account holder was born
Birth country	birthCountry	String (ISO 3166-1)	Country of birth for verification
Nationality	nationality	String (ISO 3166-1)	Account holder's legal nationality

Friction Reduction

Like core personal information, birth information can be pre-filled using Optional URL Parameters to reduce user friction. If you include this information in their signup link, they won't need to enter it again.

Phase 5.b: Residency Information Collection

The user provides any additional data needed, which varies depending on the identification process:

Identification Process	Required Residency Information	OAuth Parameters for Prefilling
QES	Full address	residencyAddress residencyAddressCity residencyAddressCountry residencyAddressPostalCode
PVID	Country only	residencyAddressCountry
Expert	Country only	residencyAddressCountry

Friction Reduction

Residency data can also be pre-filled using Optional URL Parameters to reduce user friction.

Success is indicated by continuation to Phase 6.

Phase 6: Information Confirmation

Identification Flow Only

This only triggers when the user is required to complete identification

Phase 6.a: User Review

The user reviews and confirms all provided information. They can modify their information before confirming. This step prevents data entry errors and ensures regulatory compliance before proceeding to the validation of their identity verification.

Phase 6.b: Swan Validation

Swan verifies the user's identity and returns a success notification that they have officially completed identification.

Success is indicated by continuation to Phase 7.

Phase 7: Optional Biometric Setup

The user optionally sets up biometrics, if desired and available on their mobile device. Biometrics typically include face or fingerprint authentication.

Phase 8: Access Granted

After signing up, your user can start using Swan based on their account permissions.

How they get to their account depends on your integration:

Integration	Access Method
No-code Web Banking	Swan redirects your user to the interface automatically
Full API or Customized open source frontend	Your user is redirected to the redirectUrl you supplied when creating the OAuth authorization URL

Next Integration Steps

1. Handle OAuth redirect and get the authorization code
2. Exchange the code for access tokens using the token endpoint
3. Store tokens securely for subsequent API calls
4. Enable banking features based on the user's account permissions

Error Handling

Common authentication errors include:

• Authorization code expired (10-minute limit)
• Invalid redirect URI
• Invalid client credentials

For detailed error handling, see Swan's Error Documentation.