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

Get the Kontier Payments account

GET

https://api.kontier.eu/v1

/kontier-payments

Kontier Payments (powered by Mollie) for this workspace: whether it can be set up here, whether an account is connected, and — when it is — the Mollie account as Mollie reports it now: verification status, what the owner still has to do (with deep links into Mollie), the website profile payments are made on, and its payment methods. A sandbox workspace connects in Mollie test mode, a live workspace in live mode. Requires gateway.read.

Required scope: gateway.read (Read payment gateway config).

Get the Kontier Payments account › 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.

Get the Kontier Payments account › Responses

object · required

GET/kontier-payments

curl --request GET \
  --url https://api.kontier.eu/v1/kontier-payments

shell

Example Responses

{
  "data": {
    "account": {
      "can_receive_payouts": true,
      "can_take_payments": true,
      "country": "country",
      "dashboard_url": "dashboard_url",
      "email": "email",
      "name": "name",
      "onboarding_status": "needs-data",
      "onboarding_url": "onboarding_url",
      "organization_id": "organization_id"
    },
    "available": true,
    "capabilities": [
      {
        "name": "name",
        "reason": "reason",
        "status": "status"
      }
    ],
    "connected": true,
    "gateway": {
      "enabled": true,
      "id": "57df6eb8-26d6-52a7-a1f3-e026df60a448",
      "is_default": true,
      "mode": "test"
    },
    "methods": [
      {
        "description": "description",
        "enabled": true,
        "id": "id",
        "image": "image",
        "status": "status"
      }
    ],
    "problem": "problem",
    "profile": {
      "id": "id",
      "name": "name",
      "review": "review",
      "status": "status",
      "website": "website"
    },
    "profiles": [
      {
        "id": "id",
        "name": "name",
        "review": "review",
        "status": "status",
        "website": "website"
      }
    ],
    "requirements": [
      {
        "capability": "capability",
        "due_date": "due_date",
        "id": "id",
        "status": "status",
        "url": "url"
      }
    ],
    "testmode": true
  }
}

json

application/json

Disconnect the Kontier Payments account

DELETE

https://api.kontier.eu/v1

/kontier-payments

Revokes Kontier's access at Mollie and removes the connection. The Mollie account itself, its balance and its payouts are untouched: it belongs to the customer. Payments already made keep their history. Requires gateway.manage.

Required scope: gateway.manage (Manage payment gateways).

Disconnect the Kontier Payments account › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Disconnect the Kontier Payments account › Responses

object · required

Open or connect a Kontier Payments account

POST

https://api.kontier.eu/v1

/kontier-payments/connect

Answers the Mollie page to send the operator's browser to: Kontier's co-branded sign-up for a new account (intent=create) or the login for an existing Mollie account (intent=connect). Mollie redirects back to Kontier, which stores the connection and lands the operator on the Kontier Payments page. Requires gateway.manage.

Required scope: gateway.manage (Manage payment gateways).

Open or connect a Kontier Payments account › 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.

Open or connect a Kontier Payments account › Request Body

intent

string · enum · required

create opens a new Mollie account (co-branded sign-up); connect links an existing one (login).

Enum values:

create

connect

return_to

string · maxLength: 512

Dashboard path to land on afterwards; defaults to Kontier Payments' page in the integrations hub.

Open or connect a Kontier Payments account › Responses

object · required

Switch a payment method on or off

PUT

https://api.kontier.eu/v1

/kontier-payments/methods/{method}

Switches a Mollie payment method on or off for the chosen website profile. Switching one on may answer pending-review or pending-external: Mollie reviews some methods, and some need a step at the method's own provider first. Requires gateway.manage.

Required scope: gateway.manage (Manage payment gateways).

Switch a payment method on or off › path Parameters

method

string · pattern: ^[a-z0-9]{2,32}$ · required

Mollie's method id, e.g. ideal, creditcard, bancontact, directdebit.

Switch a payment method on or off › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Switch a payment method on or off › Request Body

enabled

boolean · required

Switch the method on (true) or off (false) for the profile.

Switch a payment method on or off › Responses

object · required

Choose the website profile payments are made on

