Bokio bank-payments API
Operations for creating and reading bank payments
OpenAPI Specification
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