From ca602dd192b53c981951ccd2be03748848e9ff3e Mon Sep 17 00:00:00 2001 From: Maxence Busson Date: Fri, 24 Oct 2025 15:04:14 +0200 Subject: [PATCH 1/5] Update incoming-vop-requests.mdx --- .../sepa/vop/incoming-vop-requests.mdx | 73 +++++++++++++++++-- 1 file changed, 65 insertions(+), 8 deletions(-) diff --git a/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx b/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx index db1baf7e62..743558fe2a 100644 --- a/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx +++ b/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx @@ -88,20 +88,69 @@ The SIREN number is a 9-digit code assigned by INSEE, the French National Instit - **Company IBAN**: `AccountHolder.registration` (same as `company_identification`). - **Individual IBAN**: Not applicable. -## Matching considerations {#matching-considerations} +## Matching algorithm {#matching-algorithm} -### Account holder information accuracy {#correct-information} +Swan uses an enhanced matching algorithm that checks multiple name variations to improve verification success rates. + +### Company accounts {#company-matching} + +For company accounts, Swan checks the received name against six variations: + +1. Legal name (`AccountHolder.companyName`) +2. Trade name (`CompanyInfo.tradeName`) +3. Legal name + "Swan" +4. Trade name + "Swan" +5. Legal name + Project name (`ProjectInfo.name`) +6. Trade name + Project name + +#### Example + +
+**Swan receives "Awesome Company" for an IBAN.** + +| Received name | Swan checks against | Result type | +| --- | --- | --- | +| Awesome Company | Legal name: "AWESOME COMPANY SAS" | Close match (83%) | +| Awesome Company | Trade name: "Awesome Company" | Match (100%) | +| Awesome Company | Legal name + Swan: "AWESOME COMPANY SAS Swan" | No match (65%) | +| Awesome Company | Trade name + Swan: "Awesome Company Swan" | Close match (87%) | +| Awesome Company | Legal name + Project: "AWESOME COMPANY SAS FinanceApp" | No match (58%) | +| Awesome Company | Trade name + Project: "Awesome Company FinanceApp" | Close match (78%) | + +Swan checks all variations and returns the best matching result to the requesting PSP. +
+ +### Individual accounts {#individual-matching} + +For individual accounts, Swan checks the received name against three variations: + +1. Individual name (`AccountHolder.firstName` + `AccountHolder.lastName`) +2. Individual name + "Swan" +3. Individual name + Project name (`ProjectInfo.name`) + +**Example**: When Swan receives "Marie Dubois" for an individual IBAN: + +| Received name | Swan checks against | Result type | +| --- | --- | --- | +| Marie Dubois | Individual name: "Marie Claire Dubois" | Close match (89%) | +| Marie Dubois | Individual name + Swan: "Marie Claire Dubois Swan" | Close match (75%) | +| Marie Dubois | Individual name + Project: "Marie Claire Dubois PayApp" | No match (68%) | + +Swan checks all variations and returns the best matching result to the requesting PSP. + +## Account holder information accuracy {#correct-information} To ensure successful incoming transfers, your users must provide senders with their exact account name and IBAN as they appear on their Swan account. Swan verifies incoming transfers against the legal name and details registered in the system. **Key points to communicate to your users:** - Use the complete legal name, including all registered middle names. - Ensure all names are spelled correctly. -- For business accounts, use the full legal company name, not a trade or merchant name. +- For business accounts, use the full legal company name, not a trade or merchant name. +- Consider sharing your trade name if it differs significantly from your legal name, as Swan's matching algorithm also checks trade names. You may share [our end-user support article](https://support.swan.io/hc/en-150/articles/30680956306333-Verification-of-Payee-VoP) to assist with user training. -**Example**: If a company's legal name is "MY COMPANY SAS" but they operate as "Awesome Company", senders must use "MY COMPANY SAS" for VoP requests to match. Similarly, if an account holder's name is "Henri Charles Dupont," senders should use the complete name, not just "Henri Dupont." +**Example**: If a company's legal name is "MY COMPANY SAS" but they operate as "Awesome Company", senders can use either name. Swan's matching algorithm checks both the legal name and trade name to improve verification success. Similarly, if an account holder's name is "Henri Charles Dupont," senders should use the complete name, not just "Henri Dupont." ## VoP matching and results {#matching-and-results} @@ -118,18 +167,26 @@ Swan returns one of four possible results: | **No match** | Significant differences (under 70% similarity for names) | Name: Levenshtein distance
ID numbers: Exact match | | **Impossible to match** | Account not found, unsupported ID type, account closed or suspended | Not applicable | -### Examples {#examples} - -**Name matching examples:** +### Name matching examples {#name-examples} +**Individual names:** - "Henri Dupont" vs "Henri Dupont" → Match (100% similarity) - "Henri Dupont" vs "Henri Dupond" → Close match (92% similarity) - "Henri Dupont" vs "Henry Dupond" → Close match (83% similarity) - "Henri Dupont" vs "Malika Ngoma" → No match (8% similarity) -**ID number matching examples:** +**Company names:** +- "Awesome Company SAS" vs "Awesome Company SAS" → Match (100% similarity) +- "Awesome Company" vs "Awesome Company SAS" → Close match (83% similarity) +- "Awesome Co" vs "Awesome Company" → Close match (73% similarity) +- "Different Business Ltd" vs "Awesome Company SAS" → No match (15% similarity) + +### ID number matching examples {#id-examples} + +ID numbers require exact matches: - Stored: "DE136695976", Received: "136695976" → **No match** - Stored: "9234.56.788", Received: "923456788" → **No match** +- Stored: "DE136695976", Received: "DE136695976" → **Match** ## What this means for transfers {#transfer-implications} From df80f7955fc77bc423e9ca4cddff36198886c443 Mon Sep 17 00:00:00 2001 From: Maxence Busson Date: Fri, 24 Oct 2025 15:07:36 +0200 Subject: [PATCH 2/5] Update incoming-vop-requests.mdx --- .../sepa/vop/incoming-vop-requests.mdx | 22 +++++++++---------- 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx b/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx index 743558fe2a..6bfa0f5d7b 100644 --- a/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx +++ b/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx @@ -103,19 +103,17 @@ For company accounts, Swan checks the received name against six variations: 5. Legal name + Project name (`ProjectInfo.name`) 6. Trade name + Project name -#### Example -
-**Swan receives "Awesome Company" for an IBAN.** +**Example**: Swan receives "Awesome Company" for an IBAN | Received name | Swan checks against | Result type | | --- | --- | --- | -| Awesome Company | Legal name: "AWESOME COMPANY SAS" | Close match (83%) | +| Awesome Company | Legal name: "AWESOME COMPANY SAS" | Close match (79%) | | Awesome Company | Trade name: "Awesome Company" | Match (100%) | -| Awesome Company | Legal name + Swan: "AWESOME COMPANY SAS Swan" | No match (65%) | -| Awesome Company | Trade name + Swan: "Awesome Company Swan" | Close match (87%) | -| Awesome Company | Legal name + Project: "AWESOME COMPANY SAS FinanceApp" | No match (58%) | -| Awesome Company | Trade name + Project: "Awesome Company FinanceApp" | Close match (78%) | +| Awesome Company | Legal name + Swan: "AWESOME COMPANY SAS Swan" | No match (62%) | +| Awesome Company | Trade name + Swan: "Awesome Company Swan" | Close match (75%) | +| Awesome Company | Legal name + Project: "AWESOME COMPANY SAS FinanceApp" | No match (50%) | +| Awesome Company | Trade name + Project: "Awesome Company FinanceApp" | No match (58%) | Swan checks all variations and returns the best matching result to the requesting PSP.
@@ -128,13 +126,13 @@ For individual accounts, Swan checks the received name against three variations: 2. Individual name + "Swan" 3. Individual name + Project name (`ProjectInfo.name`) -**Example**: When Swan receives "Marie Dubois" for an individual IBAN: +**Example**: When Swan receives "Henri Dubois" for an individual IBAN: | Received name | Swan checks against | Result type | | --- | --- | --- | -| Marie Dubois | Individual name: "Marie Claire Dubois" | Close match (89%) | -| Marie Dubois | Individual name + Swan: "Marie Claire Dubois Swan" | Close match (75%) | -| Marie Dubois | Individual name + Project: "Marie Claire Dubois PayApp" | No match (68%) | +| Henri Dubois | Individual name: "Henri Dubois" | Match (100%) | +| Henri Dubois | Individual name + Swan: "Henri Dubois Swan" | Close match (71%) | +| Henri Dubois | Individual name + Project: "Henri Dubois PayApp" | No match (63%) | Swan checks all variations and returns the best matching result to the requesting PSP. From 01df948a58472c1a7f8cf822fbcfa0cf30096146 Mon Sep 17 00:00:00 2001 From: "Max B." <17831738+max-koro@users.noreply.github.com> Date: Fri, 24 Oct 2025 15:49:27 +0200 Subject: [PATCH 3/5] Doc 1400/hotfix capdep wrong api call bodies (#467) * Fixing bad API examples * Update guide-update-shareholder-amount.mdx --- .../capital-deposits/guide-update-company.mdx | 42 ++++++++++++----- .../guide-update-shareholder-amount.mdx | 47 ++++++++++++++----- 2 files changed, 67 insertions(+), 22 deletions(-) diff --git a/docs/topics/capital-deposits/guide-update-company.mdx b/docs/topics/capital-deposits/guide-update-company.mdx index 781017f17e..6d0819b34f 100644 --- a/docs/topics/capital-deposits/guide-update-company.mdx +++ b/docs/topics/capital-deposits/guide-update-company.mdx @@ -14,11 +14,11 @@ import UpdateCompanyPrereqs from './partials/_update-company-prereqs.mdx'; ## Guide {#steps} -1. Call the `updateCapitalDepositCompany` mutation. +1. Call the `updateCapitalDepositCaseCompany` mutation. 1. Add the capital deposit case ID. 1. Add the fields you want to update: `companyName` and/or `residencyAddress`. 1. Add the success payload and any information you'd like to receive. -1. Add rejections (not shown). +1. Add rejections. :::info Automatic synchronization Updating these fields automatically syncs the data across both the capital deposit case and the associated account holder. @@ -26,13 +26,13 @@ Updating these fields automatically syncs the data across both the capital depos ## Mutation {#mutation} -Open in API Explorer +Open in API Explorer -```graphql {2-4} showLineNumbers +```graphql {2-6,15} showLineNumbers mutation UpdateCompany { - updateCapitalDepositCompany( + updateCapitalDepositCaseCompany( input: { - id: "$CAPITAL_DEPOSIT_CASE_ID" + capitalDepositCaseId: "$CAPITAL_DEPOSIT_CASE_ID" companyName: "Acme" residencyAddress: { addressLine1: "10 Rue de Rivoli" @@ -43,7 +43,7 @@ mutation UpdateCompany { } } ) { - ... on UpdateCapitalDepositCompanySuccessPayload { + ... on UpdateCapitalDepositCaseCompanySuccessPayload { __typename capitalDepositCase { id @@ -63,19 +63,39 @@ mutation UpdateCompany { } } } + ... on CapitalDepositCaseCanNotBeFoundRejection { + __typename + message + } + ... on BadRequestRejection { + __typename + message + } + ... on ValidationRejection { + __typename + message + } + ... on ForbiddenRejection { + __typename + message + } + ... on InternalErrorRejection { + __typename + message + } } } ``` ## Payload {#payload} -```graphql {6-7,11,14-18} showLineNumbers +```graphql {} showLineNumbers { "data": { - "updateCapitalDepositCompany": { - "__typename": "UpdateCapitalDepositCompanySuccessPayload", + "updateCapitalDepositCaseCompany": { + "__typename": "UpdateCapitalDepositCaseCompanySuccessPayload", "capitalDepositCase": { - "id": "$CAPITAL_DEPOSIT_CASE_ID", + "id": "a4c9da36-56e1-4ed8-b0a1-2c9f3d7e8b12", "companyName": "Acme", "companyOnboarding": { "accountHolder": { diff --git a/docs/topics/capital-deposits/guide-update-shareholder-amount.mdx b/docs/topics/capital-deposits/guide-update-shareholder-amount.mdx index c9eb43802a..df2e077b49 100644 --- a/docs/topics/capital-deposits/guide-update-shareholder-amount.mdx +++ b/docs/topics/capital-deposits/guide-update-shareholder-amount.mdx @@ -15,10 +15,10 @@ import UpdateShareholderPrereqs from './partials/_update-shareholder-prereqs.mdx ## Guide {#steps} 1. Call the `updateCapitalDepositShareholderAmount` mutation (line 2). -1. Add the shareholder ID (line 3). -1. Add the updated amount in the `amount` field (line 3). +1. Add the shareholder ID (line 4). +1. Add the updated amount in the `shareholderAmount` field (line 5). 1. Add the `UpdateCapitalDepositShareholderAmountSuccessPayload` and any information you'd like to receive. -1. Add rejections (not shown). +1. Add rejections. :::info Automatic recalculation Updating a shareholder's deposit amount automatically triggers a recalculation of the total capital deposit amount for the case. @@ -26,12 +26,14 @@ Updating a shareholder's deposit amount automatically triggers a recalculation o ## Mutation {#mutation} -Open in API Explorer - -```graphql {2-3} showLineNumbers +Open in API Explorer +```graphql {2-5,8} showLineNumbers mutation UpdateShareholderAmount { updateCapitalDepositShareholderAmount( - input: { id: "$SHAREHOLDER_ID", amount: { currency: "EUR", value: "1000" } } + input: { + shareholderId: "$SHAREHOLDER_ID", + shareholderAmount: { currency: "EUR", value: "1000" } + } ) { ... on UpdateCapitalDepositShareholderAmountSuccessPayload { __typename @@ -43,22 +45,45 @@ mutation UpdateShareholderAmount { } } } + ... on CapitalDepositCaseCanNotBeFoundRejection { + __typename + message + } + ... on CapitalDepositShareholderCannotBeFoundRejection { + __typename + message + } + ... on CapitalDepositShareholderCanNotBeUpdatedRejection { + __typename + message + } + ... on ValidationRejection { + __typename + message + } + ... on ForbiddenRejection { + __typename + message + } + ... on InternalErrorRejection { + __typename + message + } } } ``` ## Payload {#payload} - -```graphql {6,8-10} showLineNumbers +```graphql {6,8-9} showLineNumbers { "data": { "updateCapitalDepositShareholderAmount": { "__typename": "UpdateCapitalDepositShareholderAmountSuccessPayload", "shareholder": { - "id": "$SHAREHOLDER_ID", + "id": "fc995f3f-09aa-42e4-9e2f-c4e1185e6b57", "capitalDepositAmount": { "currency": "EUR", - "value": "1000" + "value": "1000.00" } } } From 1521cfd12a010fc6ccecd1ae8e4924bcedd9e6c4 Mon Sep 17 00:00:00 2001 From: "Max B." <17831738+max-koro@users.noreply.github.com> Date: Fri, 24 Oct 2025 16:08:09 +0200 Subject: [PATCH 4/5] Update belgian-ibans.mdx (#466) * Update belgian-ibans.mdx * Update belgian-ibans.mdx * Update belgian-ibans.mdx * Apply suggestions from code review Co-authored-by: racene-swan --------- Co-authored-by: racene-swan --- docs/preview/belgian-ibans/belgian-ibans.mdx | 56 +++++++++++++++++--- 1 file changed, 49 insertions(+), 7 deletions(-) diff --git a/docs/preview/belgian-ibans/belgian-ibans.mdx b/docs/preview/belgian-ibans/belgian-ibans.mdx index 7626ccf671..09b4cbd42a 100644 --- a/docs/preview/belgian-ibans/belgian-ibans.mdx +++ b/docs/preview/belgian-ibans/belgian-ibans.mdx @@ -21,7 +21,7 @@ Offering Belgian IBANs expands Swan's local IBAN coverage, allowing you to offer Belgian IBANs are available for: - **Account holders** registered in Belgium and in Swan-supported European markets. -- **[Account members](/topics/accounts/memberships/)** invited to a Belgian account, regardless of their location.. +- **[Account members](/topics/accounts/memberships/)** invited to a Belgian account, regardless of their location. - **Business accounts** for Belgian companies and subsidiaries. ## Integration impact @@ -32,13 +32,15 @@ Belgian IBAN support maintains full compatibility with existing Swan integration - **Standard [onboarding flow](/topics/onboarding/)**: Uses existing [individual](/topics/onboarding/individual/) and [company](/topics/onboarding/company/) onboarding processes. - **Consistent permissions**: Account membership permissions work identically across all local IBANs. -### Onboarding requirements +## Onboarding requirements Belgian account holders follow Swan's standard onboarding requirements with these specifics: -#### Individual accounts +### Individual accounts + +#### Account information | API field | Requirement | Notes | |---|:---:|---| @@ -58,7 +60,23 @@ Belgian account holders follow Swan's standard onboarding requirements with thes | `residencyAddress.state` | | State or region | | `taxIdentificationNumber` | | Belgian tax identification | -#### Company accounts +#### Identification + +Belgian individual accounts require identity verification following Swan's [identification](/topics/users/identifications/) process. + +| Account country | Recommended level | Other supported levels | +|---|---|---| +| 🇧🇪 Belgium | QES | Expert + first transfer
PVID | + +:::info Identification level +This may change from QES to Expert to align with the Netherlands when launching Belgian IBANs. +::: + +[Learn more about identity verification methods ➜](/partnership/document-center/identity/) + +### Company accounts + +#### Account information | API field | Requirement | Notes | |---|:---:|---| @@ -87,9 +105,29 @@ Belgian account holders follow Swan's standard onboarding requirements with thes | `typeOfRepresentation` | | Type of legal representation | | `vatNumber` | | VAT registration number | +#### Identification + +***Self-employed accounts*** + +Belgian self-employed account holders use **QES** identification. + +:::info Self-employed identification +We might update self-employed identification to **`QES` + [`First transfer`](/topics/onboarding/account-holders/#first-transfer)** when launching Belgian IBANs. +::: + +***Company accounts*** + +Belgian company accounts require identity verification for the [account admin](/topics/onboarding/company/#representatives). + +| Account country | Recommended level | Other supported levels | +|---|---|---| +| 🇧🇪 Belgium | Expert | QES
PVID | + +[Learn more about identity verification methods ➜](/partnership/document-center/identity/) + #### Ultimate Beneficial Owners (UBOs) -For company accounts, Ultimate Beneficial Owners information is required: +For company accounts, the UBOs information is required: | API field | Requirement | Notes | |---|:---:|---| @@ -124,7 +162,7 @@ For company accounts, Ultimate Beneficial Owners information is required: | `personalAddress.postalCode` | | Postal code | | `personalAddress.state` | | State or region | -### Account memberships +## Account memberships Belgian account memberships follow standard Swan patterns: @@ -150,4 +188,8 @@ Belgian account memberships follow standard Swan patterns: | `restrictedTo.lastName` | | Member's last name | | `restrictedTo.phoneNumber` | | Phone number - required for advanced permissions | | `restrictedTo.birthDate` | | Birth date - required for advanced permissions or card management | -| `taxIdentificationNumber` | | Member's tax identification number | \ No newline at end of file +| `taxIdentificationNumber` | | Member's tax identification number | + +## Card printing + +Cards for Belgian accounts are printed and shipped from Swan's [🇫🇷 France hub in Dijon](/topics/cards/physical/#hubs-france). \ No newline at end of file From e638a9f2ef6ff466858cc16eb950251a31b55184 Mon Sep 17 00:00:00 2001 From: Maxence Busson Date: Fri, 24 Oct 2025 16:17:12 +0200 Subject: [PATCH 5/5] Update incoming-vop-requests.mdx --- .../credit-transfers/sepa/vop/incoming-vop-requests.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx b/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx index 6bfa0f5d7b..cf809f690a 100644 --- a/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx +++ b/docs/topics/payments/credit-transfers/sepa/vop/incoming-vop-requests.mdx @@ -69,9 +69,7 @@ This process is automatic. Swan handles all incoming VoP requests; no implementa Swan supports the following payee identification types with a Swan [Bank Identifier Code (BIC)](/topics/accounts/ibans/#local): ### Name {#name-type} -The name of the legal entity or of the individual: -- **Company IBAN**: `AccountHolder.companyName`. -- **Individual IBAN**: `AccountHolder.firstName` + `AccountHolder.lastName`. +The name of the legal entity or of the individual: `AccountHolderInfo.name`. ### Tax number {#tax-number-type} The number assigned by a tax authority to identify an organisation: @@ -96,7 +94,7 @@ Swan uses an enhanced matching algorithm that checks multiple name variations to For company accounts, Swan checks the received name against six variations: -1. Legal name (`AccountHolder.companyName`) +1. Legal name (`AccountHolderInfo.name`) 2. Trade name (`CompanyInfo.tradeName`) 3. Legal name + "Swan" 4. Trade name + "Swan" @@ -122,7 +120,7 @@ Swan checks all variations and returns the best matching result to the requestin For individual accounts, Swan checks the received name against three variations: -1. Individual name (`AccountHolder.firstName` + `AccountHolder.lastName`) +1. Individual name (`AccountHolderInfo.name`) 2. Individual name + "Swan" 3. Individual name + Project name (`ProjectInfo.name`)