PUT

https://api.kontier.eu/v1

/kontier-payments/profile

Makes one of the connected account's website profiles the one Kontier charges on, and answers the account page. Requires gateway.manage.

Required scope: gateway.manage (Manage payment gateways).

Choose the website profile payments are made on › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Choose the website profile payments are made on › Request Body

profile_id

string · minLength: 1 · maxLength: 64 · required

One of the connected account's website profiles (pfl_…).

Choose the website profile payments are made on › Responses

object · required

PUT/kontier-payments/profile

curl --request PUT \
  --url https://api.kontier.eu/v1/kontier-payments/profile \
  --header 'Content-Type: application/json' \
  --data '
{
  "profile_id": "profile_id"
}
'

shell

Example Request Body

{
  "profile_id": "profile_id"
}

json

Example Responses

{
  "data": {
    "account": {
      "can_receive_payouts": true,
      "can_take_payments": true,
      "country": "country",
      "dashboard_url": "dashboard_url",
      "email": "email",
      "name": "name",
      "onboarding_status": "needs-data",
      "onboarding_url": "onboarding_url",
      "organization_id": "organization_id"
    },
    "available": true,
    "capabilities": [
      {
        "name": "name",
        "reason": "reason",
        "status": "status"
      }
    ],
    "connected": true,
    "gateway": {
      "enabled": true,
      "id": "57df6eb8-26d6-52a7-a1f3-e026df60a448",
      "is_default": true,
      "mode": "test"
    },
    "methods": [
      {
        "description": "description",
        "enabled": true,
        "id": "id",
        "image": "image",
        "status": "status"
      }
    ],
    "problem": "problem",
    "profile": {
      "id": "id",
      "name": "name",
      "review": "review",
      "status": "status",
      "website": "website"
    },
    "profiles": [
      {
        "id": "id",
        "name": "name",
        "review": "review",
        "status": "status",
        "website": "website"
      }
    ],
    "requirements": [
      {
        "capability": "capability",
        "due_date": "due_date",
        "id": "id",
        "status": "status",
        "url": "url"
      }
    ],
    "testmode": true
  }
}

json

application/json

Create the website profile payments are made on

POST

https://api.kontier.eu/v1

/kontier-payments/profiles

