The Subaio Partner API allows partners to make backend API calls to the Subaio Client API endpoints.
\The API is opened to partners using IP whitelisting, SSL-client certificates and/or VPN connections etc. to ensure that only the partners are able connect.
" contact: email: "info@subaio.com" host: partner.demo.subaio.com:9443 basePath: "/" schemes: - "https" securityDefinitions: Bearer: type: apiKey name: Authorization in: header parameters: PartnerId: name: "partnerId" in: "path" type: string required: true CorrelationId: name: X-Correlation-ID type: string in: header required: false description: "Optionally provide an ID to track requests throughout the system for debugging purposes. There are no limitations on format. If the ID is not provided as a request header, a UUID is generated. Whether provided or generated, the correlation ID of is also returned as the X-Correlation-ID response header." tags: - name: User handling - name: Transactions - name: PSD2 - name: Recurring payments - name: Crowdsourcing - name: Accounts - name: Reports - name: Budgets paths: # Tag: User handling ###################################################### /partner/{partnerId}/2.0.0/users: post: summary: "Create new Subaio user" description: "Create a new Subaio user by supplying a user key that can be shared between you and Subaio.
This ID is used when getting login tokens, linking transaction data to an onboarded user etc.
" tags: - User handling parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/CreateUserRequest" - $ref: '#/parameters/CorrelationId' consumes: - "application/json" produces: - "application/json" responses: 201: description: "User created" headers: X-Correlation-ID: type: string 409: description: "User already exists" headers: X-Correlation-ID: type: string delete: summary: "Delete Subaio user" description: "Delete a Subaio user
Data retention policy is enforced, so necessary data is kept until it expires.
" tags: - User handling parameters: - $ref: '#/parameters/PartnerId' - $ref: '#/parameters/CorrelationId' responses: 202: description: "User deleted" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/users/logins: post: summary: "Get Subaio JWT based on signed payload containing bank user ID" description: "Payload is handled on a per bank basis." tags: - User handling parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/LoginRequest" - $ref: '#/parameters/CorrelationId' consumes: - "application/json" produces: - "application/json" responses: 200: description: "Login successful - Subaio JWT returned" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/LoginResponse" 403: description: "Login invalid" headers: X-Correlation-ID: type: string 404: description: "User not found" headers: X-Correlation-ID: type: string # Tag: Transactions ###################################################### /partner/{partnerId}/2.0.0/transactions: post: summary: "New debited transactions" description: "Encrypted transaction list. The payload is encrypted using JWE specifications (RFC7516)." tags: - Transactions parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/TransactionsRequest" - $ref: '#/parameters/CorrelationId' consumes: - "application/json" produces: - "application/json" responses: 201: description: "Created. All transactions in the request were successfully received." headers: X-Correlation-ID: type: string 400: description: "Bad Request. The contents could not be processed. Retrying the same request without modifications will not help. All transactions in the request are considered unreceived. The response body may contain additional information on what went wrong with the request handling. If the request contained multiple transactions, and the errorCode is TX_DATA_ERROR, the sender MAY retry sending the batched transactions in single messages." headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/TransactionsErrorResponse" get: summary: "Fetch debited transactions on the user." description: "Returns a list of debited transactions on the user." tags: - Transactions parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/TransactionsResponse" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Returned a list of debited transactions on the user." headers: X-Correlation-ID: type: string security: - Bearer: [] # Tag: PSD2 ###################################################### /partner/{partnerId}/2.0.0/psd2/initiate: post: summary: "Initiate PSD2 login flow." description: | Returns a URL to a PSD2 login UI that must be followed to give access to bank data. Since some browsers block third-party cookies by default, and some PSD2 providers are dependent on cookies to work, it is necessary to either open a new browser window, or redirect the entire page. To help open the redirect URL in a new window (or tab on mobile), the tiny [@subaio/psd2login-web](https://developer.subaio.com/docs/psd2login/web/0.2.0/) helper library can be used. No `redirectUrl` should be provided in the body of this request. If `redirectUrl` is provided, it will redirect and simply close the window afterwards. If opening a new window is not desireable or possible, the page should instead pass a `redirectUrl` in the body of the request and redirect to the returned `url`. When the process is finished, the page will be redirected to the URL provided to in the body, with an added query-parameter, `psd2Status`. It can take the following values: * `SUCCESS`: The user successfully added one or more banks, and they are currently being processed. * `ABORTED`: The user chose to abort the process halfway through. * `UNKNOWN`: An unexpected error caused the login to fail. tags: - PSD2 parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/Psd2InitiateRequest" - $ref: '#/parameters/CorrelationId' responses: 200: description: "Login flow has been initiated." headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/Psd2InitiateResponse" security: - Bearer: [] # Tag: Recurring payments ###################################################### /partner/{partnerId}/2.0.0/services: get: summary: "Get all recurring payment for a user" description: "" tags: - Recurring payments parameters: - $ref: '#/parameters/PartnerId' - name: "visibility" in: query required: false type: string default: VISIBLE description: "Shows services with visibility." enum: - VISIBLE - HIDDEN - $ref: '#/parameters/CorrelationId' responses: 200: description: "List of recurring payments" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/ServiceResponse" 202: description: "The resources is not ready yet, please try again later. The Retry-After header will state when it would make sense to try again. The Location header is a self reference, it is present because it is required for status code 202." headers: X-Correlation-ID: type: string Retry-After: description: "A suggested time in seconds to wait before retrying." type: integer Location: description: "Mandatory when returning 202, but is just a url self reference." type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/services/{serviceId}: get: summary: "Get specific recurring payment for a user." description: "" tags: - Recurring payments parameters: - $ref: '#/parameters/PartnerId' - name: "serviceId" in: "path" required: true type: string - $ref: '#/parameters/CorrelationId' responses: 200: description: "The recurring payments for the user" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/Service" security: - Bearer: [] /partner/{partnerId}/2.0.0/services/{serviceId}/hidden: put: summary: "Update the service hidden status" description: "" tags: - Recurring payments parameters: - $ref: '#/parameters/PartnerId' - name: "serviceId" in: "path" required: true type: string - name: "body" in: "body" required: true schema: $ref: "#/definitions/ServiceUpdateHiddenRequest" - $ref: '#/parameters/CorrelationId' consumes: - "application/json" responses: 200: description: "Updated the service hidden status." headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/upcoming-payments: get: summary: "Get upcoming recurring payments" description: "Return the next expected payment for each active recurring payment. Sporadic payments are not included." tags: - Recurring payments parameters: - $ref: '#/parameters/PartnerId' - $ref: '#/parameters/CorrelationId' responses: 200: description: "List of upcoming payments" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/UpcomingPaymentsResponse" security: - Bearer: [] # Tag: Crowdsourcing ###################################################### /partner/{partnerId}/2.0.0/crowdsourcing: post: summary: "Submit a missing subscription." description: "Submit a missing subscription by giving a transaction id and a payment frequency.
" tags: - Crowdsourcing parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/CrowdsourcingRequest" - $ref: '#/parameters/CorrelationId' responses: 201: description: "The missing subscription has been submitted." headers: X-Correlation-ID: type: string 503: description: "This feature has been disabled." headers: X-Correlation-ID: type: string security: - Bearer: [] # Tag: Accounts ###################################################### /partner/{partnerId}/2.0.0/accounts: put: summary: "Update user account access" description: Update the accounts a user has access to - only able to remove accounts, as access to new accounts has to be introduced through the transactions endpoint tags: - Accounts parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/AccountsRequest" - $ref: '#/parameters/CorrelationId' consumes: - "application/json" produces: - "application/json" responses: 200: description: "User account upgraded" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/accounts-balances: put: summary: "Update account balance and name for customer accounts. Any existing account balance and name (if provided) will be overwritten. If the account does not exist it will be created." tags: - Accounts parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/AccountsBalancesRequest" - $ref: '#/parameters/CorrelationId' consumes: - "application/json" responses: 200: description: "All account details have been updated or created." headers: X-Correlation-ID: type: string security: - Bearer: [] # Tag: Reports ###################################################### /partner/{partnerId}/2.0.0/reports: post: summary: "Request user report" description: "Request a user report based on the transactions currently present" tags: - Reports parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/ReportRequest" - $ref: '#/parameters/CorrelationId' consumes: - "application/json" produces: - "application/json" responses: 200: description: "User report requested for processing" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/ReportResponse" security: - Bearer: [] # Tag: Budgets ###################################################### /partner/{partnerId}/2.0.0/budgets: post: summary: "Create budget for user" description: "Request a new budget for the user" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "body" in: "body" required: false schema: $ref: "#/definitions/BudgetRequest" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "User budget" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetCreateResponse" security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}: get: summary: "Get user budget" description: "Get the user budget with the provided budget id. The `transactions` element will always be empty, if you need transactions use the /details endpoint." tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "User budget" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetResponse" 202: description: "Budget is uninitialized, due to payment data not being ready" headers: X-Correlation-ID: type: string 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/coapplicants: post: summary: "Approve co-applicant in the budget" description: "Confirms that both users agree that they are co-applicants." tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "body" in: "body" required: true schema: $ref: "#/definitions/BudgetCoapplicantRequest" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Applicant added to budget" headers: X-Correlation-ID: type: string 400: description: "Co-applicant type is SEPARATE_FINANCES, but no budget id provided" headers: X-Correlation-ID: type: string 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/comment: post: summary: "Add comment to budget" description: "Adds a comment to the budget" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "body" in: "body" required: true schema: $ref: "#/definitions/BudgetCommentRequest" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Comment added to budget by the user" headers: X-Correlation-ID: type: string 400: description: "Payload not valid" headers: X-Correlation-ID: type: string 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/completions: post: summary: "Complete budget" description: "Mark the budget as completed" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "body" in: "body" required: true schema: $ref: "#/definitions/BudgetCompletionsRequest" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Budget marked as completed" headers: X-Correlation-ID: type: string 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/details: get: summary: "Get user budget with details" description: "Get the user budget with the provided budget id. The budget contains transaction details." tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "User budget" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetDetailsResponse" 202: description: "Budget is uninitialized, due to payment data not being ready" headers: X-Correlation-ID: type: string 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/user-data: get: summary: "Get user data for budget" description: "Get the user data for the budget with the provided budget id" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "User data for budget" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetUserDataResponse" 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] post: summary: "Create user data for budget" description: "Create the user data for the budget with the provided budget id" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "body" in: "body" required: true schema: $ref: "#/definitions/BudgetUserDataRequest" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "User data for budget" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetResponse" 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/categories/{categoryId}/adjustments: post: summary: "Adjust amount for a category" description: "Send amount changes for a category" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "categoryId" in: "path" required: true type: string - name: "body" in: "body" required: true schema: $ref: "#/definitions/BudgetAdjustCategoryRequest" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Category amount adjusted and updated budget returned" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetResponse" 400: description: "Payload not valid, e.g. amount is less than 0" headers: X-Correlation-ID: type: string 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] delete: summary: "Remove user adjusted amount for a category" description: "Remove the user adjusted amount for a category" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "categoryId" in: "path" required: true type: string - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Action for user adjusted amount for category removed and updated budget returned" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetResponse" 404: description: "No budget or action with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/questions/next: get: summary: "Get next action" description: "Get next unresolved action for user budget" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Budget action" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetActionResponse" 404: description: "No budget with provided id found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/questions/{actionId}: post: summary: "Recategorize or add category" description: "Recategorize action or add new missing category" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "actionId" in: "path" required: true type: string format: uuid - name: "body" in: "body" required: true schema: $ref: "#/definitions/BudgetActionRequest" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Budget action updated" headers: X-Correlation-ID: type: string 404: description: "Budget or budget action not found" headers: X-Correlation-ID: type: string security: - Bearer: [] delete: summary: "Undo action" description: "Undo the effects of an action" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "actionId" in: "path" required: true type: string format: uuid - name: "body" in: "body" required: true schema: $ref: "#/definitions/BudgetSkipRequest" - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Budget action deleted" headers: X-Correlation-ID: type: string 404: description: "Budget or budget action not found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/questions/{actionId}/skips: post: summary: "Skip action" description: "Skip action" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "actionId" in: "path" required: true type: string format: uuid - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 201: description: "Action skipped" headers: X-Correlation-ID: type: string 404: description: "Budget or budget action not found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/expenses/{expenseId}: get: summary: "Get expense" description: "Get details about an expense" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - name: "expenseId" in: "path" required: true type: string format: uuid - $ref: '#/parameters/CorrelationId' produces: - "application/json" responses: 200: description: "Expense" headers: X-Correlation-ID: type: string schema: $ref: "#/definitions/BudgetExpenseResponse" 404: description: "Budget or expense not found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/budgets/{budgetId}/report: post: summary: "Get creditworthiness report" tags: - Budgets parameters: - $ref: '#/parameters/PartnerId' - name: "budgetId" in: "path" required: true type: string format: uuid - $ref: '#/parameters/CorrelationId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/BudgetReport" consumes: - application/json produces: - application/pdf - application/octet-stream responses: 200: description: "Report" headers: X-Correlation-ID: type: string schema: type: file 404: description: "Budget not found" headers: X-Correlation-ID: type: string security: - Bearer: [] /partner/{partnerId}/2.0.0/alerts/seen: put: summary: "Mark multiple alerts as seen." description: "Marks multiple alerts as seen. After an alert has been marked as seen it will not show up as an alert anymore.
" tags: - Alerts parameters: - $ref: '#/parameters/PartnerId' - $ref: '#/parameters/CorrelationId' - name: "body" in: "body" required: true schema: $ref: "#/definitions/AlertSeenRequest" responses: 200: description: "The alerts have been marked as seen." headers: X-Correlation-ID: type: string security: - Bearer: [] definitions: Psd2InitiateRequest: type: object properties: redirectUrl: type: string description: "URL to redirect to when PSD2 login is complete." Psd2InitiateResponse: type: object properties: url: type: string format: uri description: "URL to redirect to when PSD2 login is complete." loginId: type: string format: uuid description: "Id associated with current login." CrowdsourcingRequest: type: object required: - id properties: id: type: string description: "Transaction id." paymentFrequency: type: string enum: - DAILY - WEEKLY - BIWEEKLY - MONTHLY - BIMONTHLY - QUARTERLY - HALFYEARLY - YEARLY - UNKNOWN description: "Payment frequency." example: "MONTHLY" # Transactions RawTransaction: type: object description: "A single transaction to receive partner transaction notifications." required: - uid - type - tx properties: uid: type: "string" description: "Partner user id for the owner of this transaction. A generated unique id assigned for a particular customer and partner combination at registration time." example: "28d2044d-a550-465f-8404-f750ca3595ce" type: type: "string" enum: - TX - IMPORT_COMPLETED description: "Type of the transaction event. TX is a new transaction for the user. IMPORT_COMPLETED is sent after the last transaction import for a newly onboarded user. " card: type: "object" description: "The card details." required: - id - pan4 properties: id: type: "string" description: "Partner card id, uniquely identifying the card this transaction belongs to among all cards and partners. The ID for the card is assigned during registration to the partner." example: "caa652a3-3d16-4b97-b07a-97a6828de8a4" pan4: type: "string" description: "Last four digits of the card pan. Used for displaying the card to the user." example: "0875" cardType: type: "string" description: "The card type (CREDIT, DEBIT)" example: "DEBIT" paymentNetwork: type: "string" description: "Payment network for the card, if known. Example values are MC, VISA, VISABAX, VISADK, DANKORT or BAX" account: type: "object" description: "The account details." required: - id - name - iban properties: id: type: "string" description: "Partner account id, uniquely identifying the account this transaction belongs to among all accounts and partners. The ID for the account is assigned during registration to the partner." example: "aaa652a3-3d16-4b97-b07a-97a6828de8a4" name: type: "string" description: "The user visible name of the account or the account number. Used for displaying the account to the user." example: "595900001234" iban: type: "string" description: "The user visible name of the account or the account number. Used for displaying the account to the user." example: "DK12595900001234" tx: type: "object" description: "The detail fields of a single transaction. Required if type is TX, not present for IMPORT_COMPLETED marker transactions." required: - txid - txTime - type - amount - currency - description properties: txid: type: "string" description: "Unique transaction id identifying a single transaction globally. Required if type is TX." example: "9456cc69-e50e-4e9f-bc0b-bd44b87734a3" description: type: "string" description: "Raw transaction description" example: "Netflix 20.00 USD" txTime: description: "Timestamp of the transaction in ISO 8601. Only the date-part of the timestamp is reliable, for some transaction sources the time-part is always 00:00. In other cases, the time may be the processing time at the bank, not necessarily the time of actual purchase. The timestamp may come with a timezone, or without any timezone info." example: "2018-11-16T12:45:53+02:00" type: type: "string" description: "Raw transaction type. Example values are CARD_PURCHASE, CASH_WITHDRAWAL, ACCOUNT_TRANSFER" amount: type: "number" format: "double" description: "Purchase amount in cardholder currency. Purchases (money is taken from card/account) have a negative amount, and refunds have a positive amount." example: -158.99 currency: $ref: "#/definitions/Currency" originalAmount: type: "number" format: "double" description: "Original amount if purchase done in some other currency. May contain more than two significant decimal digits if the originating currency supports them." example: -187792.687 originalCurrency: $ref: "#/definitions/Currency" merchant: type: "object" description: "Details of the merchant associated with the transaction. All of the fields are optional, most transactions will have at least the name populated, but even that is not guaranteed for all transactions." required: - name properties: cid: type: "string" description: "Card acceptor id, as provided by the payment network." example: "1905481-8" name: type: "string" description: "Merchant name" example: "Zlatnicka Täityö" address: type: "string" description: "Address of merchant" city: type: "string" description: "City of merchant" example: "OSLO" postCode: type: "string" description: "Postal code of merchant" country: type: "string" description: "Country of merchant" example: "GB" mcc: type: "integer" description: "Merchant category code" example: 6011 JweParams: type: "object" description: "Supported JWE encryption header parameters. See the JWE speficiation for details on formatting the JWE token, and where to place each header value." required: - alg - enc - kid properties: alg: type: "string" enum: - RSA-OAEP description: "The supported content encryption key protection algorithm is RSAES OAEP using default parameters." enc: type: "string" enum: - A256GCM description: "The supported ciphertext encryption algorithm is AES GCM using 256-bit content encryption key (CEK)." kid: type: "string" description: "The key identifier for the public key used to encrypt the CEK." example: "partner1-26-05-2018" zip: type: "string" enum: - DEF description: "The compression used on the plaintext before encryption. If this header value is not present, the contents are not compressed. DEF referes to DEFLATE algorithm defined in RFC1951." ServicePayment: type: object required: - id - sourceTransactionId - amount - currency - date properties: id: type: "integer" format: int64 sourceTransactionId: type: string amount: type: number format: double example: 1.23 description: "The amount of the payment converted to currency." currency: $ref: "#/definitions/Currency" originalAmount: type: number format: double example: 1.23 description: "The amount of the payment in the original currency." originalCurrency: $ref: "#/definitions/Currency" date: type: string description: "Payment date" format: date example: "2020-01-15" # Upcoming payments UpcomingPayment: type: object required: - serviceId - expectedPaymentDate - expectedPaymentCost - currency - expectedOriginalPaymentCost - product properties: serviceId: type: string format: uuid description: Unique ID for recurring payment group expectedPaymentDate: type: string format: date expectedPaymentCost: type: number format: double example: 19.75 currency: $ref: "#/definitions/Currency" expectedOriginalPaymentCost: type: number format: double example: 2.95 originalCurrency: $ref: "#/definitions/Currency" accountId: type: "string" description: "Account Id from the service which the upcoming payment belongs to. This field will be null if no account info has been provided by the bank." cardId: type: "string" description: "Card Id from the service which the upcoming payment belongs to. This field will be null if no card info has been provided by the bank." product: $ref: "#/definitions/Product" additionalInfo: type: object required: - type description: "Implementation specific extra details - usually this is empty." additionalProperties: type: string Product: type: object required: - title - imageUrl - type - isGateway - isUnknownStoreSubscription properties: title: type: string example: "Audible" imageUrl: type: string format: uri example: "https://cdn.demo.subaio.com/products/DK/b025dc90-ea55-11e7-9343-0242ac130002/e8266645cb3aff1d8b36329281a3ffa5.png" type: type: "string" enum: - SUBSCRIPTION - OTHER_RECURRING description: | Product type can be used to group recurring payments into two lists. `SUBSCRIPTION` are non-essential recurring expenses such as streaming services, fitness centers, and `OTHER_RECURRING` are fixed expenses such as insurance, rent, loans, utility bills etc. isGateway: type: boolean description: "Used to explain how this service might look like something they don't know what is, but 'sells' another product they pay for through them. An example could be a publisher that sells magazine subscriptions. You have a subscription on a specific magazine but the subscription is with the publisher." isUnknownStoreSubscription: type: boolean description: "The service has a fake product to help visualize unknown service. This is generally only applicable to the Apple Store" BudgetProduct: type: object required: - title - imageUrl properties: title: type: string example: "Audible" imageUrl: type: string format: uri example: "https://cdn.demo.subaio.com/products/DK/b025dc90-ea55-11e7-9343-0242ac130002/e8266645cb3aff1d8b36329281a3ffa5.png" # Notifications Notification: type: object required: - type - country - userId - suggestedLocale - payload - texts description: "A single notification send from subaio." properties: type: type: "string" description: "Describes the type of notification being send." enum: - CANCELLATION_COMPLETED - CANCELLATION_ABORTED - CANCELLATION_MOREINFOREQUIRED - NEW_SUBSCRIPTION - NEW_PAYMENT_CANCELLED_SUBSCRIPTION - NEW_PAYMENT - TEST_NOTIFICATION - PAYMENT_CHANGED - USER_UPDATE_REQUIRED country: type: string description: "Country for receiving user using ISO 3166-1 alpha-2" pattern: "^[A-Z]{2}$" userId: type: string suggestedLocale: type: "string" description: "The suggest local for displaying notification text." example: "da-dk" payload: type: array minItems: 0 items: $ref: "#/definitions/NotificationPayload" texts: type: object description: "A map of locals to translations. The properties are named based on the available locals" properties: en: $ref: "#/definitions/NotificationTranslation" additionalProperties: $ref: "#/definitions/NotificationTranslation" NotificationPayload: type: object required: - name - params properties: name: type: string params: type: object required: - type additionalProperties: type: string NotificationTranslation: type: object required: - title - body description: "A notification message in a specific locale." properties: title: type: "string" description: "The notification title/header to be displayed to the user." example: "" body: type: "string" description: "We have had to abort the cancellation of your subscription with Netflix" Service: type: object required: - id - amount - currency - paymentFrequency - accountId - cardId - product - status - userActionsRequired - payments - yearlyCost - notifications - visibility - totalAmountLastTwelveMonths - nextExpectedTransactionDate - visibilityOption - amountToDisplay properties: id: type: string format: uuid amount: type: number format: double example: 1.23 currency: $ref: "#/definitions/Currency" paymentFrequency: $ref: "#/definitions/PaymentFrequency" accountId: type: "string" description: "Account Id for the payments recognized for the service. This field will be null if no account info has been provided by the bank." cardId: type: "string" description: "Card Id for the payments recognized for the service. This field will be null if no card info has been provided by the bank." product: $ref: "#/definitions/Product" status: type: string enum: - ACTIVE - INACTIVE - UNDER_CANCELLATION - CANCELLED userActionsRequired: type: array minItems: 0 items: $ref: "#/definitions/UserActionRequiredType" payments: type: array minItems: 1 items: $ref: "#/definitions/ServicePayment" yearlyCost: type: number format: double example: 1.23 totalAmountLastTwelveMonths: type: number format: double description: "The total amount paid for service in the last twelve months." example: 1200.00 notifications: type: array minItems: 0 description: "Set of notifications for service." items: $ref: "#/definitions/NotificationType" example: [NEW_PAYMENT, NEW_SUBSCRIPTION] visibility: type: string description: "The visibility state of the service. Relates to the /partner/{partnerId}/2.0.0/services endpoint visibility query parameter. The value can be changed on the /partner/{partnerId}/2.0.0/services/{serviceId}/hidden endpoint. \n\n If UNDECIDED, it may be a subscription, but it could also be a single purchase of a subscription-like amount from the same company (for instance, a fitness center selling both monthly subscriptions and towels for the same amount). The subscription should be visible, and the user should be asked to confirm whether or not it’s a false positive. These services will be visible on /partner/{partnerId}/2.0.0/services endpoint." enum: - VISIBLE - HIDDEN - UNDECIDED example: "HIDDEN" nextExpectedTransactionDate: type: string description: "The next expected transaction date for a service." example: "2022-09-01" store: $ref: "#/definitions/Store" visibilityOption: $ref: "#/definitions/VisibilityOptionType" cancellation: $ref: "#/definitions/Cancellation" amountToDisplay: $ref: "#/definitions/AmountToDisplayType" cancellationOption: $ref: "#/definitions/CancellationOptionType" iban: type: string description: "IBAN for the latest payment of the service. Null, if no IBAN has been provided by the bank." example: "DK5000403333333333" Cancellation: description: "There are several hardcoded responses support can attach to a cancellation to inform the user. There is also the possibility of a free text response from support but this is used with confirmation from the customer." type: object required: - directDebit - equipmentBack - moneyBack properties: confirmationContent: type: string description: "Confirmation content to the user from support. This is usually a message from the subscription company that we believe is important for the user to know." directDebit: type: boolean description: "If the service is paid with direct debit. If that is the case, there is a chance that the user has already received a bill in the applicable system of their resident country and we recommend they cancel that bill when the subscription ends unless instructed otherwise." equipmentBack: type: boolean description: "If the user should give equipment back." freeTextMessage: type: string description: "Free text message from support to the user." moneyBack: type: boolean description: "If the user gets money back." endDate: type: string description: "The reported last payment date from the service holder or the date that the user reported themselves during self-cancellation" format: date example: "2020-01-15" abortReason: $ref: "#/definitions/CancellationAbortReason" UserActionRequiredType: type: string enum: - CANCELLATION_NEED_MORE_INFO # Budgets Budget: type: object required: - id - status - createdTime - totalMonthlyAmount - totalMonthlyAmountUserProvided - totalMonthlyIncome - totalMonthlyIncomeUserProvided - averageExpensesLastThreeMonths - averageExpensesLastTwelveMonths - averageIncomeLastThreeMonths - averageIncomeLastTwelveMonths - amountCategorized - amountCategorizedUserProvided - disposableIncome - disposableIncomeUserProvided - categorizationTarget - categories - uncategorized - income - alerts - accounts - userData - riskIndicators - comment properties: id: type: string format: uuid example: "c8f2df69-1162-435c-9486-4e27506cbf9e" status: type: string enum: - DRAFT - READY - ACCEPTED - DENIED createdTime: type: string description: "Budget creation date, format yyyy-MM-dd'T'HH:mm:ss" format: date-time example: "2022-05-16T11:28:07" totalMonthlyAmount: type: number format: double example: 9500 totalMonthlyAmountUserProvided: type: number description: "Calculated expenses if user provided one or more values, `null` if no user provided value exist" format: double example: 9000 totalMonthlyIncome: type: number format: double example: 25000 totalMonthlyIncomeUserProvided: type: number description: "Calculated income if user provided one or more values, `null` if no user provided value exist" format: double example: 24000 averageExpensesLastThreeMonths: type: number format: double example: 1200 averageExpensesLastTwelveMonths: type: number format: double example: 1150 averageIncomeLastThreeMonths: type: number format: double example: 25000 averageIncomeLastTwelveMonths: type: number format: double example: 24500 amountCategorized: type: number format: double example: 6500 amountCategorizedUserProvided: type: number format: double description: "Categorized expenses if user provided one or more values, `null` if no user provided value exist" example: 6400 disposableIncome: type: number format: double description: "Categorized expenses subtracted from income, `null` if income is not enabled" example: 6400 disposableIncomeUserProvided: type: number format: double description: "Categorized expenses subtracted from income, `null` if income is not enabled or if no user provided value exist" example: 6400 categorizationTarget: type: number format: double example: 8000 categories: type: array minItems: 0 items: $ref: "#/definitions/Category" uncategorized: type: array minItems: 0 items: $ref: "#/definitions/Expense" income: type: array minItems: 0 description: "`null` if income is not enabled" items: $ref: "#/definitions/BudgetIncome" alerts: type: array minItems: 0 items: $ref: "#/definitions/BudgetAlert" accounts: type: array minItems: 0 items: $ref: "#/definitions/BudgetAccounts" userData: $ref: "#/definitions/BudgetUserData" riskIndicators: type: array description: "List of all risk indicators, `null` if risk indicators are not enabled" items: $ref: "#/definitions/BudgetRiskIndicators" comment: type: string example: "This is a user provided comment" BudgetDetails: type: object required: - id - status - totalMonthlyAmount - totalMonthlyAmountUserProvided - totalMonthlyIncome - totalMonthlyIncomeUserProvided - averageExpensesLastThreeMonths - averageExpensesLastTwelveMonths - averageIncomeLastThreeMonths - averageIncomeLastTwelveMonths - amountCategorized - amountCategorizedUserProvided - disposableIncome - disposableIncomeUserProvided - categorizationTarget - categories - uncategorized - income - nonrecurringTransactions - alerts - accounts - userData - riskIndicators - comment - nonrecurringSpending - nonrecurringIncome - nonrecurringExpenses properties: id: type: string format: uuid example: "c8f2df69-1162-435c-9486-4e27506cbf9e" status: type: string enum: - DRAFT - READY - ACCEPTED - DENIED totalMonthlyAmount: type: number format: double example: 9500 totalMonthlyAmountUserProvided: type: number description: "Calculated expenses if user provided one or more values, `null` if no user provided value exist" format: double example: 9000 totalMonthlyIncome: type: number format: double example: 25000 totalMonthlyIncomeUserProvided: type: number description: "Calculated income if user provided one or more values, `null` if no user provided value exist" format: double example: 24000 averageExpensesLastThreeMonths: type: number format: double example: 1200 averageExpensesLastTwelveMonths: type: number format: double example: 1150 averageIncomeLastThreeMonths: type: number format: double example: 25000 averageIncomeLastTwelveMonths: type: number format: double example: 24500 amountCategorized: type: number format: double example: 6500 amountCategorizedUserProvided: type: number format: double description: "Calculated value if user provided one or more values, null if no user provided value exist" example: 6400 disposableIncome: type: number format: double description: "Categorized expenses subtracted from income, `null` if income is not enabled" example: 6400 disposableIncomeUserProvided: type: number format: double description: "Categorized expenses subtracted from income, `null` if income is not enabled or if no user provided value exist" example: 6400 categorizationTarget: type: number format: double example: 8000 categories: type: array minItems: 0 items: $ref: "#/definitions/Category" uncategorized: type: array minItems: 0 items: $ref: "#/definitions/Expense" nonrecurringTransactions: type: array minItems: 0 items: $ref: "#/definitions/Transaction" income: type: array minItems: 0 description: "`null` if income is not enabled" items: $ref: "#/definitions/BudgetIncome" alerts: type: array minItems: 0 items: $ref: "#/definitions/BudgetAlert" accounts: type: array minItems: 0 items: $ref: "#/definitions/BudgetAccounts" userData: $ref: "#/definitions/BudgetUserData" riskIndicators: type: array description: "List of all risk indicators, `null` if risk indicators are not enabled" items: $ref: "#/definitions/BudgetRiskIndicators" comment: type: string example: "This is a user provided comment" nonrecurringSpending: type: object $ref: "#/definitions/BudgetSpending" nonrecurringIncome: type: object $ref: "#/definitions/BudgetSpending" nonrecurringExpenses: type: object $ref: "#/definitions/BudgetSpending" BudgetRiskIndicators: type: object required: - description - isMarked - title - type properties: description: type: string description: "Description of the risk indicator" example: "For this applicant payments to debt collection has been found. In this case these are solely debt collection and not consumer loans." isMarked: type: boolean description: "`true` if the risk indicator is applicable, `false` otherwise" title: type: string example: "Possible payments to debt collection" type: type: string enum: - EXCESSIVE_DISPOSABLE_INCOME - DEBT_COLLECTION example: "DEBT_COLLECTION" BudgetUserData: type: object required: - personal - residence - employment - education - transport - expenses properties: personal: type: object required: - children - hasChildren - maritalStatus - dateOfBirth description: "Person data" properties: children: type: array minItems: 0 description: "Used to define more information about the children" items: properties: age: type: integer example: 30 hasChildren: type: boolean description: "Does the user have any children" example: true maritalStatus: type: string enum: - SINGLE - MARRIED - COHABITANT - DIVORCED - WIDOWED - SEPARATED example: MARRIED dateOfBirth: type: string format: date example: "1990-10-21" residence: type: object description: "Residential information" required: - ownership - type - occupancyDate - hasVacationHome properties: ownership: type: string enum: - HOMEOWNER - COOPERATIVE - RENT - PARENTS - OTHER example: HOMEOWNER type: type: string enum: - HOUSE - APARTMENT - ROOM example: HOUSE occupancyDate: type: string format: date description: "Date for legal possession of home" example: "2019-06-15" hasVacationHome: type: boolean description: "Does the user own a vacation home" example: true employment: type: object description: "Employment information" required: - status - type - date - unemploymentFund - unemploymentInsuranceMonths properties: status: type: string enum: - EMPLOYED - UNEMPLOYED - RETIRED - STUDENT - APPRENTICE example: EMPLOYED type: type: string enum: - SALARIED - PART_TIME - HOURLY_WAGE - SELF_EMPLOYED example: SALARIED date: type: string description: "Employment date" format: date example: "2020-01-15" unemploymentFund: type: boolean description: "Does the user have an unemployment fund" example: true unemploymentInsuranceMonths: type: integer description: "How many months does the user have back on the unemployment fund" example: 12 education: type: object description: "Education information" required: - type properties: type: type: string enum: - ELEMENTARY - SECONDARY - VOCATIONAL - HIGHER_SHORT - HIGHER_MEDIUM - HIGHER_LONG - BACHELOR - PHD example: HIGHER_LONG transport: type: object description: "Transportation information" required: - vehicles - hasVehile properties: vehicles: type: array minItems: 0 items: properties: ownership: type: string description: "Ownership of vehicle" enum: - OWNED - LEASED - COMPANY example: OWNED hasVehicle: type: boolean description: "Does the user have access to a vehicle" expenses: type: object description: "Expense information" required: - share properties: share: type: integer description: "Percentage of expenses owned by the user" minimum: 0 maximum: 100 example: 50 Category: type: object required: - id - name - totalMonthlyAmount - totalMonthlyAmountUserProvided - averageLastThreeMonths - averageLastTwelveMonths properties: id: type: string example: "house_rent" name: type: string example: "House" totalMonthlyAmount: type: number format: double example: 1234.56 totalMonthlyAmountUserProvided: type: number description: "Calculated expenses if user provided one or more values, `null` if no user provided value exist" format: double example: 1250.00 averageLastThreeMonths: type: number format: double example: 1234.56 averageLastTwelveMonths: type: number format: double example: 1234.56 expenses: type: array minItems: 0 items: $ref: "#/definitions/Expense" categories: type: array minItems: 0 items: $ref: "#/definitions/Category" notes: type: array minItems: 0 items: $ref: "#/definitions/CategoryNote" CategoryNote: type: object required: - type - message properties: type: type: string description: "Type of category note" enum: - INCLUDES_OTHERS - INCLUDED_IN_OTHERS - EXPECTED_EMPTY - EXPECTED_NONEMPTY message: type: string description: "Note message" categories: type: array description: "Only present if type = 'INCLUDES_OTHERS' or type = 'INCLUDED_IN_OTHERS'." minItems: 1 items: type: string BudgetAlert: type: object properties: type: type: string description: "Type of alert" enum: - CATEGORIZATION_TARGET_NOT_MET - MISSING_EXPENSES - UNEXPECTED_EXPENSES - GROUPED_CATEGORIES - MISSING_ACCOUNTS - REFERENCE_MISMATCH - USER_PROVIDED_EXPENSES severity: type: string description: "Severity level of the alert" enum: - LOW - MEDIUM - HIGH message: type: string description: "Alert message" BudgetAccounts: type: object properties: providerId: type: string description: "The provider id" name: type: string description: "Name of the account" iban: type: string description: "IBAN for the account" bban: type: string description: "BBAN for the account" selectedStatus: type: string description: "Selected status" enum: - SELECTED - DESELECTED - UNDECIDED Expense: type: object required: - id - source - currency - title - paymentFrequency - paymentCost - paymentCostMonthly - averageLastThreeMonths - averageLastTwelveMonths - type - imageUrl - service - categories - transactions properties: id: type: string format: uuid example: "d0e2c719-f9d8-4022-86a6-37e949870f45" source: $ref: "#/definitions/BudgetTransactionalSource" currency: $ref: "#/definitions/Currency" title: type: string example: "Himmerland Boligforening" paymentFrequency: $ref: "#/definitions/PaymentFrequency" paymentCost: type: number format: double example: 12.34 paymentCostMonthly: type: number format: double example: 12.34 averageLastThreeMonths: type: number format: double example: 12.34 averageLastTwelveMonths: type: number format: double example: 12.34 type: $ref: "#/definitions/BudgetTransactionalType" imageUrl: type: string format: uri example: "https://cdn.demo.subaio.com/products/DK/b025dc90-ea55-11e7-9343-0242ac130002/e8266645cb3aff1d8b36329281a3ffa5.png" service: type: object $ref: "#/definitions/BudgetService" categories: type: array minItems: 0 items: type: string description: "Id for the category" example: "house_rent" transactions: type: array minItems: 1 items: $ref: "#/definitions/Transaction" BudgetIncome: type: object required: - id - name - totalMonthlyAmount - totalMonthlyAmountUserProvided - averageLastThreeMonths - averageLastTwelveMonths - categories - income - notes properties: id: type: string example: "other_income" name: type: string example: "Other income" totalMonthlyAmount: type: number format: double example: 25000 totalMonthlyAmountUserProvided: type: number description: "Calculated expenses if user provided one or more values, `null` if no user provided value exist" format: double example: 24000 averageLastThreeMonths: type: number format: double example: 25000 averageLastTwelveMonths: type: number format: double example: 24500 categories: type: array items: $ref: "#/definitions/BudgetIncome" income: type: array items: $ref: "#/definitions/Income" notes: type: array items: $ref: "#/definitions/CategoryNote" Income: type: object required: - id - title - amount - monthlyAmount - averageLastThreeMonths - averageLastTwelveMonths - frequency - currency - imageUrl - source - type - service - categories - transactions properties: id: type: string format: uuid example: "d0e2c719-f9d8-4022-86a6-37e949870f45" source: $ref: "#/definitions/BudgetTransactionalSource" currency: $ref: "#/definitions/Currency" title: type: string example: "Salary" frequency: $ref: "#/definitions/PaymentFrequency" amount: type: number format: double example: 1000.00 monthlyAmount: type: number format: double example: 1000.00 averageLastThreeMonths: type: number format: double example: 25000 averageLastTwelveMonths: type: number format: double example: 24500 imageUrl: type: string format: uri example: "https://cdn.demo.subaio.com/products/DK/b025dc90-ea55-11e7-9343-0242ac130002/e8266645cb3aff1d8b36329281a3ffa5.png" type: $ref: "#/definitions/BudgetTransactionalType" service: type: object $ref: "#/definitions/BudgetService" categories: type: array minItems: 0 items: type: string description: "Id of the category" example: "house_rent" transactions: type: array minItems: 1 items: $ref: "#/definitions/Transaction" BudgetTransactionalSource: type: string enum: - ENGINE - ACTION - DERIVED_FROM_TRANSACTIONS BudgetTransactionalType: type: string enum: - SERVICE - TRANSACTION - RAW - DERIVE - DERIVED_FROM_TRANSACTIONS - USER_PROVIDED BudgetService: type: object required: - id - paymentCost - currency - paymentFrequency - totalPastYear - product properties: id: type: string format: uuid example: "d99c24e6-32e3-4975-baf3-cb70425242f0" paymentCost: type: number format: double example: 123.45 currency: $ref: "#/definitions/Currency" paymentFrequency: $ref: "#/definitions/PaymentFrequency" totalPastYear: type: number format: double example: 1234.56 product: $ref: "#/definitions/BudgetProduct" # Requests CreateUserRequest: type: object required: - bankUserId - brand - locale properties: bankUserId: type: string description: "Key or ID that links the user in both the Subaio systems and the partner systems. Do not use a sensitive key such as SSN." brand: type: string description: "Partner specific brand identifier supplied by Subaio. Banks in multiple countries or with sub-brands are provided with multiple brands." example: somebank_dk locale: type: string description: "User locale if known - this allow Subaio to localize push notifications." pattern: "^[A-Za-z]{2,3}[-_]([A-Za-z]{2}|[0-9]{3})$" example: da-DK details: type: object description: "Implementation specific extra details - usually this is empty." LoginRequest: type: object required: - payload properties: payload: type: string description: JWT signed with banks private key containing user id in subject claim, and brand identifier as custom claim. Subaio needs public certificate to verify JWT. TransactionsRequest: type: object required: - reqId - txs properties: reqId: type: string format: uuid description: "Unique request identifier." example: "27e2e489-205c-412e-bb41-e1b65ddf754e" txs: type: string description: "JWE Encrypted list of transactions. The encrypted payload will be a list of Transaction objects, as specified in this document, in JSON format. Depending on the headers, the payload may be compressed before encryption. The maximum number of *Transaction* objects in a single encrypted payload is configurable. \n\n\n The encryption parameters for the JWE are {\"alg\":\"RSA-OAEP\",\"enc\":\"A256GCM\",\"zip\":\"DEF\"}.\n\n\nSee *JweParams* for more details on supported header values.\n\n\nThe payload is an array of Transactions: [{\"uid\":\"ab\",...},{\"uid\":\"cd\",...},...]. Only keys that have a non-null value are sent in the payload, null keys are filtered out during serialization. The receiver must ignore unknown keys, as adding new fields to the models is not considered a breaking change." TransactionsResponse: type: array minItems: 0 items: $ref: "#/definitions/Transaction" Transaction: type: object required: - id - transactionDate - type - amount - currency - merchantName properties: id: type: string description: "ID of the transaction." transactionDate: type: "string" description: "Date of the transaction" type: type: "string" enum: - CARD_PURCHASE - CASH_WITHDRAWAL - OTHER - ACCOUNT_TRANSFER - DIRECT_DEBIT - INVOICE - CASH_DEPOSIT - UNKNOWN description: "The type of transaction." amount: type: number format: double example: 1.23 description: "The amount of the transaction converted to currency." currency: $ref: "#/definitions/Currency" originalAmount: type: number format: double example: 1.23 description: "The amount of the transaction in the original currency." originalCurrency: $ref: "#/definitions/Currency" merchantName: type: "string" description: "Merchant name" example: "Zlatnicka Täityö" serviceId: type: string description: "Service ID related to this transaction. Only present where applicable." example: "34302f6b-d0ae-473e-8e1b-2b500dfa028b" accountId: type: string description: "Account ID related to this transaction. Only present where applicable." cardId: type: string description: "Card ID related to this transaction. Only present where applicable." ServiceUpdateHiddenRequest: type: object required: - hidden properties: hidden: type: boolean description: "New value for hidden for the service." example: "true" AccountsRequest: type: array minItems: 0 items: type: string description: "Account ids the user has access to" example: ["Account id", "Account id2"] ReportRequest: type: object required: - type properties: type: type: string enum: - NEXT_OF_KIN description: "The report type" example: "NEXT_OF_KIN" effectiveDate: type: string format: date default: now description: "Currently not in use, placeholder for future implementations" example: "2021-03-17" ReportResponse: type: object required: - documentId properties: documentId: type: string format: uuid description: "Unique document identifier" example: "fcc113b7-fd34-4d63-81d1-a154c5014139" AccountsBalancesRequest: type: object required: - accounts properties: accounts: type: array minItems: 1 items: $ref: "#/definitions/AccountBalance" AccountBalance: type: object required: - accountId - observedTime - balance properties: accountId: type: string description: "The unique id of the account." accountName: type: string description: "Name of the account" observedTime: description: "At what time this balance observed." type: string balance: type: number format: double example: 1234.56 BudgetRequest: type: object properties: userData: $ref: "#/definitions/BudgetUserData" BudgetAdjustCategoryRequest: type: object required: - amount - frequency properties: amount: type: number format: double example: 299.95 frequency: $ref: "#/definitions/PaymentFrequency" BudgetCoapplicantRequest: type: object required: - type properties: type: type: string description: "Applicant type" $ref: "#/definitions/BudgetApplicantType" budgetId: type: string format: uuid description: "Applicable only if type is SEPARATE_FINANCES" BudgetCompletionsRequest: type: object required: - status properties: status: type: string description: "New status for budget" enum: - ACCEPTED - DENIED BudgetSkipRequest: type: object required: - notApplicable properties: notApplicable: type: boolean example: true BudgetActionRequest: type: object required: - categories - type - serviceId - amount - transactionId - title properties: categories: type: array minItems: 0 items: properties: id: type: string example: "house_internet" amount: type: number format: double example: 299.95 paymentFrequency: $ref: "#/definitions/PaymentFrequency" type: $ref: "#/definitions/BudgetTransactionalType" serviceId: type: string format: uuid example: "34302f6b-d0ae-473e-8e1b-2b500dfa028b" amount: type: number format: double example: 1.23 paymentFrequency: $ref: "#/definitions/PaymentFrequency" transactionId: type: string format: uuid example: "54070120-823d-4227-b70a-9f226b8f4b1e" title: type: string example: "Rent" BudgetUserDataRequest: $ref: "#/definitions/BudgetUserData" # Responses LoginResponse: type: object required: - token properties: token: type: string ServiceResponse: type: object required: - averageTotalAmount - services properties: averageTotalAmount: type: "number" format: "double" description: "Estimated average monthly amount payed to subscriptions." example: -1115.92 services: type: array minItems: 0 items: $ref: "#/definitions/Service" totalAmountLastTwelveMonths: type: "number" format: "double" description: "The total amount paid for all services in the last twelve months." example: 1200.00 alerts: type: array minItems: 0 description: "An array with any of #/definitions/CrowdsourcingAlert and #/definitions/MembershipAlert" items: $ref: "#/definitions/Alert" UpcomingPaymentsResponse: type: array minItems: 0 items: $ref: "#/definitions/UpcomingPayment" TransactionsErrorResponse: type: object required: - errorCode properties: errorCode: type: string enum: - TX_DATA_ERROR - SIGNATURE_ERROR - DECRYPTION_ERROR - UNKNOWN_ERROR BudgetCreateResponse: type: object required: - id properties: id: type: string format: uuid example: "c8f2df69-1162-435c-9486-4e27506cbf9e" BudgetResponse: $ref: "#/definitions/Budget" BudgetDetailsResponse: $ref: "#/definitions/BudgetDetails" BudgetExpenseResponse: $ref: "#/definitions/Expense" BudgetUserDataResponse: $ref: "#/definitions/BudgetUserData" BudgetActionResponse: type: object required: - id - title - content - skipped - type properties: id: type: string format: uuid example: "c8f2df69-1162-435c-9486-4e27506cbf9e" title: type: string example: "Action title" content: type: string example: "Please recategorize [expense.product.title]" skipped: type: boolean example: false type: type: string enum: - RECATEGORIZATION - MISSING_CATEGORY expense: $ref: "#/definitions/Expense" description: "Only present on type = 'RECATEGORIZATION'" potentialCategories: type: array minItems: 2 # If 0 then it must be in "uncategorized", if 1 then it was matched, therefore it must be at least 2 description: "Only present on type = 'RECATEGORIZATION'" items: type: string example: - "house_electricity" - "house_internet" category: type: string description: "Only present on type = 'MISSING_CATEGORY'" example: "house_rent" BudgetCommentRequest: type: object required: - comment properties: comment: type: string example: "This is a user provided comment" minLength: 1 maxLength: 65535 Currency: type: "string" pattern: "^[A-Z]{3}$" description: "ISO 4217 alphabetic currency code for the transaction currency, i.e. the cardholder's own currency." example: "NOK" Store: type: object description: "Contains information of the store connected to the service." required: - type - url properties: type: type: "string" enum: - ITUNES - GOOGLE_PLAY description: "Type of the store." url: type: string example: https://cdn.demo.subaio.com/products/DK/b025dc90-ea55-11e7-9343-0242ac130002/e8266645cb3aff1d8b36329281a3ffa5.png description: "Reference to the stores subscription list. " PaymentFrequency: type: string enum: - DAILY - WEEKLY - BIWEEKLY - MONTHLY - BIMONTHLY - QUARTERLY - HALFYEARLY - YEARLY - UNKNOWN example: MONTHLY BudgetApplicantType: type: string enum: - SHARED_FINANCES - SEPARATE_FINANCES example: SHARED_FINANCES NotificationType: type: string enum: - NEW_PAYMENT - NEW_SUBSCRIPTION - NEW_PAYMENT_CANCELLED_SUBSCRIPTION - CANCELLATION_MORE_INFORMATION_REQUIRED - CANCELLATION_CONFIRMED - CANCELLATION_ABORTED BudgetReport: type: object properties: reportId: type: string maxLength: 50 description: "Identifier to be shown in report." example: "c8f2df69-1162-435c-9486-4e27506cbf9e" BudgetSpending: type: object required: - averages - lows - highs properties: averages: type: object $ref: "#/definitions/BudgetAverageSpending" lows: type: object $ref: "#/definitions/BudgetAverageSpending" highs: type: object $ref: "#/definitions/BudgetAverageSpending" BudgetAverageSpending: type: object required: - lastMonth - months properties: lastMonth: type: number lastThreeMonths: type: number description: "Null if transaction data does not go three months back, starting from last month." lastTwelveMonths: type: number description: "Null if transaction data does not go twelve months back, starting from last month." months: type: array minItems: 12 maxItems: 12 items: $ref: "#/definitions/BudgetMonthlySpending" BudgetMonthlySpending: type: object required: - month properties: month: type: string description: "Format is YYYY-MM" example: "2022-06" amount: type: number example: 1234.56 description: "Null if no transactions exists for this month." Alert: type: object required: - id - source properties: id: type: string description: "Unique ID for the alert." source: type: string description: "Which kind of alert." AlertSource: type: string enum: - MEMBERSHIP - CROWDSOURCING description: | The kind of alert. - MEMBERSHIP "#/definitions/MembershipAlert" - CROWDSOURCING "#/definitions/CrowdsourcingAlert" MembershipAlertType: type: string enum: - WARNING description: "Describes the severity of the alert." MembershipAlert: type: object required: - id - membershipAlertType - product - transaction allOf: - $ref: "#/definitions/Alert" - properties: id: type: string description: "Unique ID for the alert." membershipAlertType: $ref: "#/definitions/MembershipAlertType" product: type: object $ref: "#/definitions/Product" transaction: type: object $ref: "#/definitions/Transaction" CrowdsourcingAlertType: type: string enum: - SUCCESS - NOT_SUBSCRIPTION - TECHNICAL_LIMITATION CrowdsourcingAlert: type: object required: - id - type - crowdsourceTime - sourceTransactionId - transaction - product - paymentFrequency - amount - currency allOf: - $ref: "#/definitions/Alert" - properties: id: type: string description: "Unique ID for the alert." type: $ref: "#/definitions/CrowdsourcingAlertType" crowdsourceTime: type: string description: "Timestamp of the crowdsourcing time." example: "2018-11-16T12:45:53+02:00" sourceTransactionId: type: string description: "The transaction ID of the original transaction provided by the bank." transaction: type: object $ref: "#/definitions/Transaction" product: type: object $ref: "#/definitions/Product" paymentFrequency: $ref: "#/definitions/PaymentFrequency" amount: type: number format: double example: 1.23 description: "The amount of the payment crowdsourced." currency: $ref: "#/definitions/Currency" originalAmount: type: number format: double example: 1.23 description: "The amount of the payment crowdsourced." originalCurrency: $ref: "#/definitions/Currency" VisibilityOptionType: type: string description: "Wether to ask the user if they want the service shown or hidden. ASK_BOTH refers to the scenario of a 'possible subscription', where the subscription was just added and the merchant also sells other non-recurring items under the same description. If that is the case, we ask the user if it is a purchase or a subscription." enum: - ASK_TO_HIDE - ASK_TO_SHOW - ASK_BOTH - HIDE example: "ASK_TO_HIDE" CancellationOptionType: type: string description: | - POSSIBLE: Cancellation is possible. - EXPLAIN_WHY_NOT: Cancellations for a product may be disabled if the company is not accepting cancellation requests - STORE: Store subscriptions, such as iTunes, cannot be cancelled automatically by us. - HIDE: Hide the ability to cancel the subscription from the user. There are certain instances where a service cannot be cancelled: fixed products (such as insurance, rent, or utility bills); if the user already has an ongoing cancellation for this service; if we are not sure if it's a subscription or the user has hidden the service. enum: - POSSIBLE - EXPLAIN_WHY_NOT - STORE - HIDE example: "HIDE" AmountToDisplayType: type: string description: | Amount data are sometimes not fully available, which means we might have to fall back to a more accurate number - TOTAL_LAST_TWELVE_MONTHS - Fallback to use `totalLastTwelveMonths` instead of `amount` - AMOUNT - Should use `amount` and not `totalLastTwelveMonths` enum: - TOTAL_LAST_TWELVE_MONTHS - AMOUNT example: "AMOUNT" CancellationAbortReason: type: string description: | Reason cancellation was aborted. - USER_NOT_RESPONDING - user has not responded to request by support. - USER_ABORTED - the user has aborted the cancellation process. - COMPANY_NOT_RESPONDING - company has not replied to the cancellation request. - COMPANY_NOT_ACCEPTING - company does not accept cancellation requests. - COMPANY_CANNOT_FIND_SUBSCRIPTION - company could not find the subscription. Usually happens if a wrong email is given by the user. - USER_WRONG_INFORMATION_PROVIDED_MULTIPLE_TIMES - user has given us the wrong information repeatably. - BRANCH_UNKNOWN - we could not find the branch/country/service the user had submitted. - CONTINUATION_DEAL - user has accepted a deal made by the company to continue the subscription. enum: - USER_NOT_RESPONDING - USER_ABORTED - COMPANY_NOT_RESPONDING - COMPANY_NOT_ACCEPTING - COMPANY_CANNOT_FIND_SUBSCRIPTION - USER_WRONG_INFORMATION_PROVIDED_MULTIPLE_TIMES - BRANCH_UNKNOWN - CONTINUATION_DEAL example: "USER_NOT_RESPONDING" AlertSeenRequest: type: array minItems: 0 items: type: string format: uuid description: "Alert IDs that should be marked as seen" example: ["88dd6b5d-69db-43ef-87df-638688b37756", "664f30b2-123e-40c5-90ed-78495dc00fb4"]