openapi: 3.0.3
info:
  version: '1.0'
  title: Company authorization bank-payments API
  description: The Bokio Company API containing all resources for company tenant.
  termsOfService: https://docs.bokio.se/page/terms/
  contact:
    name: Bokio
    url: https://docs.bokio.se
    email: support@bokio.se
servers:
- url: https://api.bokio.se/v1
  description: Bokio API
  x-bokio-api: true
security:
- tokenAuth: []
tags:
- name: bank-payments
  description: Operations for creating and reading bank payments
paths:
  /companies/{companyId}/bank-payments:
    parameters:
    - name: companyId
      in: path
      required: true
      description: Unique identifier of the company
      schema:
        type: string
        format: uuid
      example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
    post:
      tags:
      - bank-payments
      summary: Create a bank payment
      description: 'Creates a new bank payment for the company. Payment will be created in the Bokio system.

        In order to submit the transaction to the bank, the signatory for the account needs to login to the Bokio application and sign the payment with their BankID.

        This is different from the transactions imported through a connected bank in Bokio.


        **Scope:** `bank-payments:write`

        '
      operationId: post-bank-payment
      requestBody:
        description: Post the necessary fields for the API to create a new bank payment.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bank-payment'
            examples:
              Account transfer payment:
                value:
                  amount: 1200
                  paymentDate: 2025-08-25
                  ownNote: Rent payment
                  recipientRef:
                    kind: transfer
                    recipientName: Property Management Co
                    recipientReference: RENT-2025-08
                    clearingNumber: '5011'
                    accountNumber: 0379101
              Bankgiro payment:
                value:
                  amount: 2500.5
                  paymentDate: 2025-08-25
                  ownNote: Monthly service payment
                  recipientRef:
                    kind: bankgiro
                    recipientName: Tech Solutions Ltd
                    bankgiroNumber: 123-4567
                    ocr: '123456789012345'
      responses:
        '200':
          description: Payment created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bank-payment'
              examples:
                Payment created:
                  value:
                    id: 835ba700-b306-4bd9-8447-59207b6b0002
                    status: readyToSign
                    amount: 1200
                    createdDateTime: 2025-08-25 08:15:00+00:00
                    paymentDate: 2025-08-25
                    ownNote: Rent payment
                    recipientRef:
                      kind: transfer
                      recipientName: Property Management Co
                      recipientReference: RENT-2025-08
                      clearingNumber: '5011'
                      accountNumber: 0379101
        '400':
          description: Missing required information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
              examples:
                Error:
                  value:
                    code: validation-error
                    message: Validation failed with 2 errors
                    bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
                    errors:
                    - field: '#/amount'
                      message: The amount field is required
                    - field: '#/recipientRef'
                      message: The recipientRef field is required
      security:
      - tokenAuth: []
    get:
      tags:
      - bank-payments
      summary: Get bank payments
      description: 'Get all bank payments for the company that were created by the integration.

        **Scope:** `bank-payments:read-limited`'
      operationId: get-bank-payments-limited
      parameters:
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
          format: int32
          default: 1
      - name: pageSize
        in: query
        required: false
        description: Number of items per page
        schema:
          type: integer
          format: int32
          default: 25
          maximum: 100
      - name: query
        in: query
        required: false
        description: 'Optional query to filter the data set with supported fields listed below and [available operations](filtering).


          | Field                | Type        |

          | -------------------- | ----------- |

          | amount               | number      |

          | status               | string      |

          | paymentDate          | date-time   |

          | createdDateTime      | date-time   |

          '
        schema:
          type: string
        example: amount==1200.00
      responses:
        '200':
          description: Bank payments found
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/pagedResponse'
                - type: object
                  properties:
                    items:
                      type: array
                      items:
                        $ref: '#/components/schemas/bank-payment'
        '400':
          description: Invalid query filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
              examples:
                invalid-filter:
                  value:
                    code: validation-error
                    message: The provided filter 'amount===oops' is not valid. Please check the format of the query parameter
                    bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
                    errors:
                    - field: query
                      message: The provided filter 'amount===oops' is not valid. Please check the format of the query parameter
      security:
      - tokenAuth: []
  /companies/{companyId}/bank-payments/{bankPaymentId}:
    parameters:
    - name: companyId
      in: path
      required: true
      description: Unique identifier of the company
      schema:
        type: string
        format: uuid
      example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
    - name: bankPaymentId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 835ba700-b306-4bd9-8447-59207b6b0002
      description: Unique identifier of the bank payment
    get:
      tags:
      - bank-payments
      summary: Get a bank payment created by the integration
      description: 'Retrieve the information of the bank payment with the matching bankPaymentId.


        **Scope:** `bank-payments:read-limited`

        '
      operationId: get-bank-payments-bank-payment-id
      responses:
        '200':
          description: Bank payment found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bank-payment'
              examples:
                bank payment found:
                  value:
                    id: 835ba700-b306-4bd9-8447-59207b6b0002
                    status: readyToSign
                    createdDateTime: 2025-08-25 08:15:00+00:00
                    amount: 1500
                    paymentDate: 2025-08-25
                    ownNote: 'Payment for invoice #INV-2025-001'
                    recipientRef:
                      kind: transfer
                      recipientName: Property Management Co
                      recipientReference: RENT-2025-08
                      clearingNumber: '8000'
                      accountNumber: '1234567890'
        '404':
          description: Bank payment not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
              examples:
                Error:
                  value:
                    code: not-found
                    message: Bank payment not found
                    bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
      security:
      - tokenAuth: []
  /companies/{companyId}/bank-payments/bulk:
    parameters:
    - name: companyId
      in: path
      required: true
      description: Unique identifier of the company
      schema:
        type: string
        format: uuid
      example: ea9ee4dd-fae3-4aec-a7db-6fc9cc1f8135
    post:
      tags:
      - bank-payments
      summary: Bulk create bank payments
      description: 'Creates multiple bank payments for the company in a single request. Up to 100 payments can be created per request.


        The operation is atomic — if any payment fails validation, no payments are created.


        **Scope:** `bank-payments:write`

        '
      operationId: post-bank-payments-bulk
      requestBody:
        description: List of bank payments to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bulk-create-bank-payments-request'
            examples:
              Two payments:
                value:
                  payments:
                  - amount: 1200
                    paymentDate: 2025-08-25
                    ownNote: Rent payment
                    recipientRef:
                      kind: transfer
                      recipientName: Property Management Co
                      recipientReference: RENT-2025-08
                      clearingNumber: '5011'
                      accountNumber: 0379101
                  - amount: 2500.5
                    paymentDate: 2025-08-25
                    ownNote: Service payment
                    recipientRef:
                      kind: bankgiro
                      recipientName: Tech Solutions Ltd
                      bankgiroNumber: 123-4567
                      ocr: '123456789012345'
      responses:
        '200':
          description: All payments created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/bank-payment'
              examples:
                All succeeded:
                  value:
                  - id: 835ba700-b306-4bd9-8447-59207b6b0002
                    status: readyToSign
                    amount: 1200
                    createdDateTime: 2025-08-25 08:15:00+00:00
                    paymentDate: 2025-08-25
                    ownNote: Rent payment
                    recipientRef:
                      kind: transfer
                      recipientName: Property Management Co
                      recipientReference: RENT-2025-08
                      clearingNumber: '5011'
                      accountNumber: 0379101
                  - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    status: readyToSign
                    amount: 2500.5
                    createdDateTime: 2025-08-25 08:15:00+00:00
                    paymentDate: 2025-08-25
                    ownNote: Service payment
                    recipientRef:
                      kind: bankgiro
                      recipientName: Tech Solutions Ltd
                      bankgiroNumber: 123-4567
                      ocr: '123456789012345'
        '400':
          description: 'Validation failed. No payments were created.

            Errors include the payment index in the field path.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apiError'
              examples:
                Payment validation errors:
                  value:
                    code: validation-error
                    message: Validation failed with 2 errors
                    bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
                    errors:
                    - field: '#/payments/0/recipientRef/bankgiroNumber'
                      message: The bankgiro number is invalid
                    - field: '#/payments/1/amount'
                      message: The amount must be greater than 0
                Too many payments:
                  value:
                    code: validation-error
                    message: Validation failed with 1 error
                    bokioErrorId: 9b408943-7a1e-47ac-85a7-ac52b2c210d3
                    errors:
                    - field: '#/payments'
                      message: The number of payments must not exceed 100
      security:
      - tokenAuth: []
