Skip to content

Commit 94b6383

Browse files
ntombingntombing
authored
Merge pull request #413 from swan-io/DOC-1148/multiple-accounts
Doc 1148/multiple accounts
2 parents a80f8ee + e5cfe07 commit 94b6383

File tree

4 files changed

+369
-1
lines changed

4 files changed

+369
-1
lines changed

‎docs/preview/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,5 +28,6 @@ These features are in beta and available for testing. We use feedback to refine
2828
| Feature | Description | ETA |
2929
|---------|-------------|-----|
3030
| <span style={{whiteSpace: 'nowrap'}}>[Card insurance](card-insurance)</span> | Comprehensive insurance coverage for Swan-issued cards including theft, fraud, and travel protection | <span style={{whiteSpace: 'nowrap'}}>In private beta</span> |
31+
| <span style={{whiteSpace: 'nowrap'}}>[Multiple accounts](multiple-accounts)</span> | Enable one company account holder to create additional accounts without repeating onboarding or KYB | <span style={{whiteSpace: 'nowrap'}}>In private beta</span> |
3132

3233
</div>

‎docs/preview/multiple-accounts/guide-multiple-accounts-integration.mdx‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
title: Create multiple accounts
3+
---
4+
5+
This guide explains how to open additional accounts linked to one account holder.
6+
7+
## Guide {#guide}
8+
9+
1. Call the `openAccount` mutation (line 2).
10+
2. Include the `accountHolderId` (line 4).
11+
3. Add the `language` parameter (optional) to select the [account language](/topics/accounts/#language). If not specified, English (`en`) is used as the default language (line 5).
12+
4. Add a `name` parameter (optional) for the account. If not specified, "My account" is used as the default name (line 6).
13+
5. Use the `OpenAccountSuccessPayload` payload (line 9) to specify the information you'd like to receive about the additional account.
14+
6. Include error handling for all rejection types defined in the `OpenAccountPayload` union (lines 26-73).
15+
16+
## Mutation {#mutation}
17+
18+
<a href="https://explorer.swan.io?query=bXV0YXRpb24gQ3JlYXRlQWNjb3VudCB7CiAgb3BlbkFjY291bnQoCiAgICBpbnB1dDogewogICAgICBhY2NvdW50SG9sZGVySWQ6ICIkQUNDT1VOVF9IT0xERVJfSUQiCiAgICAgIGxhbmd1YWdlOiBlbgogICAgICBuYW1lOiAiVGF4ZXMiCiAgICB9CiAgKSB7CiAgICAuLi4gb24gT3BlbkFjY291bnRTdWNjZXNzUGF5bG9hZCB7CiAgICAgIF9fdHlwZW5hbWUKICAgICAgYWNjb3VudCB7CiAgICAgICAgQklDCiAgICAgICAgSUJBTgogICAgICAgIGNvdW50cnkKICAgICAgICBjdXJyZW5jeQogICAgICAgIGlkCiAgICAgICAgbGFuZ3VhZ2UKICAgICAgICBuYW1lCiAgICAgICAgcGF5bWVudExldmVsCiAgICAgICAgcGF5bWVudEFjY291bnRUeXBlCiAgICAgICAgc3RhdHVzSW5mbyB7CiAgICAgICAgICBzdGF0dXMKICAgICAgICB9CiAgICAgIH0KICAgIH0KICAgIC4uLiBvbiBJbnRlcm5hbEVycm9yUmVqZWN0aW9uIHsKICAgICAgX190eXBlbmFtZQogICAgICBtZXNzYWdlCiAgICB9CiAgICAuLi4gb24gRm9yYmlkZGVuUmVqZWN0aW9uIHsKICAgICAgX190eXBlbmFtZQogICAgICBtZXNzYWdlCiAgICB9CiAgICAuLi4gb24gQWNjb3VudEhvbGRlck5vdEZvdW5kUmVqZWN0aW9uIHsKICAgICAgX190eXBlbmFtZQogICAgICBtZXNzYWdlCiAgICB9CiAgICAuLi4gb24gQWNjb3VudEhvbGRlclR5cGVOb3RFbGlnaWJsZVJlamVjdGlvbiB7CiAgICAgIF9fdHlwZW5hbWUKICAgICAgbWVzc2FnZQogICAgfQogICAgLi4uIG9uIEFjY291bnRIb2xkZXJTdGF0dXNOb3RFbGlnaWJsZVJlamVjdGlvbiB7CiAgICAgIF9fdHlwZW5hbWUKICAgICAgbWVzc2FnZQogICAgfQogICAgLi4uIG9uIEFjY291bnRIb2xkZXJWZXJpZmljYXRpb25TdGF0dXNOb3RFbGlnaWJsZVJlamVjdGlvbiB7CiAgICAgIF9fdHlwZW5hbWUKICAgICAgbWVzc2FnZQogICAgfQogICAgLi4uIG9uIEFjY291bnRIb2xkZXJBY2NvdW50c1R5cGVOb3RFbGlnaWJsZVJlamVjdGlvbiB7CiAgICAgIF9fdHlwZW5hbWUKICAgICAgbWVzc2FnZQogICAgfQogICAgLi4uIG9uIEFjY291bnRIb2xkZXJBY2NvdW50c1N0YXR1c05vdEVsaWdpYmxlUmVqZWN0aW9uIHsKICAgICAgX190eXBlbmFtZQogICAgICBtZXNzYWdlCiAgICB9CiAgICAuLi4gb24gQWNjb3VudE1lbWJlcnNoaXBOb3RFbGlnaWJsZVJlamVjdGlvbiB7CiAgICAgIF9fdHlwZW5hbWUKICAgICAgbWVzc2FnZQogICAgfQogICAgLi4uIG9uIEFjY291bnRIb2xkZXJQcm9qZWN0U2V0dGluZ3NOb3RFbGlnaWJsZVJlamVjdGlvbiB7CiAgICAgIF9fdHlwZW5hbWUKICAgICAgbWVzc2FnZQogICAgfQogICAgLi4uIG9uIEFjY291bnRIb2xkZXJBY2NvdW50c0NyZWF0aW9uTGltaXRSZWplY3Rpb24gewogICAgICBfX3R5cGVuYW1lCiAgICAgIG1lc3NhZ2UKICAgIH0KICAgIC4uLiBvbiBQcm9qZWN0U2V0dGluZ3NOb3RGb3VuZFJlamVjdGlvbiB7CiAgICAgIF9fdHlwZW5hbWUKICAgICAgbWVzc2FnZQogICAgfQogIH0KfQo%3D&tab=api" className="explorer-badge">Open in API Explorer</a>
19+
20+
```graphql {2,4-6,9} showLineNumbers
21+
mutation CreateAccount {
22+
openAccount(
23+
input: {
24+
accountHolderId: "$ACCOUNT_HOLDER_ID"
25+
language: en
26+
name: "Taxes"
27+
}
28+
) {
29+
... on OpenAccountSuccessPayload {
30+
__typename
31+
account {
32+
BIC
33+
IBAN
34+
country
35+
currency
36+
id
37+
language
38+
name
39+
paymentLevel
40+
paymentAccountType
41+
statusInfo {
42+
status
43+
}
44+
}
45+
}
46+
... on InternalErrorRejection {
47+
__typename
48+
message
49+
}
50+
... on ForbiddenRejection {
51+
__typename
52+
message
53+
}
54+
... on AccountHolderNotFoundRejection {
55+
__typename
56+
message
57+
}
58+
... on AccountHolderTypeNotEligibleRejection {
59+
__typename
60+
message
61+
}
62+
... on AccountHolderStatusNotEligibleRejection {
63+
__typename
64+
message
65+
}
66+
... on AccountHolderVerificationStatusNotEligibleRejection {
67+
__typename
68+
message
69+
}
70+
... on AccountHolderAccountsTypeNotEligibleRejection {
71+
__typename
72+
message
73+
}
74+
... on AccountHolderAccountsStatusNotEligibleRejection {
75+
__typename
76+
message
77+
}
78+
... on AccountMembershipNotEligibleRejection {
79+
__typename
80+
message
81+
}
82+
... on AccountHolderProjectSettingsNotEligibleRejection {
83+
__typename
84+
message
85+
}
86+
... on AccountHolderAccountsCreationLimitRejection {
87+
__typename
88+
message
89+
}
90+
... on ProjectSettingsNotFoundRejection {
91+
__typename
92+
message
93+
}
94+
}
95+
}
96+
```
97+
98+
## Payload {#payload}
99+
100+
The mutation returns all of the requested information such as the account details, the `accountId` (line 10) and the account `status` (line 16).
101+
102+
```json {10,16} showLineNumbers
103+
{
104+
"data": {
105+
"openAccount": {
106+
"__typename": "OpenAccountSuccessPayload",
107+
"account": {
108+
"IBAN": "FR7699999001007663023512982",
109+
"BIC": "SWNBFR22",
110+
"currency": "EUR",
111+
"country": "FRA",
112+
"id": "9217e570-f785-4c88-be55-dc8b626ca8c7",
113+
"language": "en",
114+
"name": "Taxes",
115+
"paymentLevel": "Unlimited",
116+
"paymentAccountType": "PaymentService",
117+
"statusInfo": {
118+
"status": "Opened"
119+
}
120+
}
121+
}
122+
}
123+
}
124+
```

‎docs/preview/multiple-accounts/multiple-accounts.mdx‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
---
2+
title: Multiple accounts
3+
---
4+
5+
Create additional accounts for an existing company account holder without repeating the onboarding and Know Your Business (KYB) processes.
6+
7+
:::info Specific coverage
8+
Contact your Strategic Account Manager (SAM) to request the multiple accounts feature.
9+
:::
10+
11+
## Overview {#overview}
12+
13+
**Multiple accounts allow a single company to create additional Swan accounts** under the same legal entity. These accounts share the same registration number and [local IBAN](/topics/accounts/ibans/#local) as the first account created during onboarding.
14+
15+
Each account operates independently with its own IBAN, balances, and transaction flows, making it easy to create additional accounts for specific business needs.
16+
17+
They have the same capabilities as regular accounts, including issuing and accepting all payment types (e.g., [card payments](/topics/payments/cards/), [SEPA Credit Transfers](/topics/payments/credit-transfers/sepa/)).
18+
19+
To accept payments, each account requires its own [merchant profile review](/topics/merchants/#profiles), so a new profile and payment method must be requested for each additional account created.
20+
21+
## Eligibility {#eligibility}
22+
23+
Multiple accounts are available for **[company account](/topics/onboarding/company/) types**, which include:
24+
25+
- Registered companies
26+
- Self-employed workers
27+
- Associations or non-profit organizations
28+
29+
:::info Individual accounts
30+
Individuals may create additional accounts. A new onboarding process is required, but Know Your Customer (KYC) isn't repeated.
31+
:::
32+
33+
## Requirements {#requirements}
34+
35+
### Legal representative requirements {#legal-rep-requirements}
36+
37+
All accounts under the same account holder share the **same [legal representative](/topics/onboarding/company/#representatives)** (account admin). Only the legal representative of the first account can create additional accounts. Changes to the legal representative follow the standard process but must be applied across all accounts belonging to the same account holder.
38+
39+
### Account holder requirements {#account-holder-requirements}
40+
41+
The following criteria must be met by the account holder:
42+
43+
| **Requirement** | **Value** |
44+
| --- | --- |
45+
| `accountHolder.verificationStatus` | `Verified` |
46+
| `accountHolder.status` | `Enabled` |
47+
| `accountHolder.type` | `Company` |
48+
| `accountHolder.account.status` | `Opened` |
49+
50+
## Key benefits and use cases {#key-benefits}
51+
52+
### Operational benefits {#operational-benefits}
53+
54+
- Skip onboarding for each new account.
55+
- Share KYB verification across all accounts, reducing duplicate checks.
56+
- Perform re-KYB verification on one account holder across all accounts.
57+
58+
### Use cases {#use-cases}
59+
60+
- **Freelancers** can use this feature for tax management.
61+
- **Small and medium businesses (SMBs)** often use separate accounts for advanced spending management, like managing financial flows by supplier, department, or region.
62+
- **Homeowner associations (HOAs)** can use an "operating account" for day-to-day expenses and a "reserve account" for common area expenses (e.g. repairs).
63+
64+
## Feature activation {#feature-activation}
65+
66+
The multiple accounts feature is available to all partners, but **isn't activated** by default. Contact your Strategic Account Manager (SAM) to request activation before creating accounts.
67+
68+
When requesting the feature, make sure to include:
69+
- The purpose for creating additional accounts.
70+
- The number of accounts needed.
71+
72+
:::caution Compliance review
73+
Your request is subject to a **compliance review**, as well as a contract and pricing review if accepted.
74+
:::
75+
76+
## API implementation {#implementation}
77+
78+
Once the feature is activated, you can create additional accounts.
79+
80+
1. Call the `openAccount` mutation.
81+
:::info Multiple accounts guide
82+
Follow the [**step-by-step guide**](guide-multiple-accounts-integration.mdx) to create multiple accounts.
83+
:::
84+
85+
2. Collect the legal representative's confirmation in your banking app. A consent URL or Strong Customer Authentication (SCA) is not required.
86+
87+
:::caution Confirmation
88+
You must include a clear confirmation step, such as a button, for the legal representative to confirm their intent.
89+
:::
90+
91+
The new account is created under the same account holder, sharing the same KYB and legal representative. All additional accounts have an `Unlimited` payment level and the `PaymentService` account type.
92+
93+
## Account conditions {#account-conditions}
94+
95+
### Account creation limit {#account-creation-limit}
96+
97+
By default, users are limited to one account until the multiple accounts feature is activated.
98+
99+
After the feature is activated, users may be granted a maximum number of accounts, which is defined during the compliance review and documented in a welcome letter.
100+
101+
Users are restricted from creating new accounts after reaching the maximum limit.
102+
103+
:::info Account status
104+
Only accounts with an Opened status count toward the maximum limit. Suspended, Closing, or Closed accounts do not.
105+
:::
106+
107+
### Checking your account creation limit {#checking-your-account-creation-limit}
108+
109+
1. Call the `projectInfo` query (line 2).
110+
1. Select `multipleAccountsSettings` (line 3).
111+
1. Add `accountCreationLimit` and `canOpenAccount` to check your account creation limit (lines 4-5).
112+
113+
<h3 id="query-main">Query</h3>
114+
115+
<a href="https://explorer.swan.io?query=cXVlcnkgQWNjb3VudENyZWF0aW9uTGltaXQgewogIHByb2plY3RJbmZvIHsKICAgIG11bHRpcGxlQWNjb3VudHNTZXR0aW5ncyB7CiAgICAgIGFjY291bnRDcmVhdGlvbkxpbWl0CiAgICAgIGNhbk9wZW5BY2NvdW50CiAgICB9CiAgfQp9Cg%3D%3D&tab=api" className="explorer-badge">Open in API Explorer</a>
116+
117+
```graphql {2-5} showLineNumbers
118+
query AccountCreationLimit {
119+
projectInfo {
120+
multipleAccountsSettings {
121+
accountCreationLimit
122+
canOpenAccount
123+
}
124+
}
125+
}
126+
```
127+
<h3 id="payload-main">Payloads</h3>
128+
129+
The `multipleAccountsSettings` query returns a payload that indicates the current status of the multiple accounts feature for an account holder.
130+
131+
**Example one: Multiple accounts not active**
132+
133+
This payload shows the response when the multiple accounts feature has **not** been **activated**.
134+
135+
- `accountCreationLimit`: `1` indicates that only the initial account can be created.
136+
- `canOpenAccount`: `false` confirms that additional accounts cannot be created.
137+
138+
```json {5,6} showLineNumbers
139+
{
140+
"data": {
141+
"projectInfo": {
142+
"multipleAccountsSettings": {
143+
"accountCreationLimit": 1,
144+
"canOpenAccount": false
145+
}
146+
}
147+
}
148+
}
149+
```
150+
151+
**Example two: Multiple accounts active**
152+
153+
This payload shows the response when the multiple accounts feature has been **activated**.
154+
155+
- `accountCreationLimit`: `6` shows that a maximum of six accounts can be created.
156+
- `canOpenAccount`: `true` confirms that additional accounts can be opened.
157+
158+
```json {5,6} showLineNumbers
159+
{
160+
"data": {
161+
"projectInfo": {
162+
"multipleAccountsSettings": {
163+
"accountCreationLimit": 6,
164+
"canOpenAccount": true
165+
}
166+
}
167+
}
168+
}
169+
```
170+
## Shared account details {#shared-account-details}
171+
172+
### IBAN country {#iban-country}
173+
174+
All accounts under the same account holder share the same IBAN country. To create an account with a different IBAN country, the legal representative must complete a new company onboarding process.
175+
176+
### Company registration number {#company-registration-number}
177+
178+
All additional accounts are linked to one account holder with a single registration number. To create an account for another company, the user must complete a new company onboarding process with the new company's registration number.
179+
180+
## Account management {#account-management}
181+
182+
### Legal documents {#legal-documents}
183+
184+
The same **Terms and Conditions** and **Partnership Conditions** apply to all accounts under the same account holder. Legal documents are generated in the same way as for single accounts.
185+
186+
### Account closure {#account-closure}
187+
188+
Standard [account closure rules](/topics/accounts/closure/#closure-partner) apply. Each account can be closed individually. You can request closure of the first account (created during onboarding) while keeping any additional accounts active.
189+
190+
## Billing {#billing}
191+
192+
### End-customer billing {#end-customer-billing}
193+
194+
Each active account is billed independently, resulting in one invoice per account.
195+
196+
### Partner billing {#partner-billing}
197+
198+
Active account pricing is applied at the account holder level, resulting in a new fee for active accounts on your invoice.
199+
200+
## Setting access in Web banking {#web-banking-access}
201+
202+
The web banking setting `canOpenAccount` is a project-level configuration that controls whether an account holder can open additional accounts directly from Swan Web banking.
203+
204+
This setting is activated by default. Unless you deactivate it, end users will be able to open multiple accounts from Swan's interface.
205+
206+
To restrict account opening to your own banking application, deactivate the `canOpenAccount` setting in your **Dashboard** > **Settings** > **Web banking**.
207+
208+
### Key benefits {#web-banking-benefits}
209+
210+
Controlling this setting gives you greater flexibility to:
211+
212+
1. **Restrict by pricing plan:** Restrict access to the Multiple Accounts feature by pricing plan.
213+
1. **Differentiate by account limits:** Define how many additional accounts a user can create. For instance, one additional account for Basic plans and up to five for Premium plans.
214+
215+
## Rejections {#rejections}
216+
217+
Multiple account creations can be rejected for the following reasons:
218+
219+
| Rejection reason | Description |
220+
| --- | --- |
221+
| `AccountHolderNotFoundRejection` | The provided account holder ID doesn't match an existing `AccountHolder`. |
222+
| `ForbiddenRejection` | The project isn't allowed to create multiple accounts, or the wrong context is used. |
223+
| `AccountMembershipNotEligibleRejection` | The user isn't eligible to open the account. They must be the account legal representative. |
224+
| `AccountHolderTypeNotEligibleRejection` | The account holder type must be `Company`. |
225+
| `AccountHolderStatusNotEligibleRejection` | The account holder status must be `Enabled`. |
226+
| `AccountHolderVerificationStatusNotEligibleRejection` | The account holder must have a `Verified` KYC status. |
227+
| `AccountHolderAccountsTypeNotEligibleRejection` | All associated accounts must be `EndCustomer` or `CapitalDepositMainAccount`. |
228+
| `AccountHolderAccountsStatusNotEligibleRejection` | No active accounts available. All associated accounts are `Closed`, `Closing`, or `Suspended`. |
229+
| `AccountHolderAccountsCreationLimitRejection` | The maximum number of `Opened` accounts has been reached. Check project settings for multiple accounts. |
230+
| `AccountHolderProjectSettingNotEligibleRejection` | Account creation is disabled in project settings. |
231+
232+
## Guides {#guides}
233+
234+
- [Create multiple accounts](guide-multiple-accounts-integration.mdx)

‎sidebars.js‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -781,8 +781,17 @@ module.exports = {
781781
"preview/card-insurance/guide-insurance-integration",
782782
],
783783
},
784+
{
785+
type: "category",
786+
label: "Multiple accounts",
787+
link: { type: "doc", id: "preview/multiple-accounts/multiple-accounts" },
788+
collapsed: true,
789+
items: [
790+
"preview/multiple-accounts/guide-multiple-accounts-integration",
791+
],
792+
},
784793
// Add more preview features here
785794
],
786-
}
795+
},
787796
],
788797
};

0 commit comments

Comments
 (0)