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 - Kontier 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.
Get the form for a new SEPA mandate
The form a new SEPA Direct Debit mandate of the customer is given against: whether this organization collects by SEPA at all and on which rail, the creditor and creditor identifier the mandate names, the schemes this customer may sign (B2B only for a business customer, and only on your own SEPA rail), a fresh reference, and the mandate text in the requested language with its text_version. An application that collects the mandate itself shows text unchanged and sends it back with POST /customers/{id}/sepa-mandates (channel api). offered is false when this organization does not collect by SEPA.
Required scope: payment.read (Read payments).
path Parameters
idThe customer.
query Parameters
schemeThe scheme offer.text is for; CORE when omitted.
localeThe language of offer.text (de, en, fr, es, it, pt, nl, ja); your request's language when omitted. Show this text unchanged when your application collects the mandate (channel api).
Headers
X-Workspace-IdSelects 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 form for a new SEPA mandate › Responses
OK
List a customer's SEPA mandates
Every SEPA Direct Debit mandate of the customer, newest first, active, pending, failed, replaced and revoked alike, with the IBAN masked. offer is the form a new mandate is given against, which GET /customers/{id}/sepa-mandate-offer now answers on its own; scheme and locale choose its text. From 2026-11-30 this list answers {data: [...], pagination}: the mandates move from data.mandates to data, and offer is no longer sent.
Required scope: payment.read (Read payments).
path Parameters
idThe customer.
query Parameters
includeExtra data to add to the response: events. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
schemeThe scheme offer.text is for; CORE when omitted.
localeThe language of offer.text (de, en, fr, es, it, pt, nl, ja); your request's language when omitted. Show this text unchanged when your application collects the mandate (channel api).
Headers
X-Workspace-IdSelects 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 a customer's SEPA mandates › Responses
OK
Record a SEPA mandate
Records a mandate the customer gave outside Kontier's own pages.
channel operator (the default): a form the customer signed on paper or elsewhere, with the date on the form (signed_on) and, ideally, its scan as evidence (document_id). Kontier never saw the wording, so it stores none and the rulebook's 14-day pre-notification applies.
channel api: the customer accepted the mandate online in your own application. Read the offer (GET /customers/{id}/sepa-mandates?locale=…), show offer.text unchanged with its creditor and reference, and send back the reference, locale, text_version, the SHA-256 of the text you showed (text_sha256), when the customer accepted (accepted_at, at most 24 hours ago) and the IP address and user agent they accepted from. Kontier checks these as its own portal does and stores its text word for word. With confirmed you state that the customer was shown that text and accepted it: as the creditor (or the seller a payment provider collects for) you answer for the consent you collected.
A new mandate replaces the customer's mandate of the same scheme and becomes their default payment method when they have none, or when it replaces their default. Announced as sepa_mandate.created (and sepa_mandate.activated when it is collectable at once).
Required scope: payment.write (Manage payment methods).
path Parameters
idThe customer.
query Parameters
includeExtra data to add to the response: events. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
Headers
Idempotency-KeyUnique 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-IdSelects 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.
Record a SEPA mandate › Request Body
account_holderThe account holder as the bank knows them.
confirmedoperator: you confirm the customer signed a mandate naming this creditor and reference. api: you confirm the customer was shown the offer's text unchanged and accepted it; as the creditor (or the seller a provider collects for) you answer for that consent.
ibanThe account to be debited; spaces are ignored. EU/EEA accounts only.
accepted_atapi: when the customer accepted, at most 24 hours ago and not in the future (SEPA_MANDATE_ACCEPTED_AT_INVALID).
accepted_byapi: who accepted, as your application knows them (e.g. their email), kept as evidence.
bicOptional; the bank is found from the IBAN.
channeloperator (the default): a form the customer signed, recorded with signed_on and ideally its scan. api: the customer accepted the mandate text online in your own application just now; send locale, reference, text_version, text_sha256, accepted_at, ip_address and user_agent.
document_idoperator: the uploaded scan of the signed form, kept as evidence.
ip_addressapi: the IP address the customer accepted from (SEPA_MANDATE_EVIDENCE_MISSING when absent).
localeapi: the language of the text you showed (de, en, fr, es, it, pt, nl, ja); the stored text is Kontier's text in it.
referenceoperator: the reference on the signed form, a fresh one when omitted. api: required, the offer's reference the text you showed named.
schemeCORE when omitted. B2B needs a business customer and your own SEPA rail with B2B enabled; a payment provider's rail collects CORE only.
signed_onoperator: the date on the signed form, required, not in the future. api: ignored; the mandate is dated by accepted_at.
text_sha256api: SHA-256 (hex) of offer.text exactly as you showed it, UTF-8. A text that is not Kontier's for this creditor, reference, scheme and locale is refused (SEPA_MANDATE_TEXT_CHANGED).
text_versionapi: the offer's text_version the customer read. A text that changed since is refused (SEPA_MANDATE_TEXT_CHANGED).
user_agentapi: the user agent of the customer's browser (SEPA_MANDATE_EVIDENCE_MISSING when absent).
Record a SEPA mandate › Responses
Created
List payment methods
Returns payment methods for the org. Pass ?customer_id=
Required scope: payment.read (Read payments).
query Parameters
customer_idFilter by customer UUID
include_removedInclude soft-deleted methods (default false)
limitPage size (default 50, max 200)
cursorOpaque 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.
Headers
X-Workspace-IdSelects 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
OK
Create a payment method
Creates a new payment method for the customer named by customer_id, and returns it. is_default_for_auto_pay makes it the method that pays the customer's invoices automatically.
Required scope: payment.write (Manage payment methods).
Headers
Idempotency-KeyUnique 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-IdSelects 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.
Create a payment method › Request Body
customer_idCustomer to attach the payment method to. Required.
providerPayment provider holding this method, e.g. "stripe" or "gocardless". Required.
typeMethod 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.
is_default_for_auto_payWhen true, make this the method that pays the customer's invoices automatically, replacing the previous one.
Free-form key/value metadata for caller use; not interpreted by billing.
provider_idProvider's own identifier for the stored method; omit when not tracked externally.
is_defaultWhen true, make this the customer's default payment method, demoting any prior default. Deprecated: use is_default_for_auto_pay instead. Removed on 2026-11-30.
Create a payment method › Responses
Created
Get a payment method
Returns a single payment method. Soft-deleted (removed) methods are not served and respond 404.
Required scope: payment.read (Read payments).
path Parameters
idPayment method UUID
Headers
X-Workspace-IdSelects 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 a payment method › Responses
OK
Delete a payment method
Soft-deletes a payment method by ID.
Required scope: payment.write (Manage payment methods).
path Parameters
idPayment method UUID
Headers
X-Workspace-IdSelects 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.
Delete a payment method › Responses
No Content
Update a payment method
Merge-patch update: only supplied fields (provider, provider_id, is_default_for_auto_pay, status, metadata) change, and the method is returned. Setting is_default_for_auto_pay=true takes the auto-pay slot from the customer's previous method in the same step.
Required scope: payment.write (Manage payment methods).
path Parameters
idPayment method UUID
Headers
X-Workspace-IdSelects 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.
Update a payment method › Request Body
is_default_for_auto_payWhen true, make this the method that pays the customer's invoices automatically, replacing the previous one; omit to leave unchanged.
Replacement free-form key/value metadata; omit to leave unchanged.
providerNew payment provider; omit to leave unchanged.
provider_idNew provider-side identifier; omit to leave unchanged.
statusNew lifecycle status: active, expired, or removed; omit to leave unchanged.
is_defaultWhen true, promote this method to the customer's default; omit to leave unchanged. Deprecated: use is_default_for_auto_pay instead. Removed on 2026-11-30.
Update a payment method › Responses
OK
Get a SEPA mandate
One mandate, IBAN masked. include=events adds its history oldest first: signed, activated, replaced, revoked, failed, PDF downloads.
Required scope: payment.read (Read payments).
path Parameters
mandate_idThe mandate.
query Parameters
includeExtra data to add to the response: events. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400. events is sent without being asked until 2026-11-30; after that date it is sent only when named here.
Headers
X-Workspace-IdSelects 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 a SEPA mandate › Responses
OK
Download a SEPA mandate as PDF
The mandate as a PDF: the text exactly as the customer accepted it, the creditor, reference, account and signature details, its labels in your request's language. A mandate recorded from a paper form says so; the signed form is the mandate. The download is recorded in the mandate's history.
Required scope: payment.read (Read payments).
path Parameters
mandate_idThe mandate.
Headers
X-Workspace-IdSelects 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.
Download a SEPA mandate as PDF › Responses
The mandate PDF.
Revoke a SEPA mandate
Ends the mandate: nothing is collected on it afterwards, and its payment method is removed (the auto-pay default passes to the customer's newest other method). Debits already announced to the customer may still be collected. Revoking a revoked mandate changes nothing. Announced as sepa_mandate.revoked.
Required scope: payment.write (Manage payment methods).
path Parameters
mandate_idThe mandate.
query Parameters
includeExtra data to add to the response: events. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
Headers
Idempotency-KeyUnique 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-IdSelects 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.
Revoke a SEPA mandate › Responses
OK
Set a failed SEPA mandate up again
For a mandate collected by a payment provider (Kontier Payments, Mollie, Stripe) whose setup there failed: it is pending again and the provider is asked once more. Refused (409 SEPA_MANDATE_NOT_RETRYABLE) for any other mandate, and for one a newer mandate of the customer has replaced.
Required scope: payment.write (Manage payment methods).
path Parameters
mandate_idquery Parameters
includeExtra data to add to the response: events. Send a comma-separated list or repeat the parameter. An unknown name is refused with 400.
Headers
Idempotency-KeyUnique 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-IdSelects 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.
Set a failed SEPA mandate up again › Responses
OK