Payments overview
Swan uses of a combination of payments and transactions to accomplish all financial operations.
Payments​
The core of Swan's offer is facilitating the sending and receiving of payments. A payment is:
A grouping of a single transaction or a series of transactions to move funds from one account to another. Payments group transactions together for two main reasons: the transactions were initiated at the same time, and they're related to the same operation or there is some other logical link between the transactions.
Payments can be initiated by individuals, businesses, or banks. Swan executes several types of payments denominated and executed in euros.
Types of payments​
Swan executes several types of payments:
- Credit transfers
- Direct debit
- Card payments
- French check payments (merchant offer only)
Payment ID​
Each payment has a unique payment ID. You can retrieve a payment ID (and other information about the payment) on your Dashboard or by running an API query.
Payment statuses​
| Payment status | Explanation |
|---|---|
ConsentPending | Status only occurs when consent is required for the payment Next step: Transaction flow blocked while waiting for consent; when consent is received, transaction flow resumes and payment status changes to Initiated |
Initiated | Payment successfully requested; enters the transaction flow |
Rejected | Payment rejected, either directly after payment initiation or from the Initiated status |
Push and pull payments​
The key difference between push and pull payments lies in who initiates the payment.
Push payments, such as credit transfers, refer to transactions where the debtor initiates the payment. The debtor authorizes the sending of funds from their account to the creditor's account. In other words, the debtor pushes the funds to the creditor.
Pull payments, such as direct debits and card payments, refer to transactions where the creditor initiates collecting funds from the debtor's account. The creditor requests a payment, and the debtor provides the necessary authorization for the transaction. In other words, the creditor pulls the funds from the debtor.
Payments and risk​
Push payments pose a lower risk for creditors and banks because debtors initiate these payments. The chance of insufficient funds is reduced, and debtors can only dispute push payments if they're the victim of theft or hacking.
Pull payments pose a higher risk for creditors and banks. Regulations allow varying periods of time after a pull transaction during which the debtor can dispute. Additionally, since pull payments are initiated by the creditor and not the debtor, there is a higher risk of insufficient funds in the account.
Transactions​
Distinct and identifiable events that aid in moving money from one account to another. Transactions lay out the path to move money between accounts.
A single payment is a group of one or several transactions.
All transactions go through a scoring service to determine if the transaction is compliant and if the account's Available balance is sufficient to cover the transaction.
Transactions are created asynchronously after a payment is initiated. In the API, you'll work primarily with transactions when seeking information about payments.
For example, two transactions are required if you try to send a single SEPA Credit Transfer (SCT) payment to an IBAN that doesn't exist.
- Transaction #1: Funds sent with an outgoing SCT to the SEPA network.
- Transaction #2: Funds returned with a separate transaction from the target bank.
Some physical card terminals in the Netherlands refuse Mastercard transactions. Therefore, Swan offers a Maestro fallback for qualified physical cards.
If the fallback is used to complete a transaction, the API returns the masked Maestro card information when queried for transaction details. The masked information also appears in the transaction history on your Dashboard and Swan's Web Banking interface.
Transaction ID​
Each transaction has a unique transaction ID.
You can filter your Dashboard transactions list with a full transaction ID to locate an exact transaction. Retrieve a transaction ID along with other transaction information by querying the API or directly on your Dashboard.
Transaction statuses​
There are six possible statuses for Swan transactions: Upcoming, Pending, Booked, Released, Canceled, and Rejected.
Transactions directly impact account balances.
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. Not all statuses are used for all transaction types.
| Transaction status | Explanation |
|---|---|
Upcoming | Transaction was initiated and consent was granted, but the transaction isn't executed yet. Upcoming transactions don't impact the account balance. |
Pending | Transaction 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. |
Booked | Completed 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. |
Released | Unique 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. |
Canceled | An 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. |
Rejected | Declined 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. |
Transaction supporting documents​
In certain cases, Swan requires supporting documents to justify transactions. Swan uses the supporting documents feature to manage the request and reception of these documents.
You can upload these documents proactively when initiating transactions with the API.
Transaction confirmation 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.
You can generate transaction statements for eligible Booked transactions with the API.
Statements are also available from your Dashboard and, if you're using it, Swan's Web Banking interface.
The following are eligible Booked transactions:
- SEPA Credit Transfers (incoming and outgoing)
- Instant SEPA Credit Transfers (incoming and outgoing)
Call the transaction or transactions query to confirm transaction statement eligibility.
Add the statementCanBeGenerated boolean, as shown in the guide to get transaction information.
After the statement is generated successfully with the API, you receive a TransactionStatement.Generated webhook notification.
When you receive the webhook notification, query the API to retrieve the URL to download the statement.
You have seven days to download the statement before the link expires.
Transaction statement statuses​
| Transaction statement status | Explanation |
|---|---|
Pending | Transaction statement is being generated. |
Generated | Transaction statement was generated successfully, triggering a TransactionStatement.Generated webhook notification. |
Failed | The statement couldn't be generated. You can try again. |
Expired | Transaction statement was generated successfully. However, it wasn't downloaded within seven days and therefore expired. |
Sharing transaction information​
The European Union's revised Payment Services Directive (PSD2) regulates how banking interfaces can display transactions. In order to display or share a user's sensitive information, there must be a recent consent from that user.
At the user level, you might need to act on behalf of a user with a user access token to access an account's online payment transactions. The user must consent to this action by performing a Strong Customer Authentication (SCA). Each SCA is valid for 180 days, so if the user's most recent SCA is older than 180 days, they'll need to consent again.
At the project level, when acting on your own behalf, you can view a list of your project's transactions anytime with a project access token. However, if you need to share information with a user, that user must consent. Again, if they haven't consented within 180 days, they'll need to perform a new SCA.
Swan's frontend complies with PSD2 requirements. If you choose to use a custom API integration or to modify Swan's open source code, you are responsible for respecting PSD2 requirements. Swan will verify that your offer is compliant.
About SEPA​
The Single Euro Payments Area (SEPA) is a payment network used to transfer funds in euros in 36 countries. One of SEPA's primary goals is to harmozine payments across these countries, making it easy to use cashless payment methods anywhere you are in and around Europe. SEPA is regulated by the European Payments Council (EPC).
Swan uses the SEPA Credit Transfer, SEPA Instant Credit Transfer, SEPA Direct Debit payment methods for all transactions not executed internally between Swan accounts.
SEPA countries and territories​
SEPA countries and territories include both European Union (EU) and non-EU members.
- EU members: Austria, Belgium, Bulgaria, Cyprus, Croatia, Czech Republic, Denmark, Estonia, Finland (including the Aland Islands), France (including French Guiana, Guadeloupe, Martinique, Mayotte, Saint Barthelemy, French Saint Martin, Reunion, and Saint Pierre and Miquelon), Germany, Greece, Hungary, Republic of Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Poland, Portugal (including Madeira and Azores), Romania, Slovenia, Slovakia, Spain (including Ceuta, Melilla, and the Canary Islands), and Sweden.
- Non-EU members: Andorra, Iceland, Liechtenstein, Monaco, Norway, San Marino, Switzerland, United Kingdom (including Gibraltar), and Vatican City State/Holy See.
SEPA's scope with all of these countries and territories depends on licensing and local regulations. Refer to the EPC's official list for more information.
SEPA availability​
SEPA follows the Governing Council of the European Central Bank's Trans-European Automated Real-time Gross settlement Express Transfer (TARGET) system. TARGET closing days were established in the year 2000, so this system is long-standing and predictable.
The SEPA network is unavailable on TARGET closing days:
- Saturdays and Sundays
- New Year's Day
- Good Friday
- Easter Monday
- 1 May (Labor Day)
- Christmas Day
- 26 December
Transactions sent on TARGET closing days are processed the next open day. The only exceptions are Instant SEPA Credit Transfers, which are always exchanged immediately (24 hours a day, 7 days a week, 365 days a year).
Refer to the European Central Bank's operational status page for in-the-moment availability, or their working hours page for the precise dates of upcoming TARGET closing days.