openapi: 3.0.0 info: version: 6.0.0 title: Common Account API description: | This specification defines a simple API to access information about bank accounts. The API is supposed to be used by customers who want to get information about their accounts such as current balance or transactions. This specification uses schema definitions from the Common Data Model v1.2.1. termsOfService: tbd contact: email: info@common-api.ch license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: account.common-api.ch/api/v5 externalDocs: description: Find out more about SFTI API specifications. url: https://www.common-api.ch tags: - name: accounts description: Third party access to bank account service considering account information and transaction data operations (JSON). - name: iso20022 description: Third party access to bank account service considering camt operations (XML). security: - OAuth2: - read - write paths: /accounts: get: tags: - accounts summary: Get a list of all accounts description: | Get a list of all accounts for the authenticated context. The response contains an `accounts` array; if no accounts are available, the array is empty (for example: `{"accounts": []}`). Pagination is controlled via the `cursor` and `limit` query parameters. If more accounts are available, the `X-Next-Cursor` response header provides the cursor value for the next page. operationId: listAccounts parameters: - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: Paginated list of all accounts. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Next-Cursor: $ref: '#/components/headers/X-Next-Cursor' content: application/json: schema: type: object required: - accounts properties: accounts: type: array items: $ref: '#/components/schemas/AccountItem' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /accounts/{accountId}: get: tags: - accounts summary: Get an account description: Get the details of a specific account. operationId: getAccount parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: The details of the specified account. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/AccountItem' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /accounts/{accountId}/balance: get: tags: - accounts summary: Get the balance of an account description: | Returns account balance information of the specified account. * Returns the interim booked balance (ISO20022 Balance Type ITBD) for the current day, if called without a date. The balance is calculated in the course of the service provider's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. * Returns the closing booked balance (ISO20022 Balance Type CLBD) for a specific day, if called for a past date. It is the sum of the opening booked balance at the beginning of that day and all entries booked to the account during that day. In case the specified day has not yet been finalized, the response code will be 202. operationId: getAccountBalance parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/date' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: The account balance of the specified account. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/AccountBalanceItem' '202': $ref: '#/components/responses/standard202' '204': $ref: '#/components/responses/standard204' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /accounts/{accountId}/transactions: get: tags: - accounts summary: Get a list of all transactions of an account externalDocs: description: A detailed description of how this endpoint is used is available in the wiki. url: https://github.com/swissfintechinnovations/ca-payment/wiki/Transaction-Endpoint-Factsheet description: | Returns a paginated list of transactions for the specified account. * When called without a date, it returns all transactions since the last completed booking day. Both "pending" and "booked" entries may be included based on the entryStatus parameter. * When called with a date range, only "booked" transactions from completed booking days are returned. For days not yet finalized, a 202 response code is returned. If no transactions match the requested date range or intraday window, return an empty list: {"entries": []}. Results are sorted by bookingDate in descending order. Additional sorting logic is provider-specific but all providers must ensure stable and consistent pagination behavior. If pagination is required, the server includes an opaque cursor in the `X-Next-Cursor` header. This cursor identifies a specific position in the sorted result set and is internally derived from the sorting criteria. Clients must pass this value unchanged in the `cursor` parameter of the next request to retrieve subsequent pages. Transaction details are optional in the schema, but all available information must be included if present for a given transaction. operationId: listAccountTransactions parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/date_from' - $ref: '#/components/parameters/date_to' - $ref: '#/components/parameters/entry_status' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: List of transactions of the specified account. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Next-Cursor: $ref: '#/components/headers/X-Next-Cursor' content: application/json: schema: $ref: '#/components/schemas/AccountTransactionReport' '202': description: | Accepted - The request is valid, but the requested data is not yet available because the associated booking day is still in progress or not finalized. The request can be repeated at a later time once the data has been finalized. $ref: '#/components/responses/standard202' '204': description: | No Content - The request was successful, but no data is available for the requested date or parameters. No data is expected to become available in the future. This may occur if the requested period is outside the retention scope or if no entries exist for the given account and criteria. $ref: '#/components/responses/standard204' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /accounts/{accountId}/transactions/{entryId}: get: tags: - accounts summary: Get a transaction description: > Get the details of a specific transaction (AccountTransactionItem objects) for the account transaction entry identified by `entryId`. The `entryId` value corresponds to AccountTransactionEntry.accountServicerReference and to the attribute _Ntry ⇾ AcctSvcrRef_ in SPS/ISO-20022. operationId: getAccountTransaction parameters: - $ref: '#/components/parameters/account_id' - $ref: '#/components/parameters/entry_id' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: The details of the specified transaction. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/json: schema: $ref: '#/components/schemas/AccountTransactionEntry' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /iso20022/statements: get: tags: - iso20022 summary: Get a list of resource references to account statements (camt.053) description: | Get a list of resource references to available account statements (camt.053) for all accounts covered by the eBanking contract delivered. The referenced account statements comply with the XML schema and implementation guidelines defined by Swiss Payment Standards (SPS). If the requested period covers multiple days, a separate account statement is provided for each available day and account. If no statements are available for the requested period, an empty list is returned (`{"statements": []}`). Pagination is supported through the `cursor` and `limit` query parameters. When additional results are available, the `X-Next-Cursor` response header contains the cursor value for the next page of results. operationId: listIso20022AccountStatementReferences parameters: - $ref: '#/components/parameters/date_from' - $ref: '#/components/parameters/date_to' - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: List of resource references to ISO20022 XML camt.053 messages. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Next-Cursor: $ref: '#/components/headers/X-Next-Cursor' content: application/json: schema: type: object required: - statements properties: statements: type: array items: $ref: '#/components/schemas/Iso20022ReportReference053' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /iso20022/statements/{reportId}: get: tags: - iso20022 summary: Get a ISO20022 XML camt.053 document description: Get a ISO20022 XML camt.053 document. operationId: getIso20022AccountStatement parameters: - $ref: '#/components/parameters/report_id' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: Returns the requested ISO20022 XML camt.053 message. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/xml: schema: type: string format: binary '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /iso20022/reports: get: tags: - iso20022 summary: Get a list of resource references to account reports (camt.052) description: | Returns a paginated list of resource references to available account reports (camt.052) generated since the last End-of-Day (EOD) processing. Only intraday reports created after the most recent EOD cycle are included. If no reports are available since the last EOD, return an empty list: {"reports": []}. Pagination is supported through the `cursor` and `limit` query parameters. When additional results are available, the `X-Next-Cursor` response header contains the cursor value for the next page of results. The returned account reports must conform to the XML schema and implementation guidelines defined by Swiss Payment Standards. operationId: listIso20022AccountReportReferences parameters: - $ref: '#/components/parameters/cursor' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: List of resource references to ISO20022 XML camt.052 messages. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' X-Next-Cursor: $ref: '#/components/headers/X-Next-Cursor' content: application/json: schema: type: object required: - reports properties: reports: type: array items: $ref: '#/components/schemas/Iso20022ReportReference052' '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' /iso20022/reports/{reportId}: get: tags: - iso20022 summary: Get a ISO20022 XML camt.052 document description: Get a ISO20022 XML camt.052 document. operationId: getIso20022AccountReport parameters: - $ref: '#/components/parameters/report_id' - $ref: '#/components/parameters/authorization' - $ref: '#/components/parameters/client_id' - $ref: '#/components/parameters/correlation' - $ref: '#/components/parameters/agent' - $ref: '#/components/parameters/target_id' - $ref: '#/components/parameters/psu_ip' - $ref: '#/components/parameters/psu_user_agent' responses: '200': description: Returns the requested ISO20022 XML camt.052 message. headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' content: application/xml: schema: type: string format: binary '400': $ref: '#/components/responses/standard400' '401': $ref: '#/components/responses/standard401' '403': $ref: '#/components/responses/standard403' '404': $ref: '#/components/responses/standard404' '405': $ref: '#/components/responses/standard405' '500': $ref: '#/components/responses/standard500' '501': $ref: '#/components/responses/standard501' '503': $ref: '#/components/responses/standard503' components: schemas: AccountBalanceItem: title: Account Balance Item description: The account balance object. type: object required: - balance - balanceType - date properties: balance: $ref: '#/components/schemas/BalanceCurrencyAmount' balanceType: type: string enum: - ITBD - CLBD description: | The account balance type according to ISO20022. Either the interim booked balance (ITBD) or the closing booked balance (CLBD) type can be applied. Corresponds to the attribute _Bal ⇾ Tp_ in SPS/ISO-20022. example: CLBD date: $ref: '#/components/schemas/Date' description: The date for which the balance was retrieved. _links: type: object description: Contains the paths to additional resources for specific account (e.g. path to account and transactions resource). properties: self: type: string example: /accounts/550e8400-e29b-11d4-a716-446655440000/balance account: type: string example: /accounts/550e8400-e29b-11d4-a716-446655440000 transactions: type: string example: /accounts/550e8400-e29b-11d4-a716-446655440000/transactions AccountItem: title: Account Information Item description: The account object. type: object required: - account - accountOwnerName - accountTypeCode - designation - id properties: account: $ref: '#/components/schemas/PaymentIbanAccount' accountOwnerName: $ref: '#/components/schemas/AccountOwnerName' accountTypeCode: type: string description: | Contains the account type code according to the ISO20022 external cash account type code list. It is strongly recommended to use only the 5 codes below as follows: * LOAN: Account used for loans (loan and mortgage accounts) - DE: Darlehenskonto, Kreditkonto, Baukreditkonto, Hypothekarkonto * LLSV: Account used for savings with special interest and withdrawal terms (pension provision and vested benefits accounts) - DE: Vorsorge- und Freizügigkeitskonten * SVGS: Account used for savings (all types of saving accounts) * TRAN: Account used for transactions (all types of personal, current and payment accounts) - DE: Privat-, Kontokorrent- und Zahlungsverkehrskonten * OTHR: Account not otherwise specified (gathering pool for all other accounts) Note: This attribute is required in the Account API, while optional in SPS. Reason: Necessary for the multibanking use case. Ref: Issue#97 example: TRAN enum: - CACC - CARD - CASH - CHAR - CISH - COMM - CPAC - LLSV - LOAN - MGLD - MOMA - NFCA - NREX - ODFT - ONDP - OTHR - SACC - SLRY - SVGS - TAXE - TRAN - TRAS - VACC currency: $ref: '#/components/schemas/Currency' description: The ISO currency three-letter code denominated and set for the account at the time it is opened. designation: $ref: '#/components/schemas/Designation' id: $ref: '#/components/schemas/CommonAccountId' _links: type: object description: Contains the paths to additional resources for specific account (e.g. path to balance and transactions resource). properties: self: type: string example: /accounts/550e8400-e29b-11d4-a716-446655440000 balance: type: string example: /accounts/550e8400-e29b-11d4-a716-446655440000/balance transactions: type: string example: /accounts/550e8400-e29b-11d4-a716-446655440000/transactions AccountOwnerName: type: string maxLength: 140 description: Name of the account holder. Corresponds to the attribute _Acct ⇾ Ownr ⇾ Nm_ in SPS/ISO-20022. example: Account Owner XYZ AccountTransactionBankTransactionCode: title: Account Transaction Bank Transaction Code description: | The bank transaction code (ISO20022) object of an account transaction. Specifies a set of elements to fully identify the type of underlying transaction resulting in an entry. type: object required: - domainCode - familyCode - subFamilyCode properties: domainCode: type: string maxLength: 4 description: | The code of the business area of the underlying transaction according to the "Bank Transaction Code". Corresponds to the attribute _Domn ⇾ Cd_ in SPS/ISO-20022. example: PMNT familyCode: type: string maxLength: 4 description: | The family code within a specific domain according to the "Bank Transaction Code". Corresponds to the attribute _Fmly ⇾ Cd_ in SPS/ISO-20022. example: RCDT subFamilyCode: type: string maxLength: 4 description: | Specifies the sub-family code within a specific domain according to the "Bank Transaction Code". Corresponds to the attribute _SubFmlyCd_ in SPS/ISO-20022. example: DMCT AccountTransactionCounterparty: title: Account Transaction Counterparty description: Specifies the counterparty details (creditor or debtor). type: object properties: account: $ref: '#/components/schemas/AccountTransactionCounterpartyAccount' agent: $ref: '#/components/schemas/AccountTransactionCounterpartyAgent' name: type: string maxLength: 140 description: Name of the counterparty (debtor name if transaction type = CRDT, creditor name if transaction type = DBIT). example: Hans Muster postalAddress: $ref: '#/components/schemas/AccountTransactionStructuredOrUnstructuredAddress' AccountTransactionCounterpartyAccount: title: Account Transaction Counterparty Account description: Specifies the counterparty account (debtor account if transaction type = CRDT creditor account if transaction type = DBIT). type: object required: - identification - type properties: identification: type: string maxLength: 35 description: 'The account identification: IBAN, ISR participant number or bank account number.' example: CH9300762011623852957 type: type: string enum: - IBAN - OTHER description: The account idientification type of the counterparty account, either IBAN or OTHER. example: IBAN AccountTransactionCounterpartyAgent: title: Account Transaction Counterparty Agent description: The account transaction counterparty agent object. type: object properties: bic: type: string minLength: 8 maxLength: 11 description: Corresponds to the attribute CdtrAgt ⇾ FinInstnId ⇾ BIC in SPS/ISO-20022. example: DEUTDE5M101 clearingSystemMemberIdentification: $ref: '#/components/schemas/CommonClearingSystemMemberIdentification' AccountTransactionEntry: title: Account Transaction Entry description: The account transaction entry object. type: object required: - accountServicerReference - additionalEntryInformation - amount - bankTransactionCode - bookingDate - entryStatus - transactionType - valueDate properties: accountServicerReference: type: string description: > Unique reference for the entry, assigned by the financial institution. This value is used as `entryId` in the transactions detail endpoint `/accounts/{accountId}/transactions/{entryId}` to query the details of this entry. Corresponds to the attribute _Ntry ⇾ AcctSvcrRef_ in SPS/ISO-20022. example: 12345ABC6789 maxLength: 35 additionalEntryInformation: type: string description: > Additional entry information. Corresponds to the attribute _AddtlNtryInf_ in SPS/ISO-20022. This attribute is required in the Account API, while optional in SPS. Reason: Necessary for the multibanking use case. Ref: Issue#4. example: Online Shopping Visa Debit Card Nr. xxxx 1234 amount: $ref: '#/components/schemas/PaymentCurrencyAmount' bankTransactionCode: $ref: '#/components/schemas/AccountTransactionBankTransactionCode' bookingDate: $ref: '#/components/schemas/Date' description: The booking date of the transaction set by the bank. Corresponds to the attribute _BookgDt_ in SPS/ISO-20022. entryStatus: type: string enum: - booked - pending description: Indicates the status of an account movement. Corresponds to the attribute _Ntry ⇾ Sts ⇾ Cd_ in SPS/ISO-20022. example: booked transactionType: $ref: '#/components/schemas/AccountTransactionTransactionType' valueDate: $ref: '#/components/schemas/Date' description: The value date of the transaction set by the bank. Corresponds to the attribute _ValDt_ in SPS/ISO-20022. entryReference: type: string description: Booking reference; format depends on booking type. Corresponds to NtryRef in SPS/ISO-20022. example: '10001628' maxLength: 35 entryReferenceInternalId: type: string description: | Additional grouping criteria for business cases ISR and QR-IBAN. Contains the BISR-ID or first 6 characters of the QR reference. example: '123456' maxLength: 35 instructedAmount: $ref: '#/components/schemas/AccountTransactionInstructedAmount' reversalIndicator: type: boolean description: | Indicates if the transaction is a reversing entry. Corresponds to the attribute _RvslInd_ in SPS/ISO-20022. example: true totalChargesAmount: $ref: '#/components/schemas/AccountTransactionItemCharges' transactions: type: array description: Specifies the transaction entries. items: $ref: '#/components/schemas/AccountTransactionItem' AccountTransactionInstructedAmount: title: Account Transaction Instructed Amount description: Specifies the instructed amount. Corresponds to the attribute TxDtls ⇾ AmtDtls ⇾ InstdAmt in SPS/ISO-20022. type: object required: - amount - exchangeRate - sourceCurrency properties: amount: $ref: '#/components/schemas/Amount' description: Corresponds to the attribute TxDtls ⇾ AmtDtls ⇾ InstdAmt ⇾ Amt. sourceCurrency: $ref: '#/components/schemas/Currency' description: | The ISO currency three-letter code which is used to fund a currency conversion. Corresponds to the attribute _SrcCcy_ in SPS/ISO-20022. targetCurrency: $ref: '#/components/schemas/Currency' description: | The ISO currency three-letter code which the recipient will receive after the currency conversion. Corresponds to the attribute _TrgtCcy_ in SPS/ISO-20022. unitCcy: $ref: '#/components/schemas/Currency' description: Currency in which the exchange rate is specified. Corresponds to attribute _UnitCcy_ in SPS/ISO-20022. exchangeRate: type: string pattern: ^\d{1,11}$|^(?=\d+[.]\d+$).{3,12}$ maxLength: 12 description: | The rate at which the source currency will be exchanged for the target currency. Corresponds to the attribute _XchgRate_ in SPS/ISO-20022. example: '0.957' AccountTransactionItem: title: Account Transaction Item description: Specifies the transaction entry item. type: object required: - accountServicerReference - amount - transactionType properties: accountServicerReference: type: string maxLength: 35 description: > Unique booking (transaction) reference assigned by the financial institution. Corresponds to the attribute _TxDtls ⇾ Refs ⇾ AcctSvcrRef_ in SPS/ISO-20022. This reference identifies the individual transaction within an entry and must not be used as `entryId` in the `/accounts/{accountId}/transactions/{entryId}` endpoint. example: 12345ABC6789 amount: $ref: '#/components/schemas/PaymentCurrencyAmount' transactionType: $ref: '#/components/schemas/AccountTransactionTransactionType' additionalTransactionInformation: type: string maxLength: 140 description: Any additional information to the transaction. Corresponds to the attribute _AddtlTxInf_ in SPS/ISO-20022. example: Online Shopping Visa Debit Card Nr. xxxx 1234 bankTransactionCode: $ref: '#/components/schemas/AccountTransactionBankTransactionCode' counterparty: $ref: '#/components/schemas/AccountTransactionCounterparty' endToEndId: type: string maxLength: 35 description: The unique reference of the debtor/creditor. Corresponds to the attribute _EndToEndId_ in SPS/ISO-20022. example: ENDTOENDID-01 instructedAmount: $ref: '#/components/schemas/AccountTransactionInstructedAmount' instructionId: type: string maxLength: 35 description: | ID of the C-Level from the original payment instruction. Corresponds to the attribute _TxDtls ⇾ Refs ⇾ InstrId_ in SPS/ISO-20022. example: 12345ABC6789 remittanceInformation: $ref: '#/components/schemas/PaymentRemittanceInformation' remittanceReference: $ref: '#/components/schemas/AccountTransactionRemittanceReference' totalChargesAmount: $ref: '#/components/schemas/AccountTransactionItemCharges' uetr: type: string pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$ description: | Globally unique reference Reference assigned by the debtor (optional) or by the debtor agent. Corresponds to the attribute _TxDtls ⇾ Refs ⇾ UETR_ in SPS/ISO-20022 example: fdc01a3e-4567-4abc-8def-1234567890ab AccountTransactionItemCharges: title: Account Transaction Item Charges description: Specifies the total amount of account charges. type: object required: - amount - currency properties: amount: $ref: '#/components/schemas/Amount' description: The total amount of account charges. currency: $ref: '#/components/schemas/Currency' description: The ISO currency three-letter code in which the total amount of charges was posed. chargeRecords: type: array description: Specifies the details about individual charges. items: $ref: '#/components/schemas/AccountTransactionItemChargesRecord' AccountTransactionItemChargesRecord: title: Account Transaction Item Charges Record description: Specifies the details about individual charges. type: object required: - amount - currency properties: amount: $ref: '#/components/schemas/Amount' description: The amount of individual charges. transactionType: $ref: '#/components/schemas/AccountTransactionTransactionType' description: Corresponds to the attribute _Chrgs ⇾ Rcrd ⇾ CdtDbtInd_ in SPS/ISO-20022. chargesIncludedIndicator: description: | Indicates whether the charges are included in the entry amount or not. Corresponds to the attribute _ChrgInclInd_ in SPS/ISO-20022. type: boolean example: true currency: $ref: '#/components/schemas/Currency' description: The ISO currency three-letter code in which the amount of individual charges was posed based. type: type: string maxLength: 35 description: The type of charge. Corresponds to the attribute _Chrgs ⇾ Rcrd ⇾ Tp_ in SPS/ISO-20022. example: Some type of charge AccountTransactionRemittanceReference: title: Account Transaction Remittance Reference description: The remittance reference of the account transaction. Specifies the structured reference. type: object required: - reference - type properties: reference: type: string maxLength: 35 description: | The reference number associated to the chosen remittance type. Corresponds to the attribute _RmtInf ⇾ Strd ⇾ CdtrRefInf ⇾ Ref_ in SPS/ISO-20022. example: '210000000003139471430009017' type: type: string enum: - SCOR - ISR - QRR description: The reference type (QRR, SCOR, ISR). Corresponds to the attribute _RmtInf ⇾ Strd ⇾ CdtrRefInf ⇾ Tp_ in SPS/ISO-20022. example: SCOR AccountTransactionReport: title: Account Transaction Report description: The account transaction report object. type: object required: - designation - entries - iban properties: designation: $ref: '#/components/schemas/Designation' entries: type: array description: > Account transaction entry object. Corresponds to attribute Ntry in SPS/ISO-20022. Optional in SPS (camt.052/053), but mandatory in the Account API, where balances and transactions are separated and entries are required for valid GET /transactions responses. items: $ref: '#/components/schemas/AccountTransactionEntry' iban: $ref: '#/components/schemas/IbanIdentification' description: The International Bank Account Number (IBAN), associated with the account. _links: type: object description: Contains the paths to additional resources for specific account (e.g. path to account and balance resource). properties: self: type: string example: /accounts/550e8400e29b11d4a716446655440000/transactions account: type: string example: /accounts/550e8400e29b11d4a716446655440000 balance: type: string example: /accounts/550e8400e29b11d4a716446655440000/balance AccountTransactionStructuredAddress: title: Structured Postal Address for Transactions description: Specifies the details of the counterparty structured address. type: object properties: postCode: type: string maxLength: 16 description: The counterparty post code. Corresponds to the attribute _PstCd_ in SPS/ISO-20022. example: '2501' streetName: type: string maxLength: 70 description: The counterparty street name. Corresponds to the attribute _StrtNm_ in SPS/ISO-20022. example: Rue de la gare townName: type: string maxLength: 35 description: The counterparty town name. Corresponds to the attribute _TwnNm_ in SPS/ISO-20022. example: Biel buildingNumber: type: string maxLength: 16 description: The counterparty building number. Corresponds to the attribute _BldgNb_ in SPS/ISO-20022. example: '24' country: type: string maxLength: 2 description: The counterparty country. Corresponds to the attribute _Ctry_ in SPS/ISO-20022. example: CH AccountTransactionStructuredOrUnstructuredAddress: title: Common Structured or Unstructured Address description: Specifies the counterparty address (debtor address if transaction type = CRDT, creditor address if transaction type = DBIT). type: object properties: structured: $ref: '#/components/schemas/AccountTransactionStructuredAddress' unstructured: $ref: '#/components/schemas/AccountTransactionUnstructuredAddress' AccountTransactionTransactionType: title: Account Transaction Transaction Type description: | The transaction type of the account transaction, either credit (CRDT) or debit (DBIT). Corresponds to the attribute _CdtDbtInd_ in SPS/ISO-20022. type: string enum: - CRDT - DBIT example: CRDT AccountTransactionUnstructuredAddress: title: Unstructured Address for Transactions description: Specifies the details of the counterparty unstructured address. type: object required: - addressLines properties: addressLines: type: array description: The counterparty address lines. Only four address lines allowed. maxItems: 4 example: - Robert Schneider SA - Rue de la gare 24 items: type: string maxLength: 70 country: type: string description: The counterparty country. Corresponds to the attribute _Ctry_ in SPS/ISO-20022. maxLength: 2 example: CH Amount: description: An amount. Corresponds to the attribute _Amt_ in SPS/ISO-20022. type: string maxLength: 18 pattern: ^[0-9]{1,12}([.][0-9]{1,5})?$ example: '10.25' BalanceCurrencyAmount: title: Balance Currency-Amount description: Specifies the requested account balance. Corresponds to the attribute _Bal_ in SPS/ISO-20022. type: object required: - amount - currency properties: amount: type: string pattern: ^-?[0-9]{1,12}([.][0-9]{1,5})?$ maxLength: 18 description: The amount of the requested account balance. example: '10.25' currency: $ref: '#/components/schemas/Currency' description: The ISO currency three-letter code in which the balance and the account are held. CommonAccountId: description: Unique identifier (UUID) of the account for which information shall be retrieved. type: string maxLength: 256 pattern: ^[A-Za-z0-9](([A-Za-z0-9._]|-){0,254}[A-Za-z0-9]){0,1}$ example: abc123_abcxyz.123789.abcxyz.abcxyz_abcxyz_abcxyz_abcxyz_ccccc_123abc CommonClearingSystemMemberIdentification: title: Common Clearing System Member Identification description: Specifies the Information used to identify a member within a clearing system. type: object required: - code - memberId properties: code: type: string maxLength: 5 description: | Identification code of a clearing system. Only "CHBCC" is permitted in Switzerland. Corresponds to the attribute _ClrSysId ⇾ Cd_ in SPS/ISO-20022. example: CHBCC memberId: type: string maxLength: 35 description: | The identification of a clearing system member. Clearing ID (Bank Code, "National Identifier") of the financial institution. Corresponds to the attribute _ClrSysId ⇾ MmbId_ in SPS/ISO-20022. example: '00230' CommonErrorResponse: title: Common Error Response description: The common error response object. type: object required: - detail - title - type properties: detail: type: string description: The details about the common error response. example: Detailed problem description with respect to the current request title: type: string description: The title of the common error response. example: This is the general problem description type: $ref: '#/components/schemas/CommonErrorType' instance: type: string description: The path to the corresponding resource. example: path/to/corresponding/resource status: type: integer format: int32 description: The HTTP status code generated by the origin server. example: 404 CommonErrorType: title: Common Error Type description: Error Types for CommonErrorResponse. type: string enum: - /problems/INVALID_PAYLOAD - /problems/MALFORMED_PAYLOAD - /problems/INVALID_TOKEN - /problems/EXPIRED_TOKEN - /problems/INSUFFICIENT_PRIVILEGES - /problems/NO_ACCESS_TO_RESOURCE - /problems/RESOURCE_DOES_NOT_EXIST - /problems/RESOURCE_NOT_READY - /problems/RESOURCE_TOO_LARGE - /problems/WRONG_METHOD - /problems/OPERATION_NOT_ALLOWED - /problems/TECHNICAL_ERROR - /problems/NOT_IMPLEMENTED - /problems/SERVICE_UNAVAILABLE example: /problems/TECHNICAL_ERROR Currency: description: The ISO currency three-letter code. Corresponds to the attribute _Ccy_ in SPS/ISO-20022. type: string minLength: 3 maxLength: 3 example: CHF Date: title: Shared date description: A date. type: string format: date example: '2018-04-13' DateTime: title: Shared date-time description: The date and time formatted as YYYY-MM-DDTHH:mm:ssZ. type: string format: date-time example: '2018-04-13T11:11:11Z' Designation: description: | This element shall always be populated with the account alias, if defined, otherwise with specific bank account name (e.g. bank saving account). This attribute is required in the Account API, while optional in SPS. Reason: Necessary for the multibanking use case. Ref: Issue#98. type: string maxLength: 140 example: Firmenkonto IbanIdentification: description: The International Bank Account Number (IBAN), associated with the account. type: string maxLength: 34 pattern: ^[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}$ example: CH5481230000001998736 Iso20022ReportReference: title: ISO20022 Report Reference description: The referenced ISO20022 report (common fields for camt.052 and camt.053). type: object required: - account - creationDateTime - id - schemaVersion properties: account: $ref: '#/components/schemas/PaymentIbanAccount' creationDateTime: $ref: '#/components/schemas/DateTime' description: Date and time when the message was created. Corresponds to the attribute _GrpHdr ⇾ CreDtTm_ in SPS/ISO-20022. id: type: string description: The unique identifier of the referenced ISO20022 report. example: '8265333' schemaVersion: type: string example: camt.053.001.01 description: The delivered schema version of the referenced ISO20022 report. pattern: ^camt\.(052|053)\.[0-9]{3}\.[0-9]{2}$ Iso20022ReportReference052: title: ISO20022 Report Reference (camt.052) description: The referenced ISO20022 report (camt.052). type: object required: - type properties: type: type: string enum: - incremental - full example: full description: | Indicates the type of ISO 20022 report being referenced. * incremental: Contains only the transactions that occurred since the last intraday statement (camt.052). * full: Contains all transactions since the last regular account statement (camt.053). dateFrom: $ref: '#/components/schemas/Date' description: The start date of the transaction query period, optional for camt.052. dateTo: $ref: '#/components/schemas/Date' description: The end date of the transaction query period, optional for camt.052. allOf: - $ref: '#/components/schemas/Iso20022ReportReference' Iso20022ReportReference053: title: ISO20022 Report Reference (camt.053) description: The referenced ISO20022 report (camt.053). type: object required: - dateFrom - dateTo properties: dateFrom: $ref: '#/components/schemas/Date' description: The start date of the transaction query period, mandatory for camt.053. dateTo: $ref: '#/components/schemas/Date' description: The end date of the transaction query period, mandatory for camt.053. allOf: - $ref: '#/components/schemas/Iso20022ReportReference' PaymentCurrencyAmount: title: Payment Currency Amount description: Specifies the entry amount according to the account currency. type: object required: - amount - currency properties: amount: $ref: '#/components/schemas/Amount' description: The entry amount, which will be reflected in the account balance. currency: $ref: '#/components/schemas/Currency' description: The ISO currency three-letter code in which the entry was posed. PaymentIbanAccount: title: Payment IBAN Account description: The IBAN account object. type: object required: - identification - type properties: identification: $ref: '#/components/schemas/IbanIdentification' description: The International Bank Account Number (IBAN), associated with the account. type: type: string description: | The allowed account identification type for the creditor account depends on the payment type. The debtor account must always be an IBAN. enum: - IBAN example: IBAN PaymentRemittanceInformation: description: Either remittanceReference or remittanceInformation must be set. Corresponds to the attribute _RmtInf ⇾ Ustrd_ in SPS/ISO-20022. type: string maxLength: 140 example: Rechnung Nr. 408 responses: standard202: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: Accepted - Valid request, requested data not available yet. The request may be attempted at a later time. content: application/json: schema: type: object standard204: headers: X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: No content - The server has successfully fulfilled the request. There is no content to return and never will be. standard400: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: | Bad Request - The format of the request was invalid. Examples: - InvalidPayload: type: /problems/INVALID_PAYLOAD title: Payload does not comply with API specification detail: Malformed JSON instance: path/to/corresponding/resource - InvalidParameter: type: /problems/INVALID_PAYLOAD title: Invalid parameter values have been detected detail: Sent data could not processed instance: path/to/corresponding/resource - MissingId: type: /problems/INVALID_PAYLOAD title: The payload was not valid detail: ID is missing instance: path/to/corresponding/resource content: application/problem+json: schema: $ref: '#/components/schemas/CommonErrorResponse' standard401: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: Unauthorized - The request has not been applied because it provides no valid authentication credentials for the target resource. content: application/problem+json: schema: $ref: '#/components/schemas/CommonErrorResponse' standard403: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: | Forbidden - A valid OAuth Token was received, but access was denied. (Depending on the security requirements, providers can return 404 instead) Examples: - InsufficientPrivileges: type: /problems/INSUFFICIENT_PRIVILEGES title: No privileges for the requested operation detail: Insufficient privileges for the requested operation instance: path/to/corresponding/resource - ExpiredToken: type: /problems/EXPIRED_TOKEN title: The OAuth Token is expired detail: The token is no longer valid instance: path/to/corresponding/resource - NoFutureDateSupported: type: /problems/MALFORMED_PAYLOAD title: Invalid parameter values have been detected detail: Data for date in the future cannot be requested instance: path/to/corresponding/resource content: application/problem+json: schema: $ref: '#/components/schemas/CommonErrorResponse' standard404: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: | Not Found - Either the endpoint does not exist or a requested resource is not yet available (e.g., account statements) Examples: - InvalidAccounts: type: /problems/INSUFFICIENT_PRIVILEGES title: Insufficient privileges to access resource detail: The provided token does not grant access to the requested account instance: path/to/corresponding/resource - InvalidToken: type: /problems/INSUFFICIENT_PRIVILEGES title: Insufficient privileges to access resource detail: The provided token is not valid instance: path/to/corresponding/resource - WrongEndpointUrl: type: /problems/TECHNICAL_ERROR title: URL not found detail: The requested endpoint does not exist instance: path/to/corresponding/resource - NoIntradayDataSupported: type: /problems/NOT_IMPLEMENTED title: Feature is not implemented detail: This interface does not support intraday data instance: path/to/corresponding/resource content: application/problem+json: schema: $ref: '#/components/schemas/CommonErrorResponse' standard405: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: | Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource. Examples: - NotSupportedOperation: type: /problems/WRONG_METHOD title: This HTTP operation is not allowed on this endpoint detail: Only GET operations are allowed instance: path/to/corresponding/resource content: application/problem+json: schema: $ref: '#/components/schemas/CommonErrorResponse' standard500: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: | Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request. Examples: - TechnicalServerError: type: /problems/TECHNICAL_ERROR title: Technical error on server side detail: Processing yielded a technical error instance: path/to/corresponding/resource - ResourceTooLarge: type: /problems/RESOURCE_TOO_LARGE title: Generated resource was too large detail: The generated resource exceeded the size limit instance: path/to/corresponding/resource content: application/problem+json: schema: $ref: '#/components/schemas/CommonErrorResponse' standard501: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: | Not Implemented - The server does not support the functionality required to fulfill the request. Examples: - EndpointNotImplemented: type: /problems/NOT_IMPLEMENTED title: Target endpoint is not implemented detail: This endpoint is not implemented instance: path/to/corresponding/resource content: application/problem+json: schema: $ref: '#/components/schemas/CommonErrorResponse' standard503: headers: Content-Language: $ref: '#/components/headers/Content-Language' X-Correlation-ID: $ref: '#/components/headers/X-Correlation-ID' description: Service Unavailable - The server is currently unable to handle the request due to a temporary overload or scheduled maintenance. content: application/problem+json: schema: $ref: '#/components/schemas/CommonErrorResponse' parameters: account_id: in: path name: accountId description: ID of the account. required: true schema: maxLength: 256 pattern: ^[A-Za-z0-9](([A-Za-z0-9._]|-){0,254}[A-Za-z0-9]){0,1}$ type: string example: accountId agent: in: header name: User-Agent description: Name and version of the of the Client software. required: true schema: type: string authorization: in: header name: Authorization description: Bearer followed by a base64 encoded OAuth access token. required: true schema: type: string client_id: in: header name: X-CorAPI-Client-ID description: 'ID of the client forwarded to the provider (SCOPE: FI).' required: true schema: type: string correlation: in: header name: X-Correlation-ID description: Unique ID (defined by the caller) which will be reflected back in the response. required: true schema: type: string cursor: in: query name: cursor description: Optional parameter for pagination. Use the ID of the last item from the previous response to retrieve the next set of results. required: false schema: type: string example: cursorIDxyz date: in: query name: date description: 'The date to query, formatted as yyyy-mm-dd. Default value: current date.' schema: $ref: '#/components/schemas/Date' date_from: in: query name: date_from description: The start date for the query. Must be earlier than or equal to the dateTo parameter. schema: $ref: '#/components/schemas/Date' date_to: in: query name: date_to description: The end date for the query. Must be later than or equal to the dateFrom parameter. schema: $ref: '#/components/schemas/Date' entry_id: in: path name: entryId description: > Unique identifier of the account transaction entry. Corresponds to AccountTransactionEntry.accountServicerReference and to the attribute _Ntry ⇾ AcctSvcrRef_ in SPS/ISO-20022. required: true schema: type: string maxLength: 35 entry_status: in: query name: entry_status description: | Specifies the status of the entries to be queried. Intraday movements can have a status of either "pending" or "booked." For completed booking days, only entries with a "booked" status will be returned. required: false schema: type: string enum: - booked - pending - both default: booked limit: in: query name: limit description: | Optional parameter for pagination, specifying the number of items to return. The actual maximum limit can be defined by the provider. required: false schema: type: integer format: int32 example: 25 minimum: 1 default: 25 psu_ip: in: header name: X-PSU-IP-Address description: 'IP address of the user initiating the operation (SCOPE: FI - optional).' required: false schema: type: string psu_user_agent: in: header name: X-PSU-User-Agent description: 'User of the client software (SCOPE: FI - optional).' required: false schema: type: string report_id: in: path name: reportId description: Unique ID of the requested ISO20022 XML camt.053 document. required: true schema: maxLength: 35 type: string target_id: in: header name: X-CorAPI-Target-ID description: 'ID of the target, e.g., a financial institution (SCOPE: FI - optional).' required: false schema: type: string headers: Content-Language: description: Response language - always en. schema: type: string X-Correlation-ID: description: Client defined ID from request to correlates HTTP requests between a client and server. schema: type: string example: f058ebd6-02f7-4d3f-942e-904344e8cde5 X-Next-Cursor: description: | An opaque string value used for pagination. Include this value in the cursor parameter of the subsequent request to fetch the next page of results. An empty string indicates that there are no more results. required: true schema: type: string nullable: true example: nextCursorIDxyz securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://example.com/oauth/authorize tokenUrl: https://example.com/oauth/token scopes: read: Grants read access write: Grants write access