Payment Methods

Endpointhttps://api.kontorion.eu/v1

A payment method is a stored instrument (credit card, bank account, direct debit mandate) that a customer uses to pay invoices. Payment methods are tokenized through the configured payment gateway - Kontorion never stores raw card numbers or bank details.

Each customer can have multiple payment methods. One is marked as is_default and is used automatically when invoices are finalized.

List payment methods

GET

https://api.kontorion.eu/v1

/payment-methods

Returns payment methods for the org. Pass ?customer_id= to scope to one customer; omit to page through every payment method across the org. Cursor-paginated (default 50, max 200 per page).

List payment methods › query Parameters

customer_id

string

Filter by customer UUID

include_removed

string

Include soft-deleted methods (default false)

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

List payment methods › 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 methods › Responses

array | null · required

object · required

GET/payment-methods

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

shell

Example Responses

{
  "data": [
    {
      "account_last4": "account_last4",
      "bank_name": "bank_name",
      "created_at": "2024-08-25T15:00:00Z",
      "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "display_brand": "display_brand",
      "exp_month": 0,
      "exp_year": 0,
      "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "is_default": true,
      "last4": "last4",
      "metadata": {
        "key": {}
      },
      "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
      "provider": "provider",
      "provider_id": "provider_id",
      "status": "status",
      "type": "type",
      "updated_at": "2024-08-25T15:00:00Z"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Create a payment method

POST

https://api.kontorion.eu/v1

/payment-methods

Creates a new payment method. customer_id is supplied in the request body.

Create a payment method › 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 method › Request Body

customer_id

string · uuid

Customer to attach the payment method to. Required.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

is_default

boolean

When true, make this the customer's default payment method, demoting any prior default.

object

Free-form key/value metadata for caller use; not interpreted by billing.

provider

string · maxLength: 255

Payment provider holding this method, e.g. "stripe" or "gocardless". Required.

provider_id

string · maxLength: 255

Provider's own identifier for the stored method; omit when not tracked externally.

type

string

Method type: CREDIT_CARD, BANK_ACCOUNT, SEPA_DIRECT_DEBIT, SEPA_DIRECT_DEBIT_B2B, ACH_BUSINESS, PAYPAL, or EXTERNAL. Required; the B2B/ACH types require a BUSINESS customer.

Create a payment method › Responses

Created

object · required

POST/payment-methods

curl --request POST \
  --url https://api.kontorion.eu/v1/payment-methods \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <string>' \
  --data '
{
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "is_default": true,
  "metadata": {
    "key": {}
  },
  "provider": "provider",
  "provider_id": "provider_id",
  "type": "type"
}
'

shell

Example Request Body

{
  "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
  "is_default": true,
  "metadata": {
    "key": {}
  },
  "provider": "provider",
  "provider_id": "provider_id",
  "type": "type"
}

json

Example Responses

{
  "data": {
    "account_last4": "account_last4",
    "bank_name": "bank_name",
    "created_at": "2024-08-25T15:00:00Z",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "display_brand": "display_brand",
    "exp_month": 0,
    "exp_year": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_default": true,
    "last4": "last4",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "provider_id": "provider_id",
    "status": "status",
    "type": "type",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Get a payment method

GET

https://api.kontorion.eu/v1

/payment-methods/{id}

Returns a single payment method. Soft-deleted (removed) methods are not served and respond 404.

Get a payment method › path Parameters

id

string · uuid · required

Payment method UUID

Get a payment method › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a payment method › Responses

object · required

GET/payment-methods/{id}

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

shell

Example Responses

{
  "data": {
    "account_last4": "account_last4",
    "bank_name": "bank_name",
    "created_at": "2024-08-25T15:00:00Z",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "display_brand": "display_brand",
    "exp_month": 0,
    "exp_year": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_default": true,
    "last4": "last4",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "provider_id": "provider_id",
    "status": "status",
    "type": "type",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Delete a payment method

DELETE

https://api.kontorion.eu/v1

/payment-methods/{id}

Soft-deletes a payment method by ID.

Delete a payment method › path Parameters

id

string · uuid · required

Payment method UUID

Delete a payment method › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a payment method › Responses

No Content

No data returned

Update a payment method

PATCH

https://api.kontorion.eu/v1

/payment-methods/{id}

Merge-patch update: only supplied fields (provider, provider_id, is_default, status, metadata) change. Setting is_default=true atomically demotes the customer's previous default method.

Update a payment method › path Parameters

id

string · uuid · required

Payment method UUID

Update a payment method › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a payment method › Request Body

is_default

boolean

When true, promote this method to the customer's default; omit to leave unchanged.

object

Replacement free-form key/value metadata; omit to leave unchanged.

provider

string · maxLength: 255

New payment provider; omit to leave unchanged.

provider_id

string · maxLength: 255

New provider-side identifier; omit to leave unchanged.

status

string

New lifecycle status: active, expired, or removed; omit to leave unchanged.

Update a payment method › Responses

object · required

PATCH/payment-methods/{id}

curl --request PATCH \
  --url https://api.kontorion.eu/v1/payment-methods/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "is_default": true,
  "metadata": {
    "key": {}
  },
  "provider": "provider",
  "provider_id": "provider_id",
  "status": "status"
}
'

shell

Example Request Body

{
  "is_default": true,
  "metadata": {
    "key": {}
  },
  "provider": "provider",
  "provider_id": "provider_id",
  "status": "status"
}

json

Example Responses

{
  "data": {
    "account_last4": "account_last4",
    "bank_name": "bank_name",
    "created_at": "2024-08-25T15:00:00Z",
    "customer_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "display_brand": "display_brand",
    "exp_month": 0,
    "exp_year": 0,
    "id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "is_default": true,
    "last4": "last4",
    "metadata": {
      "key": {}
    },
    "organization_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
    "provider": "provider",
    "provider_id": "provider_id",
    "status": "status",
    "type": "type",
    "updated_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Payment Gateways Tax Rules

List payment methods

GET

https://api.kontorion.eu/v1

/payment-methods

Returns payment methods for the org. Pass ?customer_id= to scope to one customer; omit to page through every payment method across the org. Cursor-paginated (default 50, max 200 per page).

List payment methods › query Parameters

customer_id

string

Filter by customer UUID

include_removed

string

Include soft-deleted methods (default false)

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

List payment methods › Headers

X-Workspace-Id

string

Workspace UUID or slug.

List payment methods › Responses

array | null · required

object · required

Create a payment method

POST

https://api.kontorion.eu/v1

/payment-methods

Creates a new payment method. customer_id is supplied in the request body.

Create a payment method › Headers

Idempotency-Key

string · required

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

X-Workspace-Id

string

Workspace UUID or slug.

Create a payment method › Request Body

customer_id

string · uuid

Customer to attach the payment method to. Required.

Example: 0f8fad5b-d9cb-469f-a165-70867728950e

is_default

boolean

When true, make this the customer's default payment method, demoting any prior default.

object

Free-form key/value metadata for caller use; not interpreted by billing.

provider

string · maxLength: 255

Payment provider holding this method, e.g. "stripe" or "gocardless". Required.

provider_id

string · maxLength: 255

Provider's own identifier for the stored method; omit when not tracked externally.

type

string

Method type: CREDIT_CARD, BANK_ACCOUNT, SEPA_DIRECT_DEBIT, SEPA_DIRECT_DEBIT_B2B, ACH_BUSINESS, PAYPAL, or EXTERNAL. Required; the B2B/ACH types require a BUSINESS customer.

Create a payment method › Responses

Created

object · required

Get a payment method

GET

https://api.kontorion.eu/v1

/payment-methods/{id}

Returns a single payment method. Soft-deleted (removed) methods are not served and respond 404.

Get a payment method › path Parameters

id

string · uuid · required

Payment method UUID

Get a payment method › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Get a payment method › Responses

object · required

Delete a payment method

DELETE

https://api.kontorion.eu/v1

/payment-methods/{id}

Soft-deletes a payment method by ID.

Delete a payment method › path Parameters

id

string · uuid · required

Payment method UUID

Delete a payment method › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Delete a payment method › Responses

No Content

No data returned

Update a payment method

PATCH

https://api.kontorion.eu/v1

/payment-methods/{id}

Merge-patch update: only supplied fields (provider, provider_id, is_default, status, metadata) change. Setting is_default=true atomically demotes the customer's previous default method.

Update a payment method › path Parameters

id

string · uuid · required

Payment method UUID

Update a payment method › Headers

X-Workspace-Id

string

Workspace UUID or slug.

Update a payment method › Request Body

is_default

boolean

When true, promote this method to the customer's default; omit to leave unchanged.

object

Replacement free-form key/value metadata; omit to leave unchanged.

provider

string · maxLength: 255

New payment provider; omit to leave unchanged.

provider_id

string · maxLength: 255

New provider-side identifier; omit to leave unchanged.

status

string

New lifecycle status: active, expired, or removed; omit to leave unchanged.

Update a payment method › Responses

object · required