Whatever you call it - wallet, money account, payment account, or bank account - at Swan, the notion of an account is fundamental. All types of payments always pass through an account.
The owner of the funds stocked in the account is the account holder. This can either be you, or your customer.
Each account has 3 types of balances:
booked: refers to the sum of
booked transactions, meaning already debited or credited.
pending: refers to
pending transactions, meaning those that were authorized but have not yet been debited.
available: refers to the sum of
pendingbalances. This is the available balance that can actually be spent.
Accounts at Swan were designed to support debit balances only. Their balance can never go below €0, so payments will be refused if the account's available balance is not sufficient to cover the total payment amount.
Example: An account has a balance of 142,00 € (Booked Balance), this account has a pending outgoing transfer request of -42,00€ (Pending Balance). This account can therefore not accept outgoing payments of more than 142,00 - 42,00 = 100,00€ (Available Balance).
Swan provides 4 transaction statuses:
bookedtransactions: these are debit or credit transactions that are completed and have already been recorded. These are the lines on the account statement.
pending transactions: these transactions were already authorized but have not yet been recorded. This type of transaction is commonly used to help the customer to understand their available balance, indicating the balance that is actually available to be sent on this account.
rejected transactions: these transactions were rejected. Since our accounts are designed not to carry a credit balance, this type of transaction is commonly used to help the customer understand why a transaction was refused (for example for insufficient funds).
upcoming transactions: these transactions have not yet been authorized and will soon be executed (for example SEPA Direct Debit).
Here is a diagram of the different transaction statuses:
Careful, transaction displays are regulated. If you don't use our Web banking to display your transactions, it is important to read the following before launching your development:
When you act on behalf of an individual user (with a User access token) to access online payment transactions of an account, EU Revised Directive on Payment Services (PSD2) requires the user to perform a new Strong Customer Authentication if the last one was applied more than 90 days ago.
When a Strong Customer Authentication is required to display new transactions, the
account object returns a
consent in the
requiredConsentToFetchNewTransactions attribute. Redirecting the user to the
consentURL will trigger Swan app to push a notification on the user's phone. Learn More.
Once the user has consent on the mobile app, the user is redirected to the callback URL with the
consentId in query params and you can call this query again to read the transaction list of any account.
When you act on your own behalf (server-to-server) (with a Project access token), there is no need to perform a Strong Customer Authentication to read the transaction list. But you are not allowed to disclose this information to an individual user without performing a Strong Customer Authentication every 90 days.
Many transaction types are available at Swan. The
type field describes which one has occured :
SepaCreditTransferOut: When a SEPA Credit Transfer debited the account.
SepaCreditTransferOutReturn: When a previous SEPA Credit Transfer debited the account and the creditor returned it.
SepaCreditTransferOutRecall: When a previous SEPA Credit Transfer debited the account and the account holder recalled the transfer and the creditor accepted.
SepaCreditTransferIn: When a SEPA Credit Transfer credited the account.
SepaCreditTransferInReturn: When a previous SEPA Credit Transfer credited the account and the account holder returned it.
SepaCreditTransferInRecall: When a previous SEPA Credit Transfer credited the account and the debtor recalled the transfer and the account holder accepted.
Fees: When Swan debited fees on the account.
SepaDirectDebitOut: When a SEPA Direct Debit debited the account.
SepaDirectDebitOutRefund: When a previous SEPA Direct Debit debited the account and the account holder refused it.
TopUpCardIn: When an e-commerce card payment credited the account.
TopUpCardRefund: When a previous e-commerce card top-up credited the account and Swan refunded the transaction.
TopUpCardChargeback: When a previous e-commerce card top-up credited the account and Swan received a chargeback.
The creation of an account occurs at the end of the onboarding process, when the account holder binds with Swan app. Learn More.
If you are using the API, you can also do the following:
Systematically refuse SEPA Direct Debit requests by calling the
No longer systematically refuse SEPA Direct Debit requests by calling the
The business relationship between you and an account holder can end in the following ways:
You wish to end the partnership with the account holder without them having to close the account
The account holder wishes to end the partnership with you, without having to close the account
The account holder wishes to close their account
The partnership between you and the account holder on the Swan platform appears as
partnershipStatusInfo on each account.
When you are the one initiating the end of the partnership, you should have a prior notice of 2 months imposed by our regulator. During this period the
partnershipStatusInfo has the
Canceling status and will provide the exact date of the end of the partnership in the
canceledAfterfield. At the end of this period, the
partnershipStatusInfo has the
Canceled status and you will no longer be able to access the account number nor the account holder's identifying information.
To request to end the partnership with your customer for a given account, you will need to call the
If it's the account holder that chooses to end the partnership with you, they can do so by contacting Swan directly, as is stipulated in the conditions of partnership.
In this case, the
Canceledstatus; all access to the balance, transactions, and other account information will be immediately cut-off. You will no longer have access to the account number.
Lastly, if a legal representative of the account holder sends you a request to close the account, you must call the
closeAccount mutation. Swan will then ask for the users consent, and a consent resource will be returned containing the
consentUrl which will let you redirect the user to launch Swan app's strong authentication process. Learn More.
Once the consent procedure and strong authentication is completed, the account's status will be changed to
Closing, then once all the closing operations have been finalised by Swan's team, the status will be changed to