Creates a website profile on the connected Mollie account (Mollie needs the shop's name, website, e-mail and phone) and makes it the profile Kontier charges on. Requires gateway.manage.

Required scope: gateway.manage (Manage payment gateways).

Create the website profile payments are made on › Headers

Idempotency-Key

string · required

Reuse the same key to retry safely; Mollie creates the profile once.

X-Workspace-Id

string

Workspace UUID or slug.

Create the website profile payments are made on › Request Body

email

string · email · minLength: 3 · maxLength: 255 · required

name

string · minLength: 1 · maxLength: 255 · required

The shop or brand name customers see.

phone

string · minLength: 3 · maxLength: 64 · required

The business phone number, international format (+49…).

website

string · minLength: 1 · maxLength: 255 · required

The website payments are taken for (https://…).

Create the website profile payments are made on › Responses

Created

object · required

List payment gateways

GET

https://api.kontier.eu/v1

/payment-gateways

Returns all payment gateways of the organization, on one page. Sensitive config fields are masked. Requires the gateway.read permission.

Required scope: gateway.read (Read payment gateway config).

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": {},
      "created_at": "2024-08-25T15:00:00Z",
      "display_name": "display_name",
      "id": "43a01a46-1e13-59f3-9836-55198fe37b0b",
      "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": "test",
      "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
      "provider": "provider",
      "status": "active",
      "supported_currencies": [
        "string"
      ],
      "updated_at": "2024-08-25T15:00:00Z",
      "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Connect a payment gateway

POST

https://api.kontier.eu/v1

/payment-gateways

Stores a provider credential as a new payment gateway, active, and returns it with the credential masked. mode is read from the credential. Requires the gateway.manage permission: the gateway holds the organization's live provider secret.

Required scope: gateway.manage (Manage payment gateways).

Connect a payment gateway › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Connect a payment gateway › Request Body

config

required

provider

string · required

display_name

string

supported_currencies

array | null

Connect a payment gateway › 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": {},
  "display_name": "display_name",
  "provider": "provider",
  "supported_currencies": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "config": {},
  "display_name": "display_name",
  "provider": "provider",
  "supported_currencies": [
    "string"
  ]
}

json

Example Responses

{
  "data": {
    "config": {},
    "created_at": "2024-08-25T15:00:00Z",
    "display_name": "display_name",
    "id": "43a01a46-1e13-59f3-9836-55198fe37b0b",
    "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": "test",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "provider": "provider",
    "status": "active",
    "supported_currencies": [
      "string"
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
  }
}

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. From 2026-11-30 this list answers {data: [...], pagination}: the entries move from data.providers to data.

Required scope: gateway.read (Read payment gateway config).

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

GET

https://api.kontier.eu/v1

/payment-gateways/{id}

Returns one payment gateway. Sensitive config fields are masked. Requires the gateway.read permission.

Required scope: gateway.read (Read payment gateway config).

Get a payment gateway › path Parameters

id

string · uuid · required

Gateway config UUID

Get a payment gateway › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a payment gateway › Responses

object · required

GET/payment-gateways/{id}

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

shell

Example Responses

{
  "data": {
    "config": {},
    "created_at": "2024-08-25T15:00:00Z",
    "display_name": "display_name",
    "id": "43a01a46-1e13-59f3-9836-55198fe37b0b",
    "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": "test",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "provider": "provider",
    "status": "active",
    "supported_currencies": [
      "string"
    ],
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
  }
}

json

application/json

Delete a payment gateway

DELETE

https://api.kontier.eu/v1

/payment-gateways/{id}

Requires the gateway.manage permission: the gateway holds the organization's live provider secret. Refused with 409 (PAYMENTS_IN_FLIGHT) while a payment through the gateway's provider is still in flight: the provider reports it only to this gateway's webhook. Disable the gateway instead (status disabled) until they have settled.

Required scope: gateway.manage (Manage payment gateways).

Delete a payment gateway › path Parameters

id

string · uuid · required

Gateway config UUID

Delete a payment gateway › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a payment gateway › Responses

No Content

No data returned

Update a payment gateway

PATCH

https://api.kontier.eu/v1

/payment-gateways/{id}

Merge-patch update: only supplied fields change, and the gateway is returned with the credential masked. status disables the gateway (no payments go through it) or makes it active again. A new credential clears the last check and sets mode from the credential. Requires the gateway.manage permission: the gateway holds the organization's live provider secret.

Required scope: gateway.manage (Manage payment gateways).

Update a payment gateway › path Parameters

id

string · uuid · required

Gateway config UUID

Update a payment gateway › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a payment gateway › Request Body

config

display_name

string · maxLength: 255

The name the gateway is shown under.

is_default

boolean

When true, payments go through this gateway when more than one could take them.

status

string · enum

active: the gateway takes payments; disabled: it takes none until it is active again.

Enum values:

active

disabled

supported_currencies

array | null

Update a payment gateway › 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": {},
  "display_name": "display_name",
  "is_default": true,
  "is_enabled": true,
  "status": "active",
  "supported_currencies": [
    "string"
  ]
}
'

shell

Example Request Body

{
  "config": {},
  "display_name": "display_name",
  "is_default": true,
  "is_enabled": true,
  "status": "active",
  "supported_currencies": [
    "string"
  ]
}

json

Example Responses

{
  "data": {
    "config": {},
    "created_at": "2024-08-25T15:00:00Z",
    "display_name": "display_name",
    "id": "90a4f7ae-29c8-57b9-85e6-3e6e5bb9e24a",
    "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": "test",
    "organization_id": "24d3775d-4115-5ce8-8a24-75b73041d2ca",
    "provider": "provider",
    "status": "active",
    "supported_currencies": [
      "string"
    ],
    "updated": true,
    "updated_at": "2024-08-25T15:00:00Z",
    "workspace_id": "4a82f969-6228-5ab1-8d01-b41ed73ee6ca"
  }
}

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.

Required scope: gateway.read (Read payment gateway config).

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