Dibito REST API (1.1)

The Dibito REST API provides services to submit, verify and deliver eBills. The API is designed to be used by biller integrations.

Product Website

https://www.dibito.ch

API Key

This API requires an API key to be passed in the `X-API-Key` header.
Generate your API key in the Dibito application under "Dibito -> API Keys".

Further Informations

Consult our documentation for futher informations about creating and handling eBills.
Download OpenAPI description
api-docs.json
api-docs.yaml
Overview
URL

https://www.codeblock.ch

Codeblock GmbH

contact@codeblock.ch

Languages
Servers
Generated server url

https://app.dibito.ch/

00 Examples

Operations

10 Business Cases

Operations

20 Bill Recipients

Operations

21 Bill-Recipient Subscriptions

Operations

30 Events

Operations

31 SIX Events

Operations

40 Webhook Management

Operations

90 PDF

Operations

98 Health Check

Operations

99 Authentication

Operations

webhooks

Webhooks

Bill Recipient Email Address Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
externalIdstring[ 0 .. 36 ] charactersEVID[0-9A-Z]{32}required

external event ID

Example: "EVID82A65938766547EBBBA39BA6F7B07F24"
businessCaseIdinteger(int32)
businessCaseExternalIdstring[ 0 .. 36 ] charactersBCID[0-9A-Z]{32}required

business case ID

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
oldEmailAddressstring[ 1 .. 256 ] characters

the old email address of the bill recipient which has been used in the submission of a business case

Example: "peter@muster.ch"
newEmailAddressstring[ 1 .. 256 ] characters

the new email address of the bill recipient

Example: "peter_new@muster.ch"
No request payload

Responses

Event received

Bill Recipient Subscription Status Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
externalIdstring[ 0 .. 36 ] charactersEVID[0-9A-Z]{32}required

Event ID

Example: "EVID82A65938766547EBBBA39BA6F7B07F24"
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
billRecipientobject(WebhookBillRecipient)required
billRecipient.​emailAddressstring[ 1 .. 256 ] characters

email address of the bill recipient

Example: "peter@muster.ch"
billRecipient.​billRecipientIdstring[ 1 .. 17 ] characters([0-9])*required

ID of the bill recipient

Example: 41010560425610180
billRecipient.​enterpriseIdentificationNumberstring[ 0 .. 12 ] charactersCHE[0-9]{9}

Swiss enterprise identification number (UID) without dashes, dots or extension. Note that this has to contain the swiss enterprise identification number (UID) from the commercial register (Handelsregister) which may be different from the VAT UID (Mehrwertsteuer UID).

Example: "CHE123456789"
billRecipient.​typestringrequired

the type of the bill recipient

Enum"PRIVATE""COMPANY"
billRecipient.​namestring[ 1 .. 70 ] charactersrequired

last name, if private bill recipient company name, if company bill recipient

Example: "for private bill recipient: Muster, for company name: Muster AG"
billRecipient.​firstNamestring[ 0 .. 35 ] characters

first name, if private bill recipient empty, if company bill recipient

Example: "Peter"
billRecipient.​correspondenceLanguagestring[ 1 .. 3 ] charactersrequired

language for correspondence with this bill recipient ISO-639-2/B

Example: "ger"
billRecipient.​addressobject(WebhookRecipientAddress)required

The address of a bill recipient.

billRecipient.​address.​streetNamestring[ 1 .. 70 ] charactersrequired

street name

Example: "Neustadtstrasse"
billRecipient.​address.​postalCodestring[ 1 .. 9 ] charactersrequired

postal code

Example: 6025
billRecipient.​address.​citystring[ 1 .. 35 ] charactersrequired

city name

Example: "Neudorf"
billRecipient.​address.​countryCodestring[ 0 .. 2 ] characters[A-Z]{2}required

in format ISO 3166-1 alpha 2

Example: "CH"
accountNumberstring[ 0 .. 21 ] characters

Account number of the biller (e.g. iban), if provided from the financial institution

referenceStructuredstring[ 0 .. 27 ] characters([a-zA-Z0-9])*

QR or creditor reference number, if provided from the financial institution.

Example: 1.2345612345678902e+26
billRecipientSubscriptionFormFieldsArray of objects(WebhookBillRecipientSubscriptionFormBillRecipientSubscriptionFormFields)
newStatusstring

the new status of the bill recipient subscription, see "Subscriptions and subscription cancellations" for further information

Enum"INACTIVE""REQUESTED""ACTIVE"
No request payload

Responses

Event received

Business Case Status Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
externalIdstring[ 0 .. 36 ] charactersEVID[0-9A-Z]{32}required

External ID

Example: "EVID82A65938766547EBBBA39BA6F7B07F24"
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
businessCaseExternalIdstring[ 0 .. 36 ] charactersBCID[0-9A-Z]{32}

Business Case ID

Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"
businessCaseIdinteger(int32)

Business case ID

Example: 12345
newStatusstring

the new status of the business case

Enum"OPEN""APPROVED""REJECTED""COMPLETED""CHARGEBACK_INITIATED"
approvedAmountobject(WebhookApprovalAmountWithCurrency)

Amount provided by status changed events if the new status is APPROVED. The value is always greater than zero.

externalDonationPurposeIdstring

optional field only to be used for donation inquiries to represent a potential selection of a donation purpose by the bill recipient, note the connection to the field externalDonationPurposeId from eBill business case specification

No request payload

Responses

Event received

Instalment Status Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
externalIdstring[ 0 .. 36 ] charactersEVID[0-9A-Z]{32}required

Event ID

Example: "EVID82A65938766547EBBBA39BA6F7B07F24"
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
businessCaseIdinteger(int32)

Business Case ID

Example: 12345
businessCaseExternalIdstring
paymentByInstalmentsIdinteger(int32)

Payment by instalments ID

Example: 12345
paymentByInstalmentsExternalIdstring[ 1 .. 36 ] characters

external ID of the respective paymentByInstalment

Example: "298031-2999"
instalmentIdinteger(int32)

Instalment ID

Example: 12345
instalmentExternalIdstring[ 1 .. 36 ] characters

external ID of the instalment

Example: "298031-2999-ACX01"
newStatusstring

the new status of the instalment

Enum"OPEN""APPROVED""REJECTED""COMPLETED""CHARGEBACK_INITIATED"
approvedAmountobject(WebhookApprovalAmountWithCurrency)

Amount provided by status changed events if the new status is APPROVED. The value is always greater than zero.

No request payload

Responses

Event received

Processing Status Changed EventWebhook

Request

Security
X-API-Key
Body*/*
idinteger(int32)required

Event ID

Example: 12345
timestampstring(date-time)required

timestamp of the event

Example: "2015-01-01T10:00Z"
businessCaseIdinteger(int32)

Business Case ID

newStatusstring
Enum"OPEN""INVALID""PROCESSING""FAILED""DELIVERED""DONE"
No request payload

Responses

Event received

endpoint-controller

Operations