Banqup API Docs

Register a new application in Banqup Store

In the Banqup ecosystem, apps can take various forms including standalone applications, connectors, or services that extend the platform's capabilities. This recipe explains the step-by-step process for developers to add a new application to the Banqup Store.

Prerequisites

Banqup Developer Portal account and app. See guide.
The application supports user space type and segment.

Endpoint: /servicemngmt/v2/applications/{applicationId}/infoLocalizations

Path parameter: applicationId

Requires a JSON request body (see curl example below).

curl -L -X POST 'https://{{serverURL}}/servicemngmt/v2/applications/2aa7c756-6d55-44b6-9b60-06212611cfd6/infoLocalizations' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{ 
 "locale": "en-GB",
 "displayName": "Purchase app",
 "shortDescription": "Manage purchase invoices",
 "description": "Purchases app helps you manage your purchase invoices"
}

Successful response:

{
 "id": "2aa7c756-6d55-44b6-9b60-06212611cfd6",
 "locale": "en-GB",
 "displayName": "Purchase app",
 "shortDescription": "Manage purchase invoices",
 "description": "Purchases app helps you manage your purchase invoices"
}

Endpoint: /servicemngmt/v1/applications/{applicationId}/logo

Path parameter: applicationId

Requires a multipart/form-data request body (see curl example below).

curl -L -X PUT 'https://{{serverURL}}/servicemngmt/v1/applications/2aa7c756-6d55-44b6-9b60-06212611cfd6/logo' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
--form 'logoFile=@"/home/logos/My-app-logo.svg"'

Successful response: The logo is successfully added to the app.

Endpoint: /servicemngmt/v1/applications/{applicationId}/medias

Path parameter: applicationId

Requires a multipart/form-data request body (see curl example below).

curl -L -X POST 'https://{{serverURL}}/servicemngmt/v1/applications/2aa7c756-6d55-44b6-9b60-06212611cfd6/medias' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
--form 'mediaFile=@"/home/medias/My-media.svg"'
--form 'displayOrder="1"' \
--form 'mediaType="IMAGE"'

Successful response:

{
    "id": "8fb022af-f5ec-4491-b8e6-1073c195657c",
    "applicationId": "2aa7c756-6d55-44b6-9b60-06212611cfd6",
    "mediaType": "IMAGE",
    "displayOrder": 1
}

Endpoint: /servicemngmt/v1/applications/{applicationId}/spaceTypes

Path parameter: applicationId

Requires a JSON request body (see curl example below).
Possible options for spaceType property:

BUSINESS: A business space is owned by a legal organization or a sole trader. This space type supports common business needs like invoicing, payments, financing, document exchange, communication with other Banqup partners, etc.

PARTNER: A partner is a Banqup space owner that is authorized to manage multiple other Banqup spaces, whose owners are the partner's clients. Partners can be: accountants, associations, guardians, software partners or financial institutions.

curl -L -X POST 'https://{{serverURL}}/servicemngmt/v1/applications/2aa7c756-6d55-44b6-9b60-06212611cfd6/spaceTypes' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "spaceType": "BUSINESS"
}

Successful response:

{
  "id": "2aa7c756-6d55-44b6-9b60-06212611cfd6",
  "spaceType": "BUSINESS"
}

Segments are subdivisions based on space types. Defining a space segment determines which segments the application will be limited to.

Endpoint: /servicemngmt/v2/applications/{applicationId}/spaceSegments

Path parameter:

applicationId

Requires a JSON request body (see curl example below).
Possible options for spaceSegment property:

Value	Space Type	Description
`ALL`	ALL	Applies to all space segments. This is the default.
`ALL`	APPLICATION	Applies only to the Applications segment.
`SME`	BUSINESS	Small and medium-sized businesses.
`CORPORATE`	BUSINESS	Large enterprises.
`ACCOUNTING`	PARTNER	Accounting partners.
`RESELLER`	PARTNER	Reseller partners.
`CARETAKER`	PARTNER	Caretaker partners.
`REFERRAL_PARTNER`	PARTNER	Referral partners.

