diff --git a/docs/glossary.mdx b/docs/glossary.mdx index 4e00526196..3562a6c680 100644 --- a/docs/glossary.mdx +++ b/docs/glossary.mdx @@ -160,6 +160,80 @@ import MerchantsDefinition from './topics/definitions/_merchants.mdx'; *** +import OpenBankingDefinition from './topics/definitions/_open-banking.mdx'; + +import AisDefinition from './topics/definitions/_ais.mdx'; + +import AispDefinition from './topics/definitions/_aisp.mdx'; + +import BerlinGroupDefinition from './topics/definitions/_berlin-group.mdx'; + +import BulkPisDefinition from './topics/definitions/_bulk-pis.mdx'; + +import ConsentTokenDefinition from './topics/definitions/_consent-token.mdx'; + +import PisDefinition from './topics/definitions/_pis.mdx'; + +import PispDefinition from './topics/definitions/_pisp.mdx'; + +import Psd2Definition from './topics/definitions/_psd2.mdx'; + +import SaltEdgeDefinition from './topics/definitions/_salt-edge.mdx'; + +import ScaDefinition from './topics/definitions/_sca.mdx'; + +import TppDefinition from './topics/definitions/_tpp.mdx'; + +## [Open Banking](topics/open-banking/index.mdx) {#open-banking} + + + +### [Account Information Service (AIS)](topics/open-banking/ais.mdx) {#ais} + + + +### Account Information Service Provider (AISP) {#aisp} + + + +### Berlin Group {#berlin-group} + + + +### Bulk Payment Initiation Service (Bulk PIS) {#bulk-pis} + + + +### Consent token {#consent-token} + + + +### [Payment Initiation Service (PIS)](topics/open-banking/pis.mdx) {#pis} + + + +### Payment Initiation Service Provider (PISP) {#pisp} + + + +### PSD2 {#psd2} + + + +### Salt Edge {#salt-edge} + + + +### Strong Customer Authentication (SCA) {#sca} + + + +### Third-Party Provider (TPP) {#tpp} + + + +*** + import PaymentDefinition from './topics/definitions/_payments.mdx'; ## [Payment](topics/payments/index.mdx) {#payments} @@ -178,7 +252,7 @@ import PaymentMandateDefinition from './topics/definitions/_payment-mandate.mdx' -Several Swan features can require payment mandates, including [account funding](./topics/accounts/funding/index.mdx#mandates), [accepting payments](./topics/merchants/online/sdd/index.mdx#mandates), and [received payment mandates for SEPA Direct Debit](./topics/payments/direct-debit/index.mdx#mandates). +Several Swan features may require payment mandates, including [account funding](./topics/accounts/funding/index.mdx#mandates), [accepting payments](./topics/merchants/online/sdd/index.mdx#mandates), and [received payment mandates for SEPA Direct Debit](./topics/payments/direct-debit/index.mdx#mandates). *** diff --git a/docs/topics/definitions/_ais.mdx b/docs/topics/definitions/_ais.mdx new file mode 100644 index 0000000000..76b84e5bf4 --- /dev/null +++ b/docs/topics/definitions/_ais.mdx @@ -0,0 +1,2 @@ +An Open Banking service that lets a Third-Party Provider retrieve account information from a user's payment account. +The Account Information Service (AIS) covers account details, balances, and transaction history, accessed under PSD2 with the user's consent. diff --git a/docs/topics/definitions/_aisp.mdx b/docs/topics/definitions/_aisp.mdx new file mode 100644 index 0000000000..2f31e0509d --- /dev/null +++ b/docs/topics/definitions/_aisp.mdx @@ -0,0 +1,2 @@ +A Third-Party Provider authorized to access account information on behalf of a user. +Account Information Service Providers (AISPs) can read account balances and transaction history after the user grants explicit consent. diff --git a/docs/topics/definitions/_berlin-group.mdx b/docs/topics/definitions/_berlin-group.mdx new file mode 100644 index 0000000000..d0b7c483d0 --- /dev/null +++ b/docs/topics/definitions/_berlin-group.mdx @@ -0,0 +1,2 @@ +A pan-European standards initiative that defines the API specifications most banks use for Open Banking. +Swan's Open Banking interface follows the Berlin Group standard, which gives Third-Party Providers a consistent way to access accounts across the European Economic Area. diff --git a/docs/topics/definitions/_bulk-pis.mdx b/docs/topics/definitions/_bulk-pis.mdx new file mode 100644 index 0000000000..820deb6089 --- /dev/null +++ b/docs/topics/definitions/_bulk-pis.mdx @@ -0,0 +1,2 @@ +An Open Banking service that lets a Third-Party Provider initiate several payments in a single request. +Bulk Payment Initiation Service (Bulk PIS) is primarily used by accounting and treasury tools to batch outgoing SEPA Credit Transfers. diff --git a/docs/topics/definitions/_consent-token.mdx b/docs/topics/definitions/_consent-token.mdx new file mode 100644 index 0000000000..40847d301c --- /dev/null +++ b/docs/topics/definitions/_consent-token.mdx @@ -0,0 +1,2 @@ +A 180-day token granting a Third-Party Provider Open Banking access to a user's Swan account. +The consent token is issued after the user completes Strong Customer Authentication and must be renewed every 180 days, as required by PSD2. diff --git a/docs/topics/definitions/_open-banking.mdx b/docs/topics/definitions/_open-banking.mdx new file mode 100644 index 0000000000..6086379aa9 --- /dev/null +++ b/docs/topics/definitions/_open-banking.mdx @@ -0,0 +1,2 @@ +A European framework that lets users grant regulated third parties access to their payment accounts. +Swan's Open Banking service lets licensed providers retrieve account information and initiate payments on behalf of Swan account holders, under PSD2. diff --git a/docs/topics/definitions/_pis.mdx b/docs/topics/definitions/_pis.mdx new file mode 100644 index 0000000000..6a62af3630 --- /dev/null +++ b/docs/topics/definitions/_pis.mdx @@ -0,0 +1,2 @@ +An Open Banking service that lets a Third-Party Provider initiate a payment from a user's account. +The Payment Initiation Service (PIS) requires the user to grant consent for each payment. diff --git a/docs/topics/definitions/_pisp.mdx b/docs/topics/definitions/_pisp.mdx new file mode 100644 index 0000000000..37d4778da6 --- /dev/null +++ b/docs/topics/definitions/_pisp.mdx @@ -0,0 +1,2 @@ +A Third-Party Provider authorized to initiate payments on behalf of a user. +Payment Initiation Service Providers (PISPs) can request SEPA Credit Transfers from a user's account after the user grants explicit consent for each payment. diff --git a/docs/topics/definitions/_psd2.mdx b/docs/topics/definitions/_psd2.mdx new file mode 100644 index 0000000000..ceb1379efd --- /dev/null +++ b/docs/topics/definitions/_psd2.mdx @@ -0,0 +1,2 @@ +The second Payment Services Directive, an EU regulation that governs electronic payment services across the European Economic Area. +PSD2 requires banks to give regulated Third-Party Providers access to payment accounts through Open Banking interfaces, with the account holder's consent. diff --git a/docs/topics/definitions/_salt-edge.mdx b/docs/topics/definitions/_salt-edge.mdx new file mode 100644 index 0000000000..264f2c51bd --- /dev/null +++ b/docs/topics/definitions/_salt-edge.mdx @@ -0,0 +1,2 @@ +Swan's PSD2 compliance platform for Open Banking. +Salt Edge sits between Third-Party Providers and Swan, managing TPP registration, authentication flows, and data formatting to the Berlin Group standard. diff --git a/docs/topics/definitions/_sca.mdx b/docs/topics/definitions/_sca.mdx new file mode 100644 index 0000000000..0b6d4c773e --- /dev/null +++ b/docs/topics/definitions/_sca.mdx @@ -0,0 +1,2 @@ +A PSD2 requirement that protects sensitive banking actions with two independent authentication factors. +Strong Customer Authentication (SCA) combines something the user has (such as their phone) with something they know or are (such as a passcode or biometric), and is required for Open Banking consent and payment confirmation. diff --git a/docs/topics/definitions/_tpp.mdx b/docs/topics/definitions/_tpp.mdx new file mode 100644 index 0000000000..ded6c4a319 --- /dev/null +++ b/docs/topics/definitions/_tpp.mdx @@ -0,0 +1,2 @@ +A regulated company licensed to access bank data or initiate payments on a user's behalf. +Third-Party Providers (TPPs) are authorized under PSD2 and connect to Swan accounts through Salt Edge, Swan's compliance platform. diff --git a/docs/topics/open-banking/ais.mdx b/docs/topics/open-banking/ais.mdx new file mode 100644 index 0000000000..11b0727ed5 --- /dev/null +++ b/docs/topics/open-banking/ais.mdx @@ -0,0 +1,127 @@ +--- +title: Account Information Service (AIS) +--- + +# Account Information Service (AIS) + +import AisDefinition from '../definitions/_ais.mdx'; + +> + +## What TPPs can access {#access} + +- Account list and details. +- Account balances (available, booked, and pending). +- Transaction history, with filtering and pagination. + +## AIS flow {#flow} + +The diagram below shows the full AIS sequence, from the moment the user connects their Swan account to the software application receiving the account data. + +```mermaid +sequenceDiagram +autonumber +participant User +participant SoftwareApp as Software application +participant TPP +participant SaltEdge as Salt Edge +participant Swan + User->>SoftwareApp: Wants to connect their Swan account + SoftwareApp->>TPP: Requests the bank connection + TPP->>SaltEdge: Sends authorization request + SaltEdge->>Swan: PSD2 Connector starts the consent flow + Swan-->>User: Redirects to Swan consent application + User->>Swan: Authenticates with SCA and grants consent + Swan-->>SaltEdge: Returns the access token + SaltEdge-->>TPP: Forwards the access token + TPP->>SaltEdge: Requests account data + SaltEdge->>Swan: Fetches account data + Swan-->>SaltEdge: Returns balances and transactions + SaltEdge-->>TPP: Forwards account data + TPP-->>SoftwareApp: Delivers data, which the software displays to the user +``` + +## Common AIS use cases {#use-cases} + +- Accounting and financial management software importing bank transactions automatically. +- Personal finance management apps aggregating balances across multiple banks. +- Business expense tracking and reconciliation tools. + +## Access conditions {#conditions} + +- The [Swan user](/topics/users/) must authenticate and grant explicit consent. +- The user must have an active [account membership](/topics/accounts/memberships/) with the `canViewAccount` permission. +- Consent must be valid, meaning it has not expired or been revoked. +- The connection must be active, meaning Salt Edge's daily refresh is working. + +## Transaction history {#transaction-history} + +- By default, Swan returns all transactions since account creation, including cards and transfers. +- TPPs commonly filter results to the last 3 months on their end. +- Some TPPs expose an endpoint that lets users retrieve transaction history beyond 3 months. + +## Account scope {#account-scope} + +By default, Swan returns all accounts the user has access to. + +:::note All or nothing +The consent flow does not currently allow users to select a subset of accounts; it is all or nothing. +This is a known limitation of the current consent flow. +::: + +## No accounts visible after authentication {#troubleshooting-no-accounts} + +This most often happens when a user authenticates with their **personal phone number**, but their Swan account is tied to their **professional phone number**. +The phone number is Swan's unique [user](/topics/users/) identifier, so authentication succeeds but returns no accounts. + +**Solutions**: + +- **Option 1, try with the correct phone number**: authenticate again using the professional phone number linked to the Swan account. +- **Option 2, transfer accounts to the personal phone number**: + 1. If the personal phone number is already linked to another Swan user, that user must first be deactivated to free the number (see the [`deactivateUser` mutation preconditions](/topics/users/overview/guide-deactivate)). + 1. The user linked to the professional phone number (and to the accounts) then changes their phone number to the personal one at [link.swan.io/edit-phone](https://link.swan.io/edit-phone). + 1. Once complete, the accounts are accessible using the personal phone number. + +For complex cases involving multi-project users, contact [Swan Support](https://supportform.swan.io/). + +## Transaction field mapping {#field-mapping} + +The table below maps Swan's internal transaction fields to the external fields exposed through Salt Edge, following the Berlin Group standard. + +| Internal field (Swan) | External field (Salt Edge) | Notes | +|---|---|---| +| `id` | `id` | | +| `amount.value` | `amount` | Negative string for debit, positive for credit. | +| `amount.currency` | `currency` | Currency code, such as `EUR` or `USD`. | +| `statusInfo.bookingDate` | `booking_date` | Optional. Date in `YYYY-MM-DD` format. | +| `statusInfo.status` | `status` | Only `Booked` and `Pending` transactions are exposed. `Rejected` transactions are not served through AIS. | +| `statusInfo.valueDate` when `Booked`, otherwise `updatedAt` | `value_date` | Date in `YYYY-MM-DD` format. When the transaction is not booked, this refers to the `updatedAt` date. | +| `label` | `remittance_information.unstructured` | Transaction label or description. Swan defaults to something like `Transfer to/from X` if the input was empty when initiating a SEPA Credit Transfer. | +| `reference` | `remittance_information.structured` | Structured payment reference. | +| `paymentId` | `extra.additional_information` | Not the same as the transaction ID. A payment can have multiple transactions, for example for fees. | +| For SCTs: `creditor.name`. Else if user is on the credit side: `account.holder.info.name`. Else: `counterparty`. | `creditor_details.name` | Creditor or recipient name. | +| `creditor.IBAN` | `creditor_details.account.iban` | Optional. Always served when the transaction is a SEPA Credit Transfer or the end user is on the credit side. | +| `creditor.currency` | `creditor_details.account.currency` | Optional. Only served when the end user is on the credit side. | +| For SCTs: `debtor.name`. Else if user is on the debit side: `account.holder.info.name`. Else: `counterparty`. | `debtor_details.name` | Debtor or payer name. | +| `debtor.IBAN` | `debtor_details.account.iban` | Optional. Always served when the transaction is a SEPA Credit Transfer or the end user is on the debit side. | +| `debtor.currency` | `debtor_details.account.currency` | Optional. Only served when the end user is on the debit side. | + +:::note Why rejected transactions are not served +Rejected transactions were never actually debited or credited. +They represent failed payment attempts rather than completed financial movements, so they are excluded from AIS data. +::: + +:::caution Reconciliation: do not use `value_date` for pending transactions +For pending transactions, `value_date` maps to `updatedAt`, which changes every time the transaction is updated. + +Instead: + +- Use `id` as the stable unique key across all states. +- Use `booking_date` as the date anchor. +- Only reconcile transactions with status `Booked`. +::: + +## References {#references} + +- [Salt Edge transaction docs](https://priora.saltedge.com/docs/aspsp/v2/swan/ais#connector-endpoints-accounts-accounts-transactions). +- [Swan Transaction interface](https://api-reference.swan.io/interfaces/transaction). diff --git a/docs/topics/open-banking/index.mdx b/docs/topics/open-banking/index.mdx new file mode 100644 index 0000000000..aae01b1eb1 --- /dev/null +++ b/docs/topics/open-banking/index.mdx @@ -0,0 +1,237 @@ +--- +title: Open Banking +--- + +# Open Banking + +import OpenBankingDefinition from '../definitions/_open-banking.mdx'; +import TppDefinition from '../definitions/_tpp.mdx'; +import AispDefinition from '../definitions/_aisp.mdx'; +import PispDefinition from '../definitions/_pisp.mdx'; +import AisDefinition from '../definitions/_ais.mdx'; +import PisDefinition from '../definitions/_pis.mdx'; +import BulkPisDefinition from '../definitions/_bulk-pis.mdx'; +import Psd2Definition from '../definitions/_psd2.mdx'; +import BerlinGroupDefinition from '../definitions/_berlin-group.mdx'; +import SaltEdgeDefinition from '../definitions/_salt-edge.mdx'; +import ScaDefinition from '../definitions/_sca.mdx'; +import ConsentTokenDefinition from '../definitions/_consent-token.mdx'; + +## Overview {#overview} + +> + +Swan uses Salt Edge as the PSD2 compliance platform that connects Third-Party Providers (TPPs) to Swan's accounts. + +Swan supports three Open Banking services. + +| Service | Abbreviation | Description | +|---|---|---| +| Account Information Service | AIS | TPPs can access account balances and transaction history. | +| Payment Initiation Service | PIS | TPPs can initiate SEPA Credit Transfers directly from accounts. | +| Bulk Payment Initiation Service | Bulk PIS | TPPs can initiate batched SEPA Credit Transfers directly from accounts. | + +:::tip Open Banking vs Swan GraphQL API +Swan's GraphQL API allows partners to embed banking services into their products. +The Open Banking API enables regulated TPPs to offer aggregation and payment services to users who already hold Swan accounts. +These are two distinct access models. +::: + +## How it works {#how-it-works} + +An Open Banking flow involves three parties: a software application (such as accounting or financial management software), a TPP (a regulated aggregator the software works with), and a [Swan user](/topics/users/). + +The connection is established as follows. + +1. The user works with a software application and wants to connect their Swan account to it. +1. The software relies on a TPP to establish the bank connection. +1. The TPP sends an authorization request to Salt Edge, Swan's PSD2 compliance platform. +1. Salt Edge redirects the user to Swan's consent application. +1. The user authenticates with [Strong Customer Authentication (SCA)](/topics/users/consent/#sca). +1. The user grants explicit consent to the TPP on behalf of the software. +1. Salt Edge receives an access token and enables data access or payment initiation. +1. The software application can now access account data (AIS) or initiate payments (PIS) on behalf of the user. + +:::note TPPs don't connect to Swan directly +All requests go through Salt Edge, which acts as the compliance layer between TPPs and Swan. +::: + +## Architecture {#architecture} + +```mermaid +%%{ init: { 'flowchart': { 'curve': 'linear' } } }%% +flowchart TB + U([User]) --> SA([Software application]) + SA --> TPP([TPP aggregator]) + TPP --> SE([Salt Edge
PSD2 compliance platform]) + SE --> PC([PSD2 Connector
Swan]) + PC --> API([Swan GraphQL API
and core systems]) +``` + +| Component | Role | +|---|---| +| Software application | The application the end user interacts with, such as accounting, finance, or ERP tools. | +| TPP | Regulated aggregator the software works with to access bank data or initiate payments. | +| Salt Edge | PSD2 compliance platform that manages TPP registration, authentication flows, and data formatting to the Berlin Group standard. | +| PSD2 Connector | Integration layer between Salt Edge and Swan's core systems. | +| Swan GraphQL API | Source of account data and payment execution. | + +## Ecosystem {#ecosystem} + +Open Banking relies on a network of regulated TPPs that connect banking data to software applications. + +### Connected TPPs {#ecosystem-tpps} + +:::note +This list reflects TPPs registered with Swan's Open Banking infrastructure as of May 2026. +The list is maintained by Salt Edge and may change. +::: + +| Legal entity | Commercial name | Type | Country | Description | +|---|---|---|---|---| +| Bridge | **Bridge** | AIS and PIS | πŸ‡«πŸ‡· France | Open Banking API for payment initiation and financial data aggregation. | +| Linxo | **Linxo Connect** | AIS and PIS | πŸ‡«πŸ‡· France | Open Banking solutions by Linxo Group, a CrΓ©dit Agricole subsidiary. | +| Fintecture | **Fintecture** | AIS and PIS | πŸ‡«πŸ‡· France | Payment initiation and bank data platform for B2B payments. | +| Powens | **Powens** (formerly Budget Insight) | AIS | πŸ‡«πŸ‡· France | European Open Finance platform for account aggregation and financial data. | +| SI-Expertise | **SI-Expertise** | AIS | πŸ‡«πŸ‡· France | French regulated TPP. | +| Wildmee | **Wildmee** | AIS | πŸ‡«πŸ‡· France | French regulated TPP. | +| finAPI GmbH | **finAPI** | AIS and PIS | πŸ‡©πŸ‡ͺ Germany | German Open Banking platform, used for accounting and ERP integrations. | +| fino run GmbH | **fino.digital** | AIS | πŸ‡©πŸ‡ͺ Germany | AI-based account analysis and Open Banking solutions for businesses. | +| MRH applications GmbH | **MRH applications** | AIS | πŸ‡©πŸ‡ͺ Germany | German regulated TPP. | +| GoCardless | **GoCardless** | AIS | πŸ‡¬πŸ‡§ UK | Global payment and bank debit platform. | +| Unlimit EU Ltd | **Unlimit** | PIS | πŸ‡¨πŸ‡Ύ Cyprus | Global fintech offering payment processing, BaaS, and Open Banking payment initiation services. | +| iban-XS B.V. | **ibanXS** | AIS and PIS | πŸ‡³πŸ‡± Netherlands | PSD2-regulated payment and Open Banking services across Europe. | +| Isabel NV/SA | **Ponto** | AIS | πŸ‡§πŸ‡ͺ Belgium | B2B Open Banking platform for accounting and ERP integrations. | +| Digiteal SA | **Digiteal** | AIS and PIS | πŸ‡§πŸ‡ͺ Belgium | E-invoice presentment, electronic payments, and Open Banking. | +| BudgetBakers s.r.o. | **Wallet by BudgetBakers** | AIS | πŸ‡¨πŸ‡Ώ Czech Republic | Personal finance management app with over 10 million users. | +| SPENDEE a.s. | **Spendee** | AIS | πŸ‡¨πŸ‡Ώ Czech Republic | Money manager and budget planner app. | + +### Accounting and financial software {#ecosystem-software} + +The following table lists some of the accounting and financial software in Swan's markets and the TPP each one uses to access bank data, as of July 2026. This list isn't exhaustive. + +| Software | Country | TPP | Service | +|---|---|---|---| +| **Pennylane** | πŸ‡«πŸ‡· France | Bridge | AIS | +| **MyUnisoft** | πŸ‡«πŸ‡· France | Powens | AIS | +| **Holded** | πŸ‡ͺπŸ‡Έ Spain | GoCardless | AIS | +| **Sage** | πŸ‡«πŸ‡· France and Europe | Bridge | AIS | +| **Inqom** | πŸ‡«πŸ‡· France | Bridge | AIS | +| **EBP** | πŸ‡«πŸ‡· France | Powens | AIS | +| **Xero** | πŸ‡¬πŸ‡§ UK and Europe | Yodlee | AIS | +| **DATEV** | πŸ‡©πŸ‡ͺ Germany | finAPI | AIS | +| **Cegid Quadra** | πŸ‡«πŸ‡· France | Proprietary | AIS | + +:::tip Open Banking or direct API access +If a user's accounting software is different from their Swan partner, they connect their Swan account through the Open Banking consent flow, using the TPP chosen by that software. + +If the accounting software **is** the Swan partner, Open Banking isn't involved: the partner already has real-time access to the user's transactions through the [Swan API](/developers/). +::: + +## Authentication and consent {#auth-consent} + +### Strong Customer Authentication {#sca} + +> + +Every Open Banking connection requires SCA. +This works the same way as when a Swan user logs into Web Banking or initiates a payment: two authentication factors are required. + +1. **Possession factor**: the user receives a 6-digit OTP code by SMS, tied to their phone or SIM card. +1. **Knowledge or inherence factor**: the user enters their 6-digit passcode, or uses Face ID or Touch ID. + +### Token architecture {#tokens} + +Two separate tokens govern the Open Banking connection. + +| Token | Lifecycle | Managed by | Description | +|---|---|---|---| +| User consent token | 180 days | TPP and Salt Edge | Grants the TPP access to account data. Requires user SCA to renew. | +| Technical refresh token | 24 hours | Swan and Salt Edge | Maintains the data refresh connection. Renewed automatically. | + +:::note User token renewal +Every 180 days, the user must re-authenticate with SCA to renew the consent token. +PSD2 requires this. +Renewal is initiated by the TPP through Salt Edge. +Swan cannot trigger this renewal directly. +::: + +:::note Technical token refresh +Most TPPs can perform up to 4 refreshes per day, see the [PSD2 EBA Q&A on refresh frequency](https://www.eba.europa.eu/single-rule-book-qa/qna/view/publicId/2018_4210). +::: + +### Consent validity {#consent-validity} + +- **AIS**: one consent grants data access for up to 180 days, then requires re-authentication. +- **PIS**: each payment requires its own consent. + +:::note Transactions since account creation +The 180-day limit applies to how long the consent grants data access, not to the time range of transactions you can view. +By default, Swan returns all transactions since the account was created. +::: + +### Consent revocation {#consent-revocation} + +The user consent token can be revoked by the TPP, following a request from the end user. + +:::tip Under PSD3 +With PSD3 (the third Payment Services Directive), allowing end users to revoke their consent directly from their online banking interface will become mandatory. +::: + +## Registration and testing {#testing} + +To get access, TPPs first apply to Salt Edge at [compliance-hub@saltedge.com](mailto:compliance-hub@saltedge.com). +Salt Edge reviews the application and, if approved, grants access to their platform and Swan's PSD2 API. +Testing happens in Salt Edge's own sandbox, not in Swan's Sandbox environment. + +## Key concepts {#key-concepts} + +The following terms appear throughout Swan's Open Banking documentation. + +### Open Banking + + + +### Third-Party Provider (TPP) + + + +### Account Information Service Provider (AISP) + + + +### Payment Initiation Service Provider (PISP) + + + +### Account Information Service (AIS) + + + +### Payment Initiation Service (PIS) + + + +### Bulk Payment Initiation Service (Bulk PIS) + + + +### PSD2 + + + +### Berlin Group + + + +### Salt Edge + + + +### Strong Customer Authentication (SCA) + + + +### Consent token + + diff --git a/docs/topics/open-banking/pis.mdx b/docs/topics/open-banking/pis.mdx new file mode 100644 index 0000000000..8815069bd5 --- /dev/null +++ b/docs/topics/open-banking/pis.mdx @@ -0,0 +1,93 @@ +--- +title: Payment Initiation Service (PIS) +--- + +# Payment Initiation Service (PIS) + +import PisDefinition from '../definitions/_pis.mdx'; + +> + +## Supported payment types {#supported} + +- SEPA Credit Transfers (regular and instant). +- Bulk payments. + +## Unsupported payment types {#unsupported} + +- Standing orders and recurring payments. +- International Credit Transfers. + +## PIS flow {#flow} + +The diagram below shows the full PIS sequence, from the moment the user initiates a payment in their software application to the final confirmation message. + +```mermaid +sequenceDiagram +autonumber +participant User +participant SoftwareApp as Software application +participant TPP +participant SaltEdge as Salt Edge +participant Swan + User->>SoftwareApp: Initiates payment + SoftwareApp->>TPP: Sends payment initiation request + TPP->>SaltEdge: Forwards request + SaltEdge->>Swan: PSD2 Connector creates PaymentSession + Swan-->>User: Redirects to Swan consent application + User->>Swan: Completes OAuth consent (SCA) + User->>Swan: Selects Swan account to use as debtor account + Swan->>Swan: Initiates credit transfer pending consent + User->>Swan: Reviews payment details + User->>Swan: Confirms payment with payment consent (SCA) + Swan->>Swan: Executes the transfer + Swan-->>SaltEdge: Sends status update via webhook + SaltEdge-->>TPP: Forwards status update + TPP-->>SoftwareApp: Notifies software application, which displays confirmation to the user +``` + +### References {#references} + +- [Salt Edge PIS docs](https://priora.saltedge.com/docs/aspsp/v2/swan/pis). + +## Payment session statuses {#statuses} + +Single payments have a payment session status only. +Bulk payments have both a payment session status for the whole bulk and a per-transaction status. + +The payment session status reflects the overall state of a payment. +Single and bulk payments share the same statuses, except `PART`, which applies to bulk payments only. + +| Status | Type | Applies to | Meaning | Swan transaction status | Sent when | +|---|---|---|---|---|---| +| `RCVD` | Ongoing | Single and bulk | Received | β€” | Payment session created, no transactions linked yet, consent pending. | +| `PDNG` | Ongoing | Single and bulk | Pending | `Pending` | At least one transaction is `Pending`. | +| `ACSC` | Final | Single and bulk | Accepted, settlement completed | `Booked` | All transactions are `Booked`. | +| `RJCT` | Final | Single and bulk | Rejected | `Rejected` | All transactions are `Rejected`, or the authentication or payment consent failed (`CustomerRefused`, `CredentialRefused`, `Expired`, `Failed`, `Canceled`). | +| `PART` | Final | Bulk only | Partially accepted | `Booked` and/or `Rejected` | All transactions are either `Booked` or `Rejected`. | + +## Bulk detailed status {#bulk-detailed-status} + +For a bulk payment, each individual payment also has its own status, returned by the bulk detailed status endpoint using ISO 20022 codes. + +| Status | Type | Meaning | Swan transaction status | Sent when | +|---|---|---|---|---| +| `RCVD` | Ongoing | Received | β€” | Default. No transaction is linked to the payment yet, consent is pending, and the internal `initiateCreditTransfer` request hasn't been made. | +| `PDNG` | Ongoing | Pending | `Pending` | The transaction is `Pending`. | +| `ACSC` | Final | Accepted, settlement completed | `Booked` | The transaction is `Booked`. | +| `RJCT` | Final | Rejected | `Rejected` | The transaction is `Rejected`, or the payment session consent failed. | + +:::note Rejection reasons +When a transaction is `RJCT`, a `rejectedReasonText` explains why. + +- **Failed consent**, whether the authentication or the payment consent: one of `ConsentCustomerRefused`, `ConsentCredentialRefused`, `ConsentExpired`, `ConsentFailed`, or `ConsentCanceled`. +- **Failed payment**: a [`RejectedReasonCode`](https://api-reference.swan.io/enums/rejected-reason-code). +::: + +## FAQ {#faq} + +### I validated my consent but don't see any transaction + +The PIS flow has two SCA steps: an OAuth consent and a separate payment consent. +Validating only the first won't create a transaction. +Make sure the payment consent is validated too. diff --git a/sidebars.js b/sidebars.js index e4367a0861..9eb917c2f8 100644 --- a/sidebars.js +++ b/sidebars.js @@ -395,6 +395,24 @@ module.exports = { }, ], }, + { + type: "category", + label: "Open Banking", + collapsible: false, + collapsed: false, + items: [ + { + type: "category", + label: "Overview", + link: { type: "doc", id: "topics/open-banking/index" }, + collapsed: true, + items: [ + "topics/open-banking/ais", + "topics/open-banking/pis", + ], + }, + ], + }, { type: "category", label: "Payments",