Payment Gateways

Endpointhttps://api.kontorion.eu/v1

A payment gateway configuration connects Kontorion to an external payment processor (Stripe, GoCardless, or other providers) for collecting payments from customers.

Each organization can have multiple gateway configurations - for example, Stripe for card payments and GoCardless for SEPA direct debits. One gateway is marked as the default.

Key concepts:

Provider - the payment processor (stripe, gocardless, etc.)
Mode - live or test - determines whether real charges are made
Supported currencies - which currencies this gateway can process
Supported methods - which payment methods this gateway handles (card, direct_debit, etc.)

List payment gateways

GET

https://api.kontorion.eu/v1

/payment-gateways

Returns all payment gateway configurations for the organization. Sensitive config fields are masked. Requires the gateway.read permission.

List payment gateways › Headers

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

List payment gateways › Responses

array | null · required

object · required

GET/payment-gateways

curl --request GET \
  --url https://api.kontorion.eu/v1/payment-gateways

shell

Example Responses

{
  "data": [
    {
      "config": {
        "access_token": "access_token",
        "api_base": "api_base",
        "api_key": "api_key",
        "stripe_account_id": "stripe_account_id",
        "webhook_secret": "webhook_secret"
      },
      "created_at": "2024-08-25T15:00:00Z",
      "display_name": "display_name",
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "is_default": true,
      "is_enabled": true,
      "metadata": {
        "key": {}
      },
      "mode": "mode",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "provider": "provider",
      "supported_currencies": [
        "string"
      ],
      "supported_methods": [
        "string"
      ],
      "updated_at": "2024-08-25T15:00:00Z",
      "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a payment gateway configuration

POST

https://api.kontorion.eu/v1

/payment-gateways

Requires the gateway.manage permission: the row holds the org's live provider secret.

Create a payment gateway configuration › Headers

Idempotency-Key

string · required

Unique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a payment gateway configuration › Request Body

object

Provider-specific credential document. Stripe: api_key (required), stripe_account_id, webhook_secret, api_base. GoCardless: access_token, webhook_secret. PATCH merges shallowly - send only the keys to change; omitted keys keep their stored value (so a masked read never needs to be resent).

display_name

string

mode

string

provider

string

supported_currencies

array | null

supported_methods

array | null

Create a payment gateway configuration › Responses

Created

object · required

POST/payment-gateways

curl --request POST \
  --url https://api.kontorion.eu/v1/payment-gateways \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "config": {
    "access_token": "access_token",
    "api_base": "api_base",
    "api_key": "api_key",
    "stripe_account_id": "stripe_account_id",
    "webhook_secret": "webhook_secret"
  },
  "display_name": "display_name",
  "mode": "mode",
  "provider": "provider",
  "supported_currencies": [
    "string"
  ],
  "supported_methods": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "config": {
    "access_token": "access_token",
    "api_base": "api_base",
    "api_key": "api_key",
    "stripe_account_id": "stripe_account_id",
    "webhook_secret": "webhook_secret"
  },
  "display_name": "display_name",
  "mode": "mode",
  "provider": "provider",
  "supported_currencies": [
    "string"
  ],
  "supported_methods": [
    "string"
  ]
}

json

Example Responses

{
  "data": {
    "config": {
      "access_token": "access_token",
      "api_base": "api_base",
      "api_key": "api_key",
      "stripe_account_id": "stripe_account_id",
      "webhook_secret": "webhook_secret"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "display_name": "display_name",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_default": true,
    "is_enabled": true,
    "metadata": {
      "key": {}
    },
    "mode": "mode",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "supported_currencies": [
      "string"
    ],
    "supported_methods": [
      "string"
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Get a payment gateway configuration

GET

https://api.kontorion.eu/v1

/payment-gateways/{id}

Returns one gateway configuration by ID. Sensitive config fields are masked. Requires the gateway.read permission.

Get a payment gateway configuration › path Parameters

id

string · uuid · required

Gateway config UUID

Get a payment gateway configuration › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a payment gateway configuration › Responses

object · required

GET/payment-gateways/{id}

curl --request GET \
  --url https://api.kontorion.eu/v1/payment-gateways/:id

shell

Example Responses

{
  "data": {
    "config": {
      "access_token": "access_token",
      "api_base": "api_base",
      "api_key": "api_key",
      "stripe_account_id": "stripe_account_id",
      "webhook_secret": "webhook_secret"
    },
    "created_at": "2024-08-25T15:00:00Z",
    "display_name": "display_name",
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_default": true,
    "is_enabled": true,
    "metadata": {
      "key": {}
    },
    "mode": "mode",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "supported_currencies": [
      "string"
    ],
    "supported_methods": [
      "string"
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

Delete a payment gateway configuration

DELETE

https://api.kontorion.eu/v1

/payment-gateways/{id}

Requires the gateway.manage permission: the row holds the org's live provider secret.

Delete a payment gateway configuration › path Parameters

id

string · uuid · required

Gateway config UUID

Delete a payment gateway configuration › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a payment gateway configuration › Responses

No Content

No data returned

Update a payment gateway configuration

PATCH

https://api.kontorion.eu/v1

/payment-gateways/{id}

Requires the gateway.manage permission: the row holds the org's live provider secret.

Update a payment gateway configuration › path Parameters

id

string · uuid · required

Gateway config UUID

Update a payment gateway configuration › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a payment gateway configuration › Request Body

object

display_name

string

is_default

boolean

is_enabled

boolean

mode

string

supported_currencies

array | null

supported_methods

array | null

Update a payment gateway configuration › Responses

object · required

PATCH/payment-gateways/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/payment-gateways/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "access_token": "access_token",
    "api_base": "api_base",
    "api_key": "api_key",
    "stripe_account_id": "stripe_account_id",
    "webhook_secret": "webhook_secret"
  },
  "display_name": "display_name",
  "is_default": true,
  "is_enabled": true,
  "mode": "mode",
  "supported_currencies": [
    "string"
  ],
  "supported_methods": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "config": {
    "access_token": "access_token",
    "api_base": "api_base",
    "api_key": "api_key",
    "stripe_account_id": "stripe_account_id",
    "webhook_secret": "webhook_secret"
  },
  "display_name": "display_name",
  "is_default": true,
  "is_enabled": true,
  "mode": "mode",
  "supported_currencies": [
    "string"
  ],
  "supported_methods": [
    "string"
  ]
}

json

Example Responses

{
  "data": {
    "id": "id",
    "updated": true
  }
}

json

application/json

Product Meter Bindings Payment Methods

List payment gateways

GET

https://api.kontorion.eu/v1

/payment-gateways

Returns all payment gateway configurations for the organization. Sensitive config fields are masked. Requires the gateway.read permission.

List payment gateways › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List payment gateways › Responses

array | null · required

object · required

Create a payment gateway configuration

POST

https://api.kontorion.eu/v1

/payment-gateways

Requires the gateway.manage permission: the row holds the org's live provider secret.

Create a payment gateway configuration › Headers

Idempotency-Key

string · required

Client-generated idempotency key (e.g. a UUID).

X-Workspace-Id

string

Workspace UUID or slug.

Create a payment gateway configuration › Request Body

object

display_name

string

mode

string

provider

string

supported_currencies

array | null

supported_methods

array | null

Create a payment gateway configuration › Responses

Created

object · required

Get a payment gateway configuration

GET

https://api.kontorion.eu/v1

/payment-gateways/{id}

Returns one gateway configuration by ID. Sensitive config fields are masked. Requires the gateway.read permission.

Get a payment gateway configuration › path Parameters

id

string · uuid · required

Gateway config UUID

Get a payment gateway configuration › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a payment gateway configuration › Responses

object · required

Delete a payment gateway configuration

DELETE

https://api.kontorion.eu/v1

/payment-gateways/{id}

Requires the gateway.manage permission: the row holds the org's live provider secret.

Delete a payment gateway configuration › path Parameters

id

string · uuid · required

Gateway config UUID

Delete a payment gateway configuration › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a payment gateway configuration › Responses

No Content

No data returned

Update a payment gateway configuration

PATCH

https://api.kontorion.eu/v1

/payment-gateways/{id}

Requires the gateway.manage permission: the row holds the org's live provider secret.

Update a payment gateway configuration › path Parameters

id

string · uuid · required

Gateway config UUID

Update a payment gateway configuration › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a payment gateway configuration › Request Body

object

display_name

string

is_default

boolean

is_enabled

boolean

mode

string

supported_currencies

array | null

supported_methods

array | null

Update a payment gateway configuration › Responses

object · required