curl -L -X POST 'https://{{serverURL}}/servicemngmt/v2/applications/2aa7c756-6d55-44b6-9b60-06212611cfd6/spaceTypes' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "spaceSegment": "CORPORATE"
}

Successful response:

{
  "id": "2aa7c756-6d55-44b6-9b60-06212611cfd6",
  "spaceSegment": "CORPORATE"
}

Assigning a brand means that the application will only be available to that Banqup brand.

Endpoint: /servicemngmt/v1/applications/{applicationId}/brands

Path parameter: applicationId

Requires a JSON request body (see curl example below).
Possible options for brandName property:

Banqup: available in the European Union.

Jefacture: available only in France.

ALL: Applies to all brands.

curl -L -X POST 'https://{{serverURL}}/servicemngmt/v1/applications/2aa7c756-6d55-44b6-9b60-06212611cfd6/brands' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "brandName": "Banqup"
}

Successful response:

{
  "id": "2aa7c756-6d55-44b6-9b60-06212611cfd6",
  "brandName": "Banqup"
}

Assigning a location to an app determines in which countries the app will be visible in the Banqup Store.
If the countryCode has value ALL, the app will be visible in all our available locations.

Endpoint: /servicemngmt/v1/applications/{applicationId}/locations

Path parameter: applicationId

Requires a JSON request body (see curl example below).

curl -L -X POST 'https://{{serverURL}}/servicemngmt/v1/applications/2aa7c756-6d55-44b6-9b60-06212611cfd6/locations' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d '{
  "countryCode": "BE",
  "status": "ACTIVE"
}

Successful response:

{
  "id": "2aa7c756-6d55-44b6-9b60-06212611cfd6",
  "countryCode": "BE",
  "status": "ACTIVE"
}

Endpoint: /servicemngmt/v1/applications/{applicationId}/versions

Path parameter: applicationId

Requires a JSON request body with a manifest object and app callbacks. See details and curl example below.

To add an app version, a manifest object must be provided. This is also required for each additional version you add in the future.

Property	Description	Required
serviceAccount	Refers to the app ID of the app created in Developer Portal.	Yes
accessManagement	Defines the permissions assigned to the app and, if applicable, to security groups. Review the scope required for each endpoint you intend to use to know which permissions you need.	No
dependencies	If your app has dependencies, contact Banqup or Intercom. Note that the Banqup Store validates all required dependencies. If dependencies are missing, application version registration is delayed until they are resolved.	No
minAssuranceLevels	The levels of security required to use the application (e.g. `urn:btx:L1`, `L2`, `L3`, `L50`, `L100`).	No
clientConfigurations	Defines access management and interaction endpoints used to install partner applications across multiple clients.	No
appCallbacks	Defines the callback URLs used by the platform to notify your app about lifecycle events (e.g. install, activate, configure, remove). See details below.	No

App callbacks are endpoints interacting with the application invoked via POST method. The expected response for a successful API call is 200 OK.
Your own security token may be provided for authorization header.

Add extension callback

This endpoint is triggered when an extension is added to a space. It retrieves the default configuration or settings based on the available entity or space data, and activate the extension if the configuration allows it.

POST <addUrl>
{
  "entityId" : "<entityId>”,
  "spaceId" : "<spaceId>”,
  "extensionId": "<appId>",
  "namespace": "my_namespace",
  "name": "my_app"
}

Activate extension callback

This endpoint is triggered when a user activates an extension that has already been added to the space but is currently inactive.

POST <activationUrl>
{
  "entityId" : "<entityId>”,
  "spaceId" : "<spaceId>”,
  "extensionId": "<appId>",
  "namespace": "my_namespace",
  "name": "my_app"
}

Deactivate extension callback

This endpoint is triggered when a user deactivates an extension that has already been added to the space and is currently active.

POST <deactivationUrl>
{
  "entityId" : "<entityId>”,
  "spaceId" : "<spaceId>”,
  "extensionId": "<appId>",
  "namespace": "my_namespace",
  "name": "my_app"
}

Configure extension callback

