Skip to main content

Accounts

Use Swan accounts to receive and initiate payments, as well as deposit money. All money moves through accounts, so if you're using Swan, you're using an account.

Swan accounts are based in euros (โ‚ฌ) and are represented by an IBAN and a name. Get information about the account with the account query, and update information such as the name with the updateAccount mutation.

Creating accounts

Accounts, along with account holders, are created during the account onboarding process.

Account countryโ€‹

You choose your account's country during the onboarding process. The account country then determines IBAN country codes. For example, consider the sample mutation to create an individual onboarding link. The account country chosen on line 4 is France (accountCountry: FRA). All IBANs associated with this account have the prefix FR.

Swan offers the following account countries:

  1. ๐Ÿ‡ซ๐Ÿ‡ท France
  2. ๐Ÿ‡ฉ๐Ÿ‡ช Germany
  3. ๐Ÿ‡ฎ๐Ÿ‡น Italy
  4. ๐Ÿ‡ณ๐Ÿ‡ฑ Netherlands
  5. ๐Ÿ‡ช๐Ÿ‡ธ Spain

Resident and non-resident accountsโ€‹

The account country isn't always the country where the account holder resides. Your users can have a Swan account if they live anywhere in the European Union, as Swan allows accounts for both residents and non-residents of supported account countries.

  • Resident account: The account holder lives in the account country.
  • Non-resident account: The account holder lives outside the account country. These accounts often require reporting as a foreign account to the account holder's local tax authority.
Thorough account holder review

Opening accounts is subject to a thorough verification, regardless of residence or account country.

Account languageโ€‹

Account holders choose their account language during onboarding. You can also set the account language when creating onboarding links for individuals and companies.

Swan uses the account language for all official documents and communications.

After an account is created, you can change the account language with the updateAccount mutation. If you're using Swan's Web Banking interface, account holders can change their account language independently.

By default, account memberships inherit the same language as the account. If account members choose a different preferred language than the account holder, however, they receive certain communications in their account membership language.

Supported languagesโ€‹

Several account languages are available:

  • Dutch (nl)
  • English (en)
  • Finnish (fi)
  • French (fr)
  • German (de)
  • Italian (it)
  • Portuguese (pt)
  • Spanish (es)
Finnish (fi)

While Finnish is an available account language, it isn't a supported account membership language yet. When the account language is Finnish, the account membership language defaults to English.

Account type and levelโ€‹

Swan accounts are defined by a payment level and payment account type. There are two possible values for each:

Accounts start with the level Limited and the account type EMoney. The level changes from Limited to Unlimited when the account holder verification status changes to Verified. The account type changes from EMoney to PaymentService when the account's main IBAN is available to the account holder. Accounts with the level Unlimited and the account type PaymentService are fully functional accounts.

Swan accounts have different capabilities determined by the combination of these values.

Level + TypeCapabilities
Limited + EMoneyโœ“ The account can be used for certain actions, such as inviting account members and adding virtual cards.

โ˜’ Account holder verification isn't complete.
โ˜’ The account's main IBAN isn't displayed.
โ˜’ Payments can't be made from the account.
Limited + PaymentServiceโœ“ The account's main IBAN is displayed.
โœ“ Money can be added to the account.

โ˜’ Account holder verification isn't complete.
โ˜’ Payments can't be made from the account.
Unlimited + PaymentServiceโœ“ Account holder verification status is Verified.
โœ“ Payments can be made from the account.
โœ“ The account's main IBAN is displayed.
โœ“ All accounts functions are possible.

Balancesโ€‹

Accounts at Swan are designed for credit balances only. Swan account balances can never go below zero, meaning Swan rejects outgoing payments if the account's Available balance isn't sufficient to cover the total payment amount. The only exception is the automatic billing of banking fees.

There are four different account balances.

BalanceIncludesEqual to
BookedTransactions that are already debited or creditedSum of all Booked transactions
PendingTransactions that were authorized but haven't been debited or credited yetSum of all Pending transactions
ReservedTransactions that require rolling reserve according to the policy for that payment method

Reserved amount is included in the Booked balance
Sum of all Booked transactions for which the funds are still in rolling reserve
AvailableBalance that is actually available to be usedBooked - (Pending + Reserved)

Example: Insufficient funds

This example involves the balances Booked, Pending, and Available.

  1. An account has a Booked balance of 142โ‚ฌ.
  2. There is a Pending outgoing transfer request for 42โ‚ฌ that is still being processed. Therefore, the Available balance is 100โ‚ฌ (142โ‚ฌ - 42โ‚ฌ = 100โ‚ฌ).
  3. This account doesn't have a sufficient balance to send an outgoing payment of more than its 100โ‚ฌ Available balance. Therefore, the payment is rejected.

Example: Rolling reserve

This example involves the balances Booked, Reserved, and Available.

  1. A merchant's account has a Booked balance of 200โ‚ฌ thanks to accepting a customer's payment through SEPA Direct Debit.
  2. For this example, the rolling reserve is 15% over 15 business days (exact rolling reserve amounts can change based on your contract with Swan). Therefore, the Reserved balance is 30โ‚ฌ for 15 days.
  3. The Available balance from this transaction is 170โ‚ฌ for the duration of the rolling reserve period (200โ‚ฌ - 30โ‚ฌ = 170โ‚ฌ).
  4. After 15 days, the Reserved balance is released and the full Available balance is 200โ‚ฌ.

