Doc 1776/open banking partner documentation on docsswanio

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}
+
+<OpenBankingDefinition />
+
+### [Account Information Service (AIS)](topics/open-banking/ais.mdx) {#ais}
+
+<AisDefinition />
+
+### Account Information Service Provider (AISP) {#aisp}
+
+<AispDefinition />
+
+### Berlin Group {#berlin-group}
+
+<BerlinGroupDefinition />
+
+### Bulk Payment Initiation Service (Bulk PIS) {#bulk-pis}
+
+<BulkPisDefinition />
+
+### Consent token {#consent-token}
+
+<ConsentTokenDefinition />
+
+### [Payment Initiation Service (PIS)](topics/open-banking/pis.mdx) {#pis}
+
+<PisDefinition />
+
+### Payment Initiation Service Provider (PISP) {#pisp}
+
+<PispDefinition />
+
+### PSD2 {#psd2}
+
+<Psd2Definition />
+
+### Salt Edge {#salt-edge}
+
+<SaltEdgeDefinition />
+
+### Strong Customer Authentication (SCA) {#sca}
+
+<ScaDefinition />
+
+### Third-Party Provider (TPP) {#tpp}
+
+<TppDefinition />
+
+***
+
 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'
 
 <PaymentMandateDefinition />
 
-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).
 
 
 ***

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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';
+
+> <AisDefinition />
+
+## 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).