This endpoint is triggered when a user updates the configuration of an extension that has already been added to a space.
The endpoint implementation validates the provided settings and stores them in the Banqup system. If the settings are valid and meet the necessary requirements, the extension is activated.
If any issues are detected with the settings, the endpoint returns an error response. This response can then be used to display appropriate error messages to the user, indicating what needs to be corrected.

POST <configureUrl>
{
  "entityId" : "<entityId>”,
  "spaceId" : "<spaceId>”,
  "extensionId": "<appId>",
  "namespace": "my_namespace",
  "name": "my_app"
  “settings”: { }
}

The expected response for a valid configuration that requires a redirect (for example, when settings need an OAuth access token):

302 Found

Location: http://www.redirecthost.test/domains/example?redirectUrl="https://extension.domain.test?configRedirect=$extensionConfigUrl"

In some cases, the configuration may require redirecting the user to a third-party service for authentication (for example, Google authentication for Google Drive), and then redirecting them back to the configuration screen to continue the setup.
To support this flow, the POST endpoint can return a redirectUrl in its response. The UI will use this URL to redirect the user accordingly. The redirect URL should include a placeholder for the configuration URL, allowing the user to be redirected back after authentication. Alternatively, this can also be handled using a hidden configuration form parameter.

Remove extension callback

This endpoint is triggered when an extension is removed from the space.

POST <removeUrl>
{
  "entityId" : "<entityId>”,
  "spaceId" : "<spaceId>”,
  "extensionId": "<appId>",
  "namespace": "my_namespace",
  "name": "my_app"
}

curl -L -X POST 'https://{{serverURL}}/servicemngmt/v1/applications/2aa7c756-6d55-44b6-9b60-06212611cfd6/versions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-{
  "version": "1.0.0",
  "releaseNote": "Initial release notes",
  "releaseDate": "2026-04-16T13:03:36Z",
  "manifest": {
    "serviceAccount": "f47c5440-89cb-11ee-b9d1-0242ac120002",
    "accessManagement": {
      "permissions": [
        {
          "resource": "space",
          "scope": "space_read"
        },
        {
          "resource": "space",
          "scope": "space_write"
        }
      ]
    },
    "appCallbacks": {
      "addUrl": "http://myapp.domain/add",
      "activationUrl": "http://myapp.domain/activate",
      "deactivationUrl": "http://myapp.domain/deactivate",
      "configureUrl": "http://myapp.domain/configure",
      "removeUrl": "http://myapp.domain/remove",
      "security": {
        "authorizationHeader": "my-token"
      }
    },
    "minAssuranceLevels": {
      "entity": "urn:btx:L2",
      "user": "urn:btx:L1"
    }
  },
  "copyright": "Copyright 2026 Banqup"
}

Successful response:

{
  "id": "2aa7c753-6d55-44b6-9b60-06212611cfd6",
          "version": "1.0.0",
          "releaseNote": "Initial release notes",
          "releaseDate": "2026-04-16T13:03:36Z",
          "manifest": {
    "accessManagement": {
      "permissions": [
        {
          "resource": "space",
          "scope": "space_read"
        },
        {
          "resource": "space",
          "scope": "space_write"
        }
      ]
    },
    "additionalScopes": {
      "spaceScopes": [
        "valitax_manage_configuration"
      ],
              "translations": "http://app.valitax.com/btx/translations"
    },
    "appCallbacks": {
      "addUrl": "http://myapp.domain/add",
              "activationUrl": "http://myapp.domain/activate",
              "deactivationUrl": "http://myapp.domain/deactivate",
              "configureUrl": "http://myapp.domain/configure",
              "removeUrl": "http://myapp.domain/remove"
    },
    "minAssuranceLevels": {
      "entity": "urn:btx:L2",
              "user": "urn:btx:L1"
    }
  },
  "copyright": "Copyright 2026 Banqup",
          "status": "VALID"
}

Register a new application in Banqup Store​

Prerequisites​

Add extension callback​

Activate extension callback​

Deactivate extension callback​

Configure extension callback​

Remove extension callback​

Register a new application in Banqup Store

Prerequisites

Add extension callback

Activate extension callback

Deactivate extension callback

Configure extension callback

Remove extension callback