Transactionsโ€‹

An account is essentially a list of transactions, and transactions directly impact account balances.

There are six possible statuses for Swan transactions. Each payment method uses a different combination of these statuses with specific flows. Refer to the schemas for credit transfers, direct debits, and cards for more information about statuses for that payment method.

Transaction statusExplanation
UpcomingTransaction was initiated and consent was granted, but the transaction isn't executed yet. Upcoming transactions don't impact the account balance.
PendingTransaction was initiated, consent was granted, and the transaction is set to happen within a few days. The transactions aren't debited from the account yet, but they impact the account's Pending balance.
BookedCompleted transactions that are displayed on the official account statement. These transactions have been debited from the account, and they impact the account's Booked balance.
ReleasedUnique to card transactions, card authorizations might be released for specific reasons. Released transactions can impact the account balance. Refer to the card payments section for more information.
CanceledAn Upcoming transaction is canceled by someone with the right to do so, such as the account holder, an account member, or a merchant. Only transactions with the status Upcoming can be Canceled, and Canceled transactions don't impact the account balance.
RejectedDeclined or refused transactions. For example, the beneficiary account might be closed, or the account's Available balance isn't sufficient to complete the transaction without resulting in a negative balance.

Account documentsโ€‹

Account statementsโ€‹

Each month, Swan generates account statements automatically for all Swan accounts using Coordinated Universal Time +1 (UTC +1). Statements include all Booked transactions from the previous month.

Access account statements with the API by calling the account query and adding the statement object. They're also available from your Dashboard > Data > Accounts, and, if you're using it, Swan's Web Banking interface.

Account statements are available in .pdf or .csv format by default. Statements with more than 50,000 transactions are generated as .csv files, even if you request .pdf.

All account statements have a period attribute.

  • If period = Monthly, Swan generated the statement.
  • If period = Custom, the statement was generated following your request.

Generating statementsโ€‹

You can generate account statements for a period of up to three months with the generateAccountStatement mutation. These statements always have period = Custom.

If you generate two statements with identical parameters (language, openingDate, closingDate), Swan only generates one statement. For the second statement, Swan provides the link to the first statement generated.

If the language parameter changes, however, a new statement is generated in the updated language.

Producing custom statementsโ€‹

You can also access the raw data and produce custom statements.

For example, you might:

  • Need a provide a format Swan doesn't support.
  • Want to customize the style.
  • Prefer to use a different timezone than Central European [Summer] Time (CET/CEST).

Note that even if you use custom statements, Swan generates statements each month. If audited, Swan's account statement is the official version.

Custom statement approval

As a regulated financial institution, account statements fall under compliance rules. You might need to get your custom statements approved. Please work with your dedicated Technical Account Manager before releasing a custom account statement.

Bank details documentโ€‹

You can get a PDF containing your bank details using the API. In French, this document is called a RIB, or a relevรฉ d'identitรฉ bancaire.

The PDF is generated automatically after the account's main IBAN is assigned, meaning the account must have the payment level Unlimited and the account type PaymentService. Note that the automatic generation might take a few minutes. The document is generated in the account language.

If an account's bank details document wasn't generated automatically, you can trigger the API.

Bank details documents include:

  1. Your logo.
  2. Account's main IBAN.
  3. Bank code.
  4. Your company's information.
  5. Disclaimer: "In partnership with Swan".
Swan partnership disclaimer

The Swan partnership disclaimer is required because Swan assumes responsibility for all sensitive banking operations. It's similar to the statement printed on physical cards indicating that cards are issued by Swan.

  1. Title of the document.
  2. BIC/SWIFT code.
  3. Account holder's information.

Image of a sample bank details PDF

Transaction statementsโ€‹

Your users might need to provide a document to a third party confirming they initiated a transaction. Transaction statements, also referred to as transaction confirmations, demonstrate that the transaction was executed by Swan. However, these statements don't provide proof that a transaction was completed successfully; the beneficiary's bank can reject a transaction after Swan executes it.

Refer to the transactions section for more information.

Account statusesโ€‹

StatusExplanation
OpenedAccount is open and can be used
SuspendedSwan can suspend an account if there's suspicion of fraud. While suspended, the account can't be used.
ClosingWhile an account is closing, the following events occur:

  1. All cards are canceled.
  2. Incoming SEPA Credit Transfers are automatically returned.
  3. All standing orders are canceled.
  4. All SEPA Direct Debit mandates are canceled.
The account status remains Closing until:

  • The Booked balance is zero.โˆ—
  • The last incoming SEPA Credit Transfer happened more than 30 days ago.
  • The last outgoing SEPA Credit Transfer happened more than 5 days ago.
ClosedFor all Closed accounts, access and account statements remain available for one year through the API or with Swan's Web Banking interface.
Remaining funds in Closing account โˆ—

As long as the Booked balance doesn't equal zero:

  1. The account status can't pass from Closing to Closed.
  2. The account holder can still log into their Swan Web Banking interface.
  3. The account holder can send SEPA Credit Transfers.

If funds remain in a Closing account after 10 years, Swan transfers the funds to France's Caisse des dรฉpรดts et consignations (Deposits and Consignments Fund).

Guidesโ€‹