components:
  schemas:
    apiError:
      type: object
      title: apiError
      properties:
        code:
          type: string
        message:
          type: string
        bokioErrorId:
          type: string
          format: uuid
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    pagedResponse:
      type: object
      title: pagedResponse
      properties:
        totalItems:
          type: integer
          format: int32
          example: 1
        totalPages:
          type: integer
          format: int32
          example: 1
        currentPage:
          type: integer
          format: int32
          example: 1
    bankgiroRecipient:
      type: object
      properties:
        kind:
          type: string
          enum:
          - bankgiro
        recipientName:
          type: string
          description: Name of the payment recipient
        bankgiroNumber:
          type: string
          description: Bankgiro number (required for Bankgiro payments)
        ocr:
          type: string
          description: OCR reference for the payment. Either `ocr` or `message` must be provided, but not both.
        message:
          type: string
          description: Message for the payment. Either `message` or `ocr` must be provided, but not both.
      required:
      - kind
      - recipientName
      - bankgiroNumber
    bulk-create-bank-payments-request:
      type: object
      properties:
        payments:
          type: array
          minItems: 1
          maxItems: 100
          description: List of bank payments to create (1-100 items)
          items:
            $ref: '#/components/schemas/bank-payment'
      required:
      - payments
    transferRecipient:
      type: object
      properties:
        kind:
          type: string
          enum:
          - transfer
        recipientName:
          type: string
          description: Name of the payment recipient
        recipientReference:
          type: string
          description: Reference for the payment recipient
        clearingNumber:
          type: string
          description: Clearing number (required for Transfer payments)
        accountNumber:
          type: string
          description: Account number (required for Transfer payments)
      required:
      - kind
      - recipientName
      - clearingNumber
      - accountNumber
    bank-payment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the payment
          readOnly: true
        status:
          type: string
          enum:
          - readyToSign
          - onTheWay
          - scheduled
          - paid
          - rejected
          - cancelled
          - error
          description: Current status of the payment
          readOnly: true
        createdDateTime:
          type: string
          format: date-time
          description: Date and time when the payment was created
          readOnly: true
        amount:
          type: number
          format: double
          description: Amount of the payment
        paymentDate:
          type: string
          format: date
          description: Date of the payment
        ownNote:
          type: string
          description: Own note for the payment
        recipientRef:
          description: Payment recipient information
          discriminator:
            propertyName: kind
            mapping:
              bankgiro: '#/components/schemas/bankgiroRecipient'
              transfer: '#/components/schemas/transferRecipient'
          oneOf:
          - $ref: '#/components/schemas/bankgiroRecipient'
          - $ref: '#/components/schemas/transferRecipient'
      example:
        id: 835ba700-b306-4bd9-8447-59207b6b0002
        status: readyToSign
        createdDateTime: 2023-10-01 08:15:00+00:00
        amount: 1000
        paymentDate: 2023-10-01
        ownNote: 'Payment for invoice #12345'
        recipientRef:
          kind: transfer
          recipientName: Property Management Co
          recipientReference: RENT-2025-08
          clearingNumber: '8000'
          accountNumber: '1234567890'
      required:
      - amount
      - paymentDate
      - recipientRef
  securitySchemes:
    tokenAuth:
      type: http
      scheme: bearer
    access_token:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /token
          scopes: {}
        authorizationCode:
          authorizationUrl: /authorize
          tokenUrl: /token
          scopes:
            bank-payments:read-limited: Read access to bank payments created by the integration
            bank-payments:write: Write access to bank payments
            chart-of-accounts:read: Read access to chart of accounts
            company-information:read: Read access to company information
            credit-notes:read: Read access to credit notes
            credit-notes:write: Write access to credit notes
            customers:read: Read access to customers
            customers:write: Write access to customers
            fiscal-years:read: Read access to fiscal years
            invoices:read: Read access to invoices
            invoices:write: Write access to invoices
            items:read: Read access to items
            items:write: Write access to items
            journal-entries:read: Read access to journal entries
            journal-entries:write: Write access to journal entries
            sie:read: Read access to SIE files
            supplier-invoices:read: Read access to supplier invoices
            supplier-invoices:write: Write access to supplier invoices
            suppliers:read: Read access to suppliers
            suppliers:write: Write access to suppliers
            tags:read: Read access to tag groups and tags
            tags:write: Write access to tag groups and tags
            uploads:read: Read access to uploads
            uploads:write: Write access to uploads
    client_auth:
      type: http
      scheme: basic
externalDocs:
  url: https://docs.bokio.se
  description: Read the API Documentation
x-readme:
  explorer-enabled: true
  proxy-enabled: false
  samples-languages:
  - shell
  - http
  - node
  - csharp
  - java