Payment Gateways

Endpointhttps://api.kontier.eu/v1

A payment gateway configuration connects Kontier 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.kontier.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.kontier.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,
      "last_verified_at": "2024-08-25T15:00:00Z",
      "last_verify_detail": "last_verify_detail",
      "last_verify_ok": true,
      "metadata": {
        "key": {}
      },
      "mode": "mode",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "provider": "provider",
      "supported_currencies": [
        "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.kontier.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 · required

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).

provider

string · required

display_name

string

supported_currencies

array | null

Create a payment gateway configuration › Responses

Created

object · required

POST/payment-gateways

curl --request POST \
  --url https://api.kontier.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",
  "provider": "provider",
  "supported_currencies": [
    "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",
  "provider": "provider",
  "supported_currencies": [
    "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,
    "last_verified_at": "2024-08-25T15:00:00Z",
    "last_verify_detail": "last_verify_detail",
    "last_verify_ok": true,
    "metadata": {
      "key": {}
    },
    "mode": "mode",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "supported_currencies": [
      "string"
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

List connectable payment providers

GET

https://api.kontier.eu/v1

/payment-gateways/catalog

Returns every payment provider the API accepts: its slug and vendor name, whether it can actually be connected yet, the credential keys its config document takes, and - for an available provider - its capabilities (currencies, countries, direct-debit schemes, off-session and hosted-checkout support). Describes the product, not your organization; pair it with GET /payment-gateways for what you have connected. Requires the gateway.read permission.

List connectable payment providers › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List connectable payment providers › Responses

object · required

GET/payment-gateways/catalog

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

shell

Example Responses

{
  "data": {
    "providers": [
      {
        "available": true,
        "capabilities": {
          "charging_delay_seconds": 0,
          "refund_window_seconds": 0,
          "requires_mandate_for_dd": true,
          "supported_method_types": [
            "string"
          ],
          "supports_cards": true,
          "supports_countries": [
            "string"
          ],
          "supports_currencies": [
            "string"
          ],
          "supports_debits": [
            "string"
          ],
          "supports_hosted_checkout": true,
          "supports_off_session": true
        },
        "credential_fields": [
          {
            "key": "key",
            "required": true,
            "secret": true
          }
        ],
        "display_name": "display_name",
        "id": "id"
      }
    ]
  }
}

json

application/json

Get a payment gateway configuration

GET

https://api.kontier.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.kontier.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,
    "last_verified_at": "2024-08-25T15:00:00Z",
    "last_verify_detail": "last_verify_detail",
    "last_verify_ok": true,
    "metadata": {
      "key": {}
    },
    "mode": "mode",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "supported_currencies": [
      "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.kontier.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.kontier.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

supported_currencies

array | null

Update a payment gateway configuration › Responses

object · required

PATCH/payment-gateways/{id}

curl --request PATCH \
  --url https://api.kontier.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,
  "supported_currencies": [
    "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,
  "supported_currencies": [
    "string"
  ]
}

json

Example Responses

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

json

application/json

Check a payment gateway against the provider

POST

https://api.kontier.eu/v1

/payment-gateways/{id}/verify

Runs a read-only check against the provider to confirm the stored credential is still accepted, and returns {ok, checked_at, detail}. The result is recorded on the configuration so the integrations overview can report it later. It moves no money and changes no setting: a rejected credential is a 200 with ok=false, never a disabled gateway, because a provider outage must not take collections offline. Requires the gateway.read permission.

Check a payment gateway against the provider › path Parameters

id

string · uuid · required

Gateway config UUID

Check a payment gateway against the provider › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Check a payment gateway against the provider › Responses

object · required

Product Meter Bindings Payment Methods

Kontier Billing API

Payment Gateways

Endpointhttps://api.kontier.eu/v1

A payment gateway configuration connects Kontier 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.kontier.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

GET/payment-gateways

curl --request GET \
  --url https://api.kontier.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,
      "last_verified_at": "2024-08-25T15:00:00Z",
      "last_verify_detail": "last_verify_detail",
      "last_verify_ok": true,
      "metadata": {
        "key": {}
      },
      "mode": "mode",
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "provider": "provider",
      "supported_currencies": [
        "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.kontier.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 · required

provider

string · required

display_name

string

supported_currencies

array | null

Create a payment gateway configuration › Responses

Created

object · required

POST/payment-gateways

curl --request POST \
  --url https://api.kontier.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",
  "provider": "provider",
  "supported_currencies": [
    "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",
  "provider": "provider",
  "supported_currencies": [
    "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,
    "last_verified_at": "2024-08-25T15:00:00Z",
    "last_verify_detail": "last_verify_detail",
    "last_verify_ok": true,
    "metadata": {
      "key": {}
    },
    "mode": "mode",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "supported_currencies": [
      "string"
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
  }
}

json

application/json

List connectable payment providers

GET

https://api.kontier.eu/v1

/payment-gateways/catalog

List connectable payment providers › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List connectable payment providers › Responses

object · required

GET/payment-gateways/catalog

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

shell

Example Responses

{
  "data": {
    "providers": [
      {
        "available": true,
        "capabilities": {
          "charging_delay_seconds": 0,
          "refund_window_seconds": 0,
          "requires_mandate_for_dd": true,
          "supported_method_types": [
            "string"
          ],
          "supports_cards": true,
          "supports_countries": [
            "string"
          ],
          "supports_currencies": [
            "string"
          ],
          "supports_debits": [
            "string"
          ],
          "supports_hosted_checkout": true,
          "supports_off_session": true
        },
        "credential_fields": [
          {
            "key": "key",
            "required": true,
            "secret": true
          }
        ],
        "display_name": "display_name",
        "id": "id"
      }
    ]
  }
}

json

application/json

Get a payment gateway configuration

GET

https://api.kontier.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.kontier.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,
    "last_verified_at": "2024-08-25T15:00:00Z",
    "last_verify_detail": "last_verify_detail",
    "last_verify_ok": true,
    "metadata": {
      "key": {}
    },
    "mode": "mode",
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "supported_currencies": [
      "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.kontier.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.kontier.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

supported_currencies

array | null

Update a payment gateway configuration › Responses

object · required

PATCH/payment-gateways/{id}

curl --request PATCH \
  --url https://api.kontier.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,
  "supported_currencies": [
    "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,
  "supported_currencies": [
    "string"
  ]
}

json

Example Responses

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

json

application/json

Check a payment gateway against the provider

POST

https://api.kontier.eu/v1

/payment-gateways/{id}/verify

Check a payment gateway against the provider › path Parameters

id

string · uuid · required

Gateway config UUID

Check a payment gateway against the provider › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Check a payment gateway against the provider › Responses

object · required

Product Meter Bindings Payment Methods