1. Overview

The application programming interface for network partners (Network Partner API) allows communication with the eBill infrastructure on the biller side. It is therefore the central entry point for billers.

The eBill service comprises of electronic bills, reminders, credit notes, advices and donation inquiries which are summarized under the term business case. Business cases are delivered from network partners to the SIX eBill infrastructure and can be received online by bill recipients. The eBill infrastructure is the runtime system at SIX. Core functionality is the management of system participants and the processing of business cases. It consists of software and hardware needed to provide the entire service.

Documentation of the Network Partner API comprises of three parts:

Handbook for network partners
Business-level description targeting product and IT management.

Network Partner API documentation
Technical description targeting IT architects and developers.

OpenAPI Specification
Technical specification of the interface for developers and code generators.

1.1. General Note

SIX reserves the right to amend this documentation as required within the scope of the applicable contractual conditions.

All rights are reserved with respect to this documentation, including with regard to photocopying and storage on electronic media as well as translation into foreign languages.

This documentation has been compiled with the greatest care, but may nevertheless contain errors or inaccuracies. SIX cannot assume any legal responsibility or any liability for erroneous information or its consequences.

If you notice any errors in this documentation or have any suggestions for improvements, we would be grateful to receive your feedback.

Contact
SIX
eBill & Direct Debit Support
Pfingstweidstrasse 110
8005 Zürich
Switzerland

Phone: 0041 58 399 4800

1.2. Version information

Version: 6.3.0

1.3. Contact information

Contact: SIX eBill & Direct Debit Support
URL: https://www.six-group.com/en/products-services/banking-services/billing-and-payments.html
Email: support.billing-payments@six-group.com

1.4. URI scheme

Host: api.six-group.com
BasePath: /api/pns/networkpartner/v6
Scheme: https

1.5. Tags

Bill Recipients
This resource can be used to verify the existence of a specific billRecipientId in the eBill infrastructure.

Biller Certifications
This resource can be used to retrieve all biller certifications available in eBill infrastructure.
Biller certifications serve as markers that identify billers with specific characteristics, enhance their credibility and highlight their commitment to responsibility.

Biller Management
All operations that are associated with a biller are located within the biller resource, including the creation of business cases.
The operations are designed to be self contained, because of this, the data objects can be rather large. However this allows for complete validation and avoids chains of calls that depend on each other.

Biller-Driven Subscriptions
Further information about subscription processes can be found in Section 4.3.2, “Biller driven subscription”.

Industry Sectors
Industry sectors are valid system wide. Each biller will reference one or several industry sectors.

Notification Events
The event resource allows the network partner to retrieve all changes addressed to it. There is one specific operation for every type of event (for example: Subscription status changes or business case status changes), where the network partner can pull new changes from.
More details can be found in Section 3.3.11, “Guidelines for polling events”.

System Health Checks
This allows to check the basic state of the system (can it be reached, does authentication and authorization work, does it respond).
As some infrastructures block certain HTTP methods by default, the healthcheck allows to test if all required methods (GET, POST, PUT, DELETE) work across all layers.

eBill Direct Debit
Operations that are associated with eBill Direct Debit.
More details can be found in Section 4.5, “eBill Direct Debit”.

1.6. Documentation structure

This documentation consists of the following sections:

Chapter 1, Overview
Overview of the document.

Chapter 2, Introduction
High-level information about the eBill service with roles, interfaces, business introduction.

Chapter 3, General Documentation
Basic design principles, general concepts applied during API and model design like multilingual support, event and error handling.

Chapter 4, Use Cases
Describes the interactions between network partners and eBill in order to process business cases and manage system participants.

Chapter 5, Resources
Describes the endpoints of the API. Generated from the Swagger definition and enriched with additional information.

Chapter 6, Definitions
Request and Response definitions. Generated from the Swagger definition.

Chapter 7, Problem Descriptions Overview
Lists and describes all error responses.

Appendix A, Roadmap API Versions
Go live and end of life dates for each Network Partner API version.

Appendix B, Changelog
Log of changes between Network Partner API versions.

2. Introduction

The main goal of the Network Partner API is to offer network partners an easy to use interface to deliver electronic invoices in the name of their customers (billers) to the eBill infrastructure.
Electronic invoices delivered to this channel target online consumers on the financial institution / online banking side.

System participants of the eBill service are:

basic system participants
Figure 1. Participants of the eBill service

  • Biller (creditor) is a system participant that uses the eBill service to send electronic invoices to bill recipients.

  • Network partners offer the eBill service to billers. A system participant that delivers electronic invoices to the eBill infrastructure.

  • eBill infrastructure offers the eBill service of SIX to network partners and financial institutions. The eBill infrastructure manages master data, receives and processes business cases, creates payment instructions and sends them to financial institutions. Furthermore it offers an Events endpoint which consumers can poll to get information on changes that occurred asynchronously.

  • Financial institution of the bill recipient offers the eBill service to its customers (bill recipients). It provides banking services including the processing of payment instructions generated by the eBill infrastructure.

  • Bill recipients get access to the electronic invoices while using the online banking functionality of their financial institution.

  • Financial institution of a biller receive and book the payment on behalf of the biller. There is no direct relation to the eBill infrastructure.

2.1. Scope

This documentation focuses on the eBill service, which offers electronic invoices that can be viewed and processed by bill recipients using the eBill portal.
The documentation is specifically targeting network partners and does not include details for billers and financial institutions.

Other services of SIX, namely direct debit service ("LSV"), "E-Rechnung EDI" and "E-Rechnung Workflow" are not in scope.

2.2. System interfaces

System participants use different interfaces to communicate with the eBill infrastructure. The most important interfaces are described below:

system interfaces
Figure 2. Interfaces of the eBill infrastructure

  • Network Partner API allows network partners and - indirectly - the billers to interact with the eBill infrastructure.

  • Bank API is a webservice interface for financial institutions on the bill recipient side. It e.g. allows for single sign on with the eBill infrastructure.

  • Payment instruction interface is an asynchronous communication channel to send payment instruction messages (pain.001) to financial institutions and receive status report messages (pain.002) from financial institutions.

  • eBill portal is a central web application that can be used by all participating financial institutions. It allows bill recipients to use the eBill functionality in the web. Access to the eBill portal is always initiated from an online banking session.

Note
 Network partners can offer additional services to their customers, e.g. a web portal for billers. This kind of additional functionality is not part of the service offering of SIX and therefore not depicted above.

2.3. Primary network partners

The eBill infrastructure does not restrict billers to work with a single network partner. Specifically, it is possible for a biller to deliver business cases through several network partners.

However, to allow secure data management there are some restrictions and it is necessary that each biller assigns one network partner as primary network partner.

primary networkpartner
Figure 3. Network partner and primary network partner

The following functionality of the Network Partner API must be executed by the primary network partner (green above):

  • Creation of new billers in the eBill infrastructure. The creation of a biller will assign the registering network partner as primary network partner.

  • Management of biller master data.

  • Subscriptions and cancellation of subscriptions of bill recipients with billers.

After a biller was created by his primary network partner, the eBill infrastructure allows to deliver business cases using other network partners, too (grey above). The necessary contractual agreements and technical setup have to be completed between biller and network partner.

2.4. Billing and payment process overview

An entire billing and payment process using the eBill infrastructure is shown in the following overview:

Note
 Roles within a colored area can be represented by the same party. Example: Often, the bill recipient will be the same party as the one finally paying the bill with his account.
billing and payment flow with roles
Figure 4. Billing and Payment Process

  1. The biller sends an electronic invoice to a bill recipient using the services of his network partner and the eBill infrastructure. If the supplier or ultimate creditor is a different party than the biller, this has to be handled outside of the eBill infrastructure.

  2. The bill recipient approves the electronic invoice and a payment instruction is sent by the eBill infrastructure to his or her financial institution. If the bill recipient is not the owner of the account being debited, a debtor party may be involved. However, these structures are implemented by the financial institution and are not known to the eBill infrastructure.

  3. The debtor pays the bill and at the financial institutions the following steps occur:

    1. The financial institution of the debtor debits the account of the debtor.

    2. The financial institution of the debtor initiates the funds transfer to the financial institution of the biller.

    3. The financial institution of the biller credits the account of the biller and sends a credit note to the biller.

  4. A potential ultimate creditor may be informed by the biller (out of scope of the eBill infrastructure).

3. General Documentation

General information about the Network Partner API.

3.1. Design principles

The Network Partner API is designed and implemented as a RESTful API.

The REST resources are usually designed to be self-contained. However, complex business-objects (for example: a biller with multiple properties like logos) may be split into different resources and sub-resources.

3.1.1. Definition language

The Network Partner API is available as an OpenAPI Specification.
This detailed specification of the API is in itself also the documentation of the API.
Furthermore consumers of the API have the possibility to generate the client-side code from the specification.

The specification is provided in a separate file:

FileName

Description

networkpartner-api-v6-oas3.yaml

OpenAPI Specification of the Network Partner API. The OpenAPI Specification is best viewed in an editor such as https://editor.swagger.io/

3.1.2. Payload

The payload of the Network Partner API is defined in a format independent way in the Network Partner API specification.
The implementation of the Network Partner API expects and produces JSON-Payloads.

3.1.3. API versioning

API Versioning (Version number in OAS and XML-Schema):
1.2.1
| | |
| | +--- Defines the Patch Version, is incremented in case of a Bugfix in the API or a change of the documentation
| +----- Defines the Minor Version, is incremented in case of a Non-Breaking-Change in the API
+------- Defines the Major-Version, is incremented in case of a Breaking-Change in the API

Versioning in Namespace and in URLs:
1
|
+------ Defines the Major-Version and is incremented in case of a Breaking-Change in the API

The major version of the API is defined in the basepath URL.
Example: "https://api.six-group.com/api/pns/networkpartner/v6"

The following API changes are defined as backward compatible, meaning not a Breaking-Change, and will not lead to a new major version of the API specification:

  • adding a new resource

  • new, optional headers

  • new, optional query parameters

  • new, optional properties in a request

  • new properties in a response

  • mandatory property, query parameter or header becomes optional

  • changing the order of response properties

  • adding new problem types

Minor and patch level versions can be redeployed in the backend at any time.
API consumers have to deal with these backward compatible changes

The following API changes are examples of breaking-changes:

  • existing functionality is removed

  • mandatory data structure changes

  • renaming of a property, query parameter or header

  • optional property, query parameter or header becomes mandatory

Major version changes are always done with a transitional period, in this period both versions of the API are accessible.
Requests are always answered with the same major version as the requests were given (via basepath URL).

3.2. Security

3.2.1. HTTPS

The REST-API is exposed on an HTTPS endpoint supporting TLS versions 1.2 and 1.3.

3.2.2. Authentication

The Network Partner API authentication works via mTLS (mutual TLS).
The network partner must provide a valid certificate meeting the requirements documented at the following location:
https://billing.six-group.com/private/en/home/certificates.html

Furthermore, the network partner must provide the x-networkpartner-id header that unambiguously identifies the current caller.

mtls flow overview
Figure 5. mTLS Flow Overview

References:

For details on headers that the eBill infrastructure expects see Section 3.3.5, “HTTP headers”.

3.3. Conventions

3.3.1. Models

In Chapter 6, Definitions, all models that define the resources of the Network Partner API are listed.

3.3.2. Id-handling

Identifications ("id") within the Network Partner API are always generated by the Network Partner API. This means that when the consumer of a resource creates a new object, such as billers or business cases, the "id" field in these models are optional.
When the creation of these new objects is successful, the endpoint will respond with an unique "id" that is generated by the Network Partner API.
This "id" can then be used as a unique shared identifier for this particular object and will be mandatory in any update or deletion actions.

3.3.3. Multilingual support

To support a biller that operates in multiple language regions, the API offers the concept of localizedData. Within localizedData, the biller has to specify its default language as well as provide at least the localizedData belonging to the selected default language.
There is direct support for multiple languages and the setting of a default language in the following resources:
- Section 5.3.1, “Create a biller”
- Section 5.3.11, “Update biller”
- Section 5.3.13, “Create or update the custom subscription form of a biller”

The localizedData models for biller, and biller subscription forms can be found here: Section 6.53, “LocalizedBillerData”, Section 6.57, “LocalizedBillerSubscriptionFormField”, Section 6.58, “LocalizedBillerSubscriptionFormInfoText”

3.3.4. Assets

The Network Partner API supports the creation and management of binary assets such as images. Management of the assets is split into two separate steps: First an entity (e.g. a biller) is created using a POST call. This returns asset identification (assetId). In a second step the binary data for the assetId can be uploaded.
These calls are separated to avoid embedding binary data in Base64 encoded fields or MIME/multipart uploads.

Biller example: When creating a biller via Section 5.3.1, “Create a biller”, an empty asset is created for each logo in the Section 6.53, “LocalizedBillerData” entry. When the biller is created successfully, the operation will respond with a unique assetId for each one of these assets.
This returned assetId can then be used in combination with the Section 5.3.12, “Add/update asset” operation to upload the logo for the biller.
When changing a biller via Section 5.3.11, “Update biller”, without changes to the logo, an existing assetId can be reused.

3.3.5. HTTP headers

The network partner must provide the following HTTP header fields with each request:

HTTP-Header-Field

Description

Example

x-networkpartner-id

This field contains the network partner identity of the caller
A detailed description of the associated authentication is described in Section 3.2.2, “Authentication”

NWID0000012345

x-correlation-id

This field contains an ID, which will unambiguously identify this request to the API, this field is mandatory.
When the field is not included in the request the API will respond with a Code 400 (Bad Request).
The uniqueness of this value is validated for each network partner, the api will keep a buffer of the last 1000 correlation ids per network partner and validate the given value against this set.
The ID is used in to analyze problem cases and enables the eBill infrastructure to uniquely identify requests between a network partner and the API.
For responses, the ID is taken from the request. This allows queries and answers to be linked.
We recommend to use a RFC 4122 Version 4 UUID as correlation id.

d36d37e7-bfad-…​

3.3.6. Strings must conform to XML1.0 Character Subset

Strings used in modifying API calls must conform to the defined XML1.0 character subset throughout the API.
This restriction is imposed to avoid downstream issues when communicating with systems that are limited to this
character set.
Here an example for the regex pattern used to achieve this restriction:
'[\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*'
This includes all the non-control characters in the Basic Latin block as well as some control characters.

3.3.7. HTTP status codes

Each HTTP request of the client is answered to with a HTTP status code by the Network Partner API. The status code is an indication for the client whether or not the request was successful.
In the event of an error, the response body contains additional information about how the error can be resolved, see Section 3.3.8, “Error handling”.

3.3.8. Error handling

If a request was not successful, the according HTTP status code provides basic information (see Section 3.3.7, “HTTP status codes”).
Further details are in the response body, see https://tools.ietf.org/html/rfc7807.

Example of an error response:

   HTTP/1.1 400 Bad Request # (1)
   Content-Type: application/problem+json
   Content-Language: en
   {
    "type": "/problems/REQUEST_BODY_VALIDATION_FAILED", # (2)
    "title": "Payload has missing or invalid values", # (3)
    "status": 400, # (1)
    "detail": "The submitted request contains invalid or missing data which can not be processed.", # (4)
    "instance": "/api/pns/networkpartner/v6/billers/errors/NWID0090000001/ef46fa53-6377-40d3-9f35-39a4a507792e" # (5)
    "technicalReason": "some field validations failed" # (6)
    "fieldErrors": [ # (7)
        {
            "fieldName": "fieldNameWithValidationError",
            "message": "size must be between 1 and 1000",
            "rejectedValue": ""
        }
     ]
    }

  1. The HTTP status provides basic information.

  2. A problem URI specifies the type of problem that occurred. See Chapter 7, Problem Descriptions Overview for details.

  3. Human readable title of the problem.

  4. Details of the problem that occurred.

  5. A specific reference of this occurrence. A combination of request URL, network partner id and correlation id.

  6. A more detailed technical reason of the problem, if available.

  7. An object containing validation errors on field level, if available. The object contains the field name, a message and optionally a rejected value.

3.3.9. Event handling

All events are accessible on the specific operations of the resource Section 5.6, “Notification Events”.
The eBill infrastructure will generate events specifically for each consumer (e.g. network partner).

Each operation offers the following parameters to control which and how many events are returned in a single response:

Parameter

Description

lastEventId

when provided, the operation will only respond with events that occurred after the provided lastEventId

limit

the maximum number of events the endpoint will respond with in a single call

3.3.10. Search operations

Search operations in the form of POST requests, as for example Section 5.3.10, “Search billers”, use a common set of arguments and return identically structured response. In addition, they follow a common pagination behaviour. This chapter describes the commonalities.

The search query arguments allow the retrieval of result lists in consecutive requests. The search query may contain the arguments explained below. The order of arguments is not relevant.

Argument

Description

limit

Restricts the result set to the specified number of items. Less or none may be returned. The parameter may be omitted, in which case the default is applied.

offset

The distance from the first element in the resulting list to the first item to be returned. The very first item complying to the search arguments has an offset of 0. If omitted, 0 is assumed.

Examples:

URL query string

Explanation

/billers/search

Defaults apply and biller 1 to 100 are returned

/billers/search?limit=100

Equivalent to above

/billers/search?offset=0&limit=100

Equivalent to above

/billers/search?offset=0&limit=0

Returns an empty response

/billers/search?limit=500&offset=1000

Returns biller 1001 to 1500

/billers/search?offset=2000

Returns biller 2001 to 2100

Result lists always follow the same ordering.

The request body is a mandatory json type. It contains a sequence of filter arguments, wrapped in a type of name "filter". Filter arguments may be empty or omitted, the structure "filter" is mandatory but may be empty.

Search without arguments:

{
  "filter": {}
}

Search with some arguments:

{
  "filter": {
    "name": "SIX",
    "iban": "CH100023000A109822346"
  }
}

Search operations always return a response object. The response might however be empty, or contain less items then requested.
It contains a total count which indicates the number of items complying to the filter arguments, regardless of limit or offset. This may be used for pagination.
Finally, the response contains an array of items in the "items" structure. The array can be empty, in which case the total count is 0.

No items found:

{
  "totalCount": 0,
  "items": []
}

Two items found:

{
  "totalCount": 2,
  "items": [
    {
    ...
    },
    {
    ...
    }
  ]
}

3.3.11. Guidelines for polling events

Depending on the network partner, different types of events may be of interest. We recommend the network partner to consume those events of interest on a regular basis.
Generally it is recommended to poll each events endpoint once every couple of minutes, whereas it’s important to consume all events until the endpoint does not return any more events.
Please avoid querying events unnecessary often.
In order to keep our services performant, events won’t be available after 60 days. If you are unable to find your Event-Id, please query without Event-Id to get the oldest events available.

3.3.12. Maintenance windows

The healthcheck endpoints Section 5.7, “System Health Checks” provide information about the next planned maintenance windows. For each maintenance window the start, and the end time of maintenance is returned.
As soon as the maintenance is completed, the maintenance window will be removed from the list, and the eBill infrastructure is available again.
If the maintenance can’t be completed in the planned window, it won’t be updated. It will remain until the maintenance is done. In general this should not happen and therefore there should not be a maintenance window in the past.

4. Use Cases

4.1. Biller management

Billers are managed through the Section 5.3, “Biller Management” endpoints which offer a number of different operations:

  • The operation Section 5.3.10, “Search billers” is the public listing of all billers. This means it exposes all public biller data to all network partners, not only the biller’s primary network partner.

  • The operation Section 5.3.6, “Get biller by ID” is used to retrieve a single specific biller by its Id. It returns the complete biller information, but can only be called by the primary network partner of this biller.

  • The operation Section 5.3.1, “Create a biller” is used to create a new biller. The network partner that created the biller is automatically assigned as primary network partner. If its status is ACTIVE, a duplicate check will be performed on existing ACTIVE billers.

  • The operation Section 5.3.11, “Update biller” is used by the primary network partner of the biller to change the data of the biller. It is not possible to delete a biller, but one can set its status to INACTIVE. If its status is ACTIVE, a duplicate check will be performed on existing ACTIVE billers.

The network partner can specify if the biller is allowed to submit donation inquiries by the property 'isAllowedToSubmitDonationInquiries'. This permission must only be granted for verified non-profit organizations.
The network partner can add or remove certifications from his billers. Certifications serve as markers that identify billers with specific characteristics, enhance their credibility and highlights their commitment to responsibility.
Ebill infrastructure oversees the management of certifications available for billers, with the understanding that they can be altered or updated at any given time.
Certifications may be displayed to users within the eBill portal or online banking. Network partners bear the responsibility of ensuring that the certifications associated with their billers are consistently kept current and accurate.

4.2. Business case management

Business cases can be submitted through the operation Section 5.3.2, “Create business case in PDF/A-3b-format”. After a successful creation, the operation answers with a Section 6.39, “BusinessCase”.
The id assigned to the business case by the Network Partner API can later be used to retrieve the business case information from the Section 5.3.7, “Get business case” resource.
There are six business case types Section 6.6, “Bill”, Section 6.68, “Reminder”, Section 6.43, “CreditNote”, Section 6.2, “Advice”, Section 6.51, “InstalmentBill” and Section 6.45, “DonationInquiry”.

Credit note and advice only have the status OPEN and COMPLETED, which change, as soon as the user has viewed the business case.
These business cases are furthermore excluded from the status change reports.

The following state diagram shows the lifecycle of single payments (from a bill, reminder or donation inquiry) and instalments (from an instalment bill):

bill-reminder-instalment-state
Figure 6. Lifecycle of bills, reminders, instalments and donation inquiries

Happy path

  1. A new single payment or instalment was created.

  2. The single payment or instalment was approved, either by the bill recipient or a standing approval.

  3. The payment instruction was executed. The single payment or instalment gets completed.

Direct or indirect rejection by bill recipient

  1. The bill recipient rejected the single payment or instalment. If more information is needed, the biller must contact the bill recipient.

  2. The bill recipient deregistered from eBill while the single payment or instalment was still open.

Indirect rejection by eBill infrastructure

  1. The single payment or instalment was cleaned up by the eBill infrastructure.

Completed by user or business software or replaced or referencing business cases

  1. The single payment or instalment was either processed by an external business software and the status is therefore changed to completed or the user has changed the status to completed by himself.

Please note that a donation inquiry can not be replaced or referenced by another business case and vice versa. The following applies only for single payments that are not donation inquiries and instalments.
.. In case of a replacement of a bill or an instalment bill by a new submission, the referenced bill or all instalments of the referenced instalment bill changed to completed.
If the new submission was a reminder, it did not replace the bill or the instalment bill, but only references it and both business cases stay open. If either the reminder, the bill or any instalment of the instalment bill got approved, the referenced business case will be set to completed.
Referencing is possible in eBill-SIX_v6.xml with the element referencedBill, where the reference number of the referenced bill has to be provided.
.. As in (i), a bill or an instalment bill was referenced by a reminder. The approved business case of the pair got reopened, which reopens the referenced business case as well.

Revocation of an approvement

  1. The single payment or any instalment of an instalment bill got revoked/rejected in the online banking. As a consequence, its status changed back to open (reopened). But, if in the meantime (between approval and approval-rejection/-revocation), it was replaced by another submission (bill, reminder or instalment bill), its status will change to completed. Please note that a donation inquiry can not be replaced by another submission.
    There are multiple reasons for reopening:

    • The approval was revoked in the online banking by the bill recipient.

    • The payment instruction was not valid.

    • The payment instruction could not be executed.

Chargeback by bill recipient

  1. For a bill with eBill Direct Debit payment which supports chargeback, the bill recipient has the option to chargeback the debited amount within a period of 60 days after being notified about the payment.

Each status change will be reported by a specific event as described in Section 5.6, “Notification Events”. Excluded from the reports are status changes of the business cases Section 6.43, “CreditNote” and Section 6.2, “Advice”.
It’s distinguished between business case status change events (for bills, reminders and donation inquiries) and instalment status changed events (for instalment bills only).

Further information on the format of the PDF needed for the Section 5.3.2, “Create business case in PDF/A-3b-format” can be found in Section 4.2.1, “eBill format”.

4.2.1. eBill format

The eBill format is the specification of the PDF and the attachment included in the PDF. The PDF with the included attachment is the required payload of the Section 5.3.2, “Create business case in PDF/A-3b-format” operation.

Business considerations
The business requirements that are considered by this standard are summarized as follows:

  • It should be possible to easily convert existing electronic billing standards to the eBill format.

  • VAT details and instalments information are supported on the business case level in the format.

  • Addresses are required and structured in compliance with new regulations

  • Relevant information concerning bill recipient ERP systems are supported under the term "workflow".

    1. This workflow information is modeled as optional values in the eBill-SIX_v6.xml format and supports information pertaining to VAT, delivery of goods/services, and reference identifiers see Section 4.2.1.5, “Specification of the structured data”.

    2. Only the structure of this data is validated by the Network Partner API.

  • The information contained in the QR-bill must be sufficient for the creation of a simple electronic invoice. A minimal set of base attributes will be enriched by the network partner (for example, bill recipient identification, biller identification and business case type).

Basic structure

To facilitate the transfer of business cases from a network partner to the eBill infrastructure a standard-format has been defined.
The eBill infrastructure only handles this standard-format and does not convert or support any other formats.
Transformations from other message formats to eBill format can be offered by the network partner as a service.

The eBill format consists of a PDF-container with an XML attachment and embedded signatures, see the figure below.

PDF-Container
Figure 7. A representation of the PDF-container
Table 1. Glossary:

Name

Description

eBill format

The complete PDF (PDF incl. XML and signatures)

eBill-SIX_v6.xml

The Structured business case information in XML included as attachment in the PDF

eBill-SIX_v6.xsd

The XSD-Schema that describes the structure of the XML attachment (eBill-SIX_v6.xml)
Instalments

The structured data offers support for instalment bills. A biller can offer to pay his bill by various instalment options. Each of the instalment options can contain multiple instalments:

640
Figure 8. Example of two instalments options

The bill recipient will pick one of the instalment options in the UI and will subsequently approve all of the instalments.

File specification and signatures

The supplied PDF needs to be a PDF/A-3b conforming document. This type of document fulfills a number of requirements "out of the box" such as the support for long term archiving, embedding data, document signing and wide tools support.
A PDF is allowed to have other embedded documents. The eBill format requires that an XML attachment is included with the name "eBill-SIX_v6.xml" that is compliant with the eBill XSD. The PDF must not contain an XML attachment with name "eBill-SIX_v1.xml" or any other version.
The document needs to be signed with a PAdES-B-B-level conforming electronic signature. The documentation of the PAdES standard can be downloaded from https://www.etsi.org/.
The signature must be included in the PDF document and encompasses the whole PDF document including the embedded documents and at least the eBill-SIX_v6.xml.
It is possible to provide the singing certificate in the Document Security Store (DSS).

Note: Accessibility is not required in the PDF/A-3b. It is up to the biller to ensure accessibility, if desired.

Specification of the structured data

The specification of the eBill-SIX_v6.xml is created and maintained by SIX. The XML adheres to the following ground principles:

  • Simplicity of the format (No detailed invoice positions)

  • Limited user group (network partner to infrastructure)

  • Possibility to convert from existing, simple formats, through the use of QR-Bills

  • The format is based on the recommendations of "swissDIGIN content standard light"

A specification of the structured data (XML) including a detailed description is available.

This specification is delivered separately:

FileName

Description

eBill-SIX_v6.xsd

XSD-Schema of the structured data (eBill-SIX_v6.xml)

eBill-SIX_v6_advice.pdf
eBill-SIX_v6_bill.pdf
eBill-SIX_v6_creditNote.pdf
eBill-SIX_v6_instalmentBill.pdf
eBill-SIX_v6_reminder.pdf
eBill-SIX_v6_donationInquiry.pdf

documentation of the XML schema
Character set

The eBill-SIX_v6.xml content will be parsed using the UTF-8 character set. Please note that ISO 20022 messages according to the Swiss Payment Standard only allow the Latin Character Set to be used. Therefore a conversion as documented in the pain.001 specifications will be applied for non latin characters in the relevant fields.

4.2.2. eBill format versioning

The major version of the eBill format is defined in the namespace of the XML schema (eBill-SIX_v6.xsd).
Example: xmlns:ebill="http://six-group.com/pns/networkpartner/v6/ebill/xml"

The following XML schema changes are defined as backward compatible and will not lead to a new major version of the XML schema:

  • new, optional fields

  • adding new error codes

Consumers of the eBill format have to deal with such changes without prior notice.

4.3. Subscriptions and subscription cancellations

The transfer of business cases from a biller to a bill recipient requires both parties to agree on this process. The resulting connection is called "biller to bill recipient relation" or for simplicity just "biller relation". Initiating a biller to bill recipient relation is called "subscription" and there are various ways to achieve this:

bill recipient subscription options
Figure 9. Overview of biller subscription options

  1. Section 4.3.1, “Bill recipient driven subscription”

    1. Subscribe through the eBill portal with or without custom subscription form Section 4.3.1.1, “Subscribe through the eBill portal”

    2. Subscribe through the online banking of the financial institution Section 4.3.1.2, “Subscribe through the online banking”

  2. Section 4.3.2, “Biller driven subscription”

    1. Biller Look-Up Section 4.3.2.1, “Look-Up”.

    2. Subscribe through the website of the Biller Section 4.3.2.2, “Subscription at the biller”.

    3. Subscribe through the eBill infrastructure [Subscription at the eBill infrastructure].

  3. Automatically if the user accepts a proposed eBill Direct Debit proposal see Section 4.5.2, “Submit an eBill Direct Debit proposal”. In this scenario the custom subscription form details will not be provided, as the biller is already able to identify the bill recipient.

4.3.1. Bill recipient driven subscription

In all variants of bill recipient driven subscriptions, the driving user is the future bill recipient. In case of eBill sharing this can also be the authorized sharing partner.

The following state diagram of the biller to bill recipient relation illustrates the status transitions and reasons for it.

biller bill recipient relation state diagram
Figure 10. State diagram for biller to bill recipient relations

The bill recipient starts the subscription process either in the eBill portal or in the online banking. In ideal circumstances, the information provided by the eBill infrastructure (see Section 6.7, “BillRecipient”) is sufficient for the biller to identify and establish the specific relationship between himself and the bill recipient.

If additional information is required, a custom subscription form may be presented to the bill recipient. The form is defined by the biller within the eBill infrastructure by the primary network partner of the biller. The definition consists of input fields, explanatory information, constraints and properties for visual rendering. The form is presented to the bill recipient by the eBill portal during the subscription process, or, in a read-only mode, during a subscription at the eBill infrastructure (see [Subscription at the eBill infrastructure]). The presentation is an integral part of the eBill portal and has the same characteristics regarding design, multilingualism and accessibility. For more details about the different types of biller subscription form fields, see the resource definition: Section 5.3.13, “Create or update the custom subscription form of a biller”

Custom subscription forms may be altered any time by the primary network partner of the biller. Changes take effect immediately for new subscriptions, but presently viewed forms may not reflect the changes. In order to prevent receiving deprecated form data, the biller may alter its billRecipientSubscriptionStatus, so that no new subscriptions are started, wait for a period of time sufficient for current subscription processes to conclude, update the form and then change back the status.

Subscribe through the eBill portal

If the bill recipient is using the eBill portal, the subscription flow is as follows:

subscription byRE usingEvent
Figure 11. Subscription initiated by bill recipient

  1. A bill recipient finds the biller and starts a subscription request. If the biller has defined a custom subscription form within the eBill infrastructure, the form is shown to the bill recipient.

  2. The bill recipient concludes the subscription process, whereupon a biller relation in status REQUESTED is created and a subscription event is generated.

  3. The network partner polls for new subscription events…​.

    See the resource definition: Section 5.6.2, “Find events for bill recipient subscriptions which changed status”

  4. …​and receives the subscription data as a response. The subscription data may include filled in form data.

Subscribe through the online banking

A similar process is started if the bill recipient is using the online banking of his financial institution:

subscription directsubscription usingEvent
Figure 12. Subscription initiated by the online banking of the bill recipient

  1. A bill recipient enters payment information in the online banking of his financial institution. The financial institution checks if the payment information (account) refers to an entry in the biller directory. If a match is found, the online banking provides the user the option to subscribe to the biller.

  2. The user decides to subscribe to the biller in the online banking. The online banking calls the eBill infrastructure to subscribe.

  3. The eBill infrastructure creates a bill recipient subscription in status REQUESTED and creates a subscription event for the network partner.

  4. The response of the eBill infrastructure returns an OK code.

  5. The network partner polls for new subscription events…​.

    See the resource definition: Section 5.6.2, “Find events for bill recipient subscriptions which changed status”

  6. …​and receives the subscription data as a response. The response Section 6.14, “BillRecipientSubscription” contains both accountNumber which was used to identify the corresponding biller and referenceStructured which clearly identifies the bill recipient to the biller.

Events for subscriptions and subscription cancellations are triggered after a bill recipient has subscribed or unsubscribed to a biller. It is also possible for the bill recipient to subscribe multiple times to the same biller, which results in multiple events that can have the same status but maybe a different email address or a different address.

4.3.2. Biller driven subscription

It is in the best interest of billers to promote biller subscriptions to their customers. There are three ways a biller can initiate such a biller subscription:

If a customer is found via Look-Up, eBills can be sent to him immediately. An additional subscription process is not necessary.

Look-Up

Billers get the possibility to search for bill recipients using the Network Partner API. With a positive match the biller can immediately submit business cases to the bill recipient.

subscription byRS
Figure 13. Subscription initiated by biller using Look-Up

  1. Bill recipients can specify whether they can be found by billers by updating their Look-Up status in the user settings page. In case of non-profit organizations, bill recipients must explicitly agree to this in their user settings.

  2. The biller may query the eBill infrastructure to find bill recipients and/or potential donors (e.g. using the bill recipient’s email address as search criteria).

    See the resource definition: Section 5.3.9, “Search for multiple bill recipients for this biller”

  3. If all conditions are met, a positive response is returned and it is possible to submit a business case immediately.

    Note: If the bill recipient has not given consent for the processing of his data associated with the provided lookup attributes, a negative response will be returned. For example if a lookup is performed using a matching email address and birthdate, but the bill recipient has not given consent for the birthdate to be used for processing purposes, a negative response will be returned.

Subscription at the biller

In this method, the biller relation is created directly at the biller’s website. The biller can fully integrate the subscription process into its infrastructure, thus having the greatest possible flexibility and no media discontinuity. A prerequisite for this method is that the biller has identified its bill recipient (for example, by logging into the biller’s customer portal).

This functionality can only be offered by the primary networkpartner.

The flow for this subscription process looks as follows:

SubscriptionThroughBiller
Figure 14. Subscribtion at the biller

  1. The bill recipient chooses to use eBill as a payment method at the billers website and fills in its eBill email address, which is sent to the eBill infrastructure.

    See the resource definition: Section 5.4.2, “Initiate bill recipient subscription”.

  2. The email is verified and an email including a verification code is sent to the user.

  3. The eBill infrastructure responds with a unique token that identifies this subscription request.

  4. The user fills in the verification code on the billers website, the verification code and unique token are sent to the eBill infrastructure.

    See the resource definition: Section 5.4.1, “Confirm bill recipient subscription initiation”.

  5. If the token and code are valid, the eBill infrastructure creates a new biller relation in the status ACTIVE. The bill recipient data is returned to the network partner.

Furthermore, this flow could be combined with the Section 4.3.2.1, “Look-Up” flow as a first check to see if the bill recipient has Look-Up enabled. If this is the case, the biller does not need to go through the activation/subscription flow and instead can just send in eBills for this recipient.

Personalized subscription at the eBill infrastructure

With this method, the bill recipient subscribes to a biller with a personalized link at the eBill infrastructure. The subscription process for the bill recipient takes place entirely at the eBill infrastructure. The biller can request a personalized link and share it with his customer through various channels, either as a link or QR code:

  • via email

  • in a letter

  • on the website

The link is valid for a limited time.

subscription at ebill infrastructure
Figure 15. Personalized subscription at the eBill infrastructure

  1. The biller requests a personalized subscription URL for a specific customer. The biller may deposit one of the following customer identifying information for this subscription URL:

    1. QR-Reference

    2. Custom subscription form, already prefilled with customer identifying information compliant to the current definition. See Section 5.3.13, “Create or update the custom subscription form of a biller”.

  2. The biller presents the personalized subscription URL to its customers through any channel.

  3. The customers open their personalized subscription URL at the eBill infrastructure.

  4. The customers enter the email address that they already use for eBill. The email address is validated.

  5. An email with a verification code is sent to the customers.

  6. The customers enter the verification code. The verification code is validated.

  7. The identifying information of the customers is displayed, if any has been deposited. It cannot be changed. The customers confirms the subscription.

  8. Once the subscription is confirmed, a new biller relation with the status REQUESTED is created and a subscription event is triggered. The biller receives the subscription event via its network partner. Customer identifying information, if given, is included.

Before offering this subscription method to customers, it is recommended to check that the customers cannot be found via the Section 4.3.2.1, “Look-Up”. However, if the customers is found via Look-Up, eBills can be sent to them immediately. A separate subscription process is not necessary.

Generic subscription at the eBill infrastructure

With this method, the bill recipient subscribes to a biller with a generic link at the eBill infrastructure. The subscription process for the bill recipient takes place entirely at the eBill infrastructure. The biller can request a generic link and share it with its customers publicly through various channels, either as a link or QR code:

  • through advertisement at public places

  • social media

  • on a website

  • TV

The link is valid for a limited time. A biller can create multiple links and update their description and validity date.

subscription at ebill infrastructure
Figure 16. Generic subscription at the eBill infrastructure

  1. The biller requests a generic subscription URL for its customers. The biller may specify:

    1. A description for this subscription URL such as the name of a marketing initiative.

    2. A date of validity for this generic URL

  2. The biller presents the generic subscription URL to its customer through any channel.

  3. The customers open the generic subscription URL at the eBill infrastructure.

  4. The customers enter the email address that they already use for eBill. The email address is validated.

  5. An email with a verification code is sent to the customers.

  6. The customers enter the verification code. The verification code is validated.

  7. The identifying information of the customers is displayed and cannot be changed. The customers confirm the subscription.

  8. Once the subscription is confirmed, a new biller relation with the status REQUESTED is created and a subscription event is triggered. The biller receives the subscription event via its network partner.

4.3.3. Subscription cancellation

The cancellation of a subscription is always initiated by a bill recipient (a biller will simply decide not to send eBills any more - this is not represented in the eBill infrastructure).
A subscription cancellation leads to an event on the Network Partner API.

unsubscription byRE usingEvent
Figure 17. Subscription cancellation initiated by bill recipient

  1. A bill recipient clicks "unsubscribe" in the eBill portal.

  2. The eBill infrastructure sets the biller relation to INACTIVE and creates a subscription changed event with the necessary information.

  3. The network partner polls for new subscription cancellation events…​

    See the resource definition: Section 5.6.2, “Find events for bill recipient subscriptions which changed status”

  4. …​and receives the subscription cancellation data as a response.

4.4. Donation inquiries

Starting with v6 a new business case type 'DonationInquiry' can be submitted via the Network Partner API. This allows non-profit organizations such as clubs, associations or other charities to send donation inquiries to their members directly via eBill. Non-profit organizations are registered in the eBill infrastructure as billers which have been granted the permission to submit donation inquiries by the network partner. They operate as regular billers that can also submit regular bills like membership fees to their members. See Section 4.1, “Biller management” for more details.

DonationInquiry

Within the business case 'DonationInquiry' different donation purposes and donation amounts may be proposed (see element 'donationInquiry' in eBill-SIX_v6.xsd for more details). Here are examples of possible proposed donation purposes and donation amounts.

  1. Proposed donation purposes
    For a non-profit organization which focuses on preserving the nature, the proposed donation purposes could be:

    1. Species protection

    2. Woods

    3. Oceans

  2. Proposed donation amounts

    1. 10 CHF

    2. 50 CHF

    3. 100 CHF

This offers the donor the flexibility to choose for what and how much she or he wants to donate.
Both the proposed donation purposes and donation amounts are optional elements. Submitting proposed donation purposes does not imply the submission of proposed donation amounts and vice versa. If within a donation inquiry proposed donation amounts have been specified, the total and payment information amount must be omitted and vice versa. All the amount values within a donation inquiry must fulfill the requirements specified for donation inquiry amounts (see element 'donationInquiry' in eBill-SIX_v6.xsd for more details).

Donors are bill recipients that have all the options described in Section 4.3, “Subscriptions and subscription cancellations” to subscribe to non-profit organizations and receive donation inquiries via eBill.

Two possible use cases are described below:

Donation portal

  1. The donor is on a donation portal and decides to make a contribution for a specific donation purpose. The donor then determines the donation amount and chooses eBill as the payment method. This initiates a biller subscription process which is equivalent to the one described in Section 4.3.2.2, “Subscription at the biller”.

  2. Once the subscription to the biller (in this case the non-profit organization) is complete, the network partner submits the donation inquiry into the eBill infrastructure. The donation inquiry contains the donation purpose and amount selected by the donor before. In this case, no other donation purposes and donation amounts will be proposed. By providing a QR-Reference for the donation inquiry, the non-profit organization can easily match the donation afterwards.

  3. In the next step, the donation inquiry will be displayed to the bill recipient in the online banking of his/her financial institution or in the eBill portal. After approving the donation inquiry by the bill recipient (donor), the eBill infrastructure generates a network partner event enriched with the 'externalDonationPurposeId' if a proposed donation purpose has been selected by the donor.

In this way, the donor subscribes to the non-profit organization to receive also future donation inquiries and regular bills directly via eBill.

Fundraising campaigns

Fundraising campaigns are used by non-profit organizations to draw attention to their missions, particularly to programs or to initiatives for which they are currently soliciting donations. Within the donation inquiries arising during such a campaign, these missions can be represented in the proposed donation purposes like 'Species protection', 'Woods', 'Oceans', etc. Non-profit organizations may also propose different donation amounts and so give everybody the opportunity to make a small contribution. As described in Section 4.3.2.1, “Look-Up”, non-profit organizations may search for potential donors using the Network Partner API, if the bill recipient has given prior consent to use its eBill identification (e.g. its email address) to them.

4.5. eBill Direct Debit

With eBill Direct Debit, the biller is provided with functionalities to setup and manage debit mandates via the eBill infrastructure and automatically collect them on the bill recipient side (by an eBill Direct Debit standing approval). The bill recipient has the option to request the chargeback of a processed eBill Direct Debit payment.

eBill Direct Debit can be used for recurring collections from classic contractual relationships to service- or consumption bills such as rent, leasing, credit card bills, electricity bills, etc., as well as for one-time claims.

Before an eBill Direct Debit payment is possible, an eBill Direct Debit standing approval has to exist and can be created as following:

  1. Private eBill user

    1. Creates an eBill Direct Debit standing approval by itself

    2. Biller sends an eBill Direct Debit proposal, which can be accepted by the user (bill recipient)

  2. Business eBill user

    1. Biller sends an eBill Direct Debit proposal, which can be accepted by the user (bill recipient)

On existence of an eBill Direct Debit standing approval, the biller can start submitting bills with eBill Direct Debit payment, which are checked by the eBill infrastructure against the eBill Direct Debit mandate.
The eBill infrastructure processes the bill and transmits the eBill Direct Debit payment information to the bill recipient’s financial institution, that debits the bill recipients’s account and processes the payment in favor of the biller´s account.
The bill recipient has the option to chargeback the debited amount within a period of 60 days after being notified about the payment.

4.5.1. Enabling biller for eBill Direct Debit

enabling biller for ebill direct debit
Figure 18. Enabling biller for eBill Direct Debit

Prerequisites: Network partner is enabled for eBill Direct Debit.

  1. eBill Direct Debit contractual basis between biller and network partner established

  2. Primary network partner creates or updates biller and sets the ebillDirectDebitSupport to enabled (now it is possible to submit eBill Direct Debit proposals to bill recipients, see Section 4.5.2, “Submit an eBill Direct Debit proposal”)

  3. eBill Direct Debit contractual basis between biller and biller´s financial institution established

  4. Biller´s financial institution enables biller for eBill Direct Debit in eBill infrastructure and defines an eBill Direct Debit submission limit for the biller and currency (now one or more biller accounts are enabled for eBill Direct Debit and it is possible to submit bills with eBill Direct Debit payment)

4.5.2. Submit an eBill Direct Debit proposal

submit an ebill direct debit proposal
Figure 19. Submit an eBill Direct Debit proposal

Prerequisites: Network partner and biller are enabled for eBill Direct Debit.

  1. Biller checks whether it is allowed to submit an eBill Direct Debit proposal by calling Section 5.3.9, “Search for multiple bill recipients for this biller”

  2. In the response ebillDirectDebitProposalStatus must be «allowed»

  3. Biller submits eBill Direct Debit proposal (see Section 5.8.1, “Propose eBill Direct Debit to the bill recipient”)

  4. Bill recipient receives eBill Direct Debit proposal and accepts it (by accepting the proposal a new eBill Direct Debit standing approval gets created, additionally if a subscription is missing it is created on the fly Section 4.3, “Subscriptions and subscription cancellations”. Submissions of bills with eBill Direct Debit payment are possible, see Section 4.5.4, “Submit a bill with eBill Direct Debit payment”)

  5. On acceptance the biller gets notified by an event (see allowedEbillDirectDebitSubmissions in Section 5.6.2, “Find events for bill recipient subscriptions which changed status”)

4.5.3. Submit an eBill Direct Debit proposal (opt-in)

submit an ebill direct debit proposal opt in
Figure 20. Submit an eBill Direct Debit proposal (opt-in)

Prerequisites: Network partner and biller are enabled for eBill Direct Debit.

  1. Bill recipient enables «opt-in» for eBill Direct Debit

  2. Biller checks whether it is allowed to submit a proposal to the bill recipient via Look-Up, see Section 4.3.2.1, “Look-Up”

  3. In the response ebillDirectDebitProposalStatus must be «allowed»

  4. Biller submits eBill Direct Debit proposal (see Section 5.8.1, “Propose eBill Direct Debit to the bill recipient”)

  5. Bill recipient receives eBill Direct Debit proposal and accepts it (by accepting the proposal a new eBill Direct Debit standing approval gets created and submissions of bills with eBill Direct Debit payment are possible, see Section 4.5.4, “Submit a bill with eBill Direct Debit payment”)

  6. On acceptance the biller gets notified by an event (see allowedEbillDirectDebitSubmissions in Section 5.6.2, “Find events for bill recipient subscriptions which changed status”)

4.5.4. Submit a bill with eBill Direct Debit payment

submit a bill with ebill direct debit payment
Figure 21. Submit a bill with eBill Direct Debit payment

Prerequisites: Network partner, biller and biller account are enabled for eBill Direct Debit.

  1. Biller checks whether it is allowed to submit a bill with eBill Direct Debit payment by calling Section 5.3.9, “Search for multiple bill recipients for this biller”

  2. In the response allowedEbillDirectDebitSubmissions must be available with the correct currency chargebackMode combination (means there is an existing appropriate eBill Direct Debit standing approval)

  3. Biller submits bill with eBill Direct Debit payment (see Section 5.3.2, “Create business case in PDF/A-3b-format”)

  4. eBill Direct Debit payment will be automatically approved and a payment instruction is delivered to the bill recipient´s financial institution

  5. Biller gets notified by an event about the changed business case status, see Section 5.6.3, “Find events for business cases which changed status”

4.6. eBill eCommerce

With eBill eCommerce functionality, Payment Service Providers (PSPs) integrate eBill as an additional payment mechanism within the eCommerce checkout workflow, enabling online retailers in sectors such as home electronics, fashion, food, books, and media to offer eBill as a payment alternative to their customers. This integration is predicated on existing technical capabilities, including "biller registration" and "look-up" functionalities. Through PSP-side integration, eBill allows online merchants to provide a fully digitalized, frictionless payment experience.

4.6.1. Definition of eCommerce transaction

Please find the definition in the rulebook.

4.6.2. Validation Rule

The transaction must be a SinglePayment and should not fall under the (Business Case Type) categories of reminders, installment bills, donation inquiries, notifications, or credit notes.
The attribute that carries this information is defined as optional. If a transaction meets the eCommerce criteria, it should be submitted with the ECOMMERCE attribute. If a transaction does not meet the eCommerce criteria, it should be submitted with the OTHER attribute. If no information is provided OTHER as default is applied.

4.6.3. Impact

eCommerce transactions allow for a potential adjustment of transaction prices for the NWP.

5. Resources

5.1. Bill Recipients

This resource can be used to verify the existence of a specific billRecipientId in the eBill infrastructure.

5.1.1. Get bill recipient by ID

GET /bill-recipients/{billRecipientId}

Operation ID

getBillRecipientById

Description

The network partner can verify if a bill recipient is part of the eBill infrastructure by its billRecipientId.
The call will return the billRecipientId if the bill recipient has been found in the eBill infrastructure.
Receiving a billRecipientId does not necessary mean that the corresponding bill recipient is an acitve eBill user, it only means that this billRecipientId exists in the eBill infrastructure.

Validations

All validations according to Section 7.1, “Basic Validations”.

Parameters
Path Parameters
Name Description Schema

billRecipientId

required

ID of the bill recipient

Pattern: ([0-9])*
Minimum Length: 1
Maximum Length: 17
Example: 41010560425610173
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Bill recipient found

Section 6.8, “BillRecipientById”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.2. Biller Certifications

This resource can be used to retrieve all biller certifications available in eBill infrastructure.
Biller certifications serve as markers that identify billers with specific characteristics, enhance their credibility and highlight their commitment to responsibility.

5.2.1. Find Certifications

GET /certifications

Operation ID

findCertifications

Description

Get the certification list of the eBill infrastructure

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Certifications found

List of Section 6.41, “Certification”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3. Biller Management

All operations that are associated with a biller are located within the biller resource, including the creation of business cases.
The operations are designed to be self contained, because of this, the data objects can be rather large. However this allows for complete validation and avoids chains of calls that depend on each other.

5.3.1. Create a biller

POST /billers

Operation ID

createBiller

Description

This operation attempts to create a new biller in the system.

Before creating a new biller, a series of validations are executed (these rules apply even if the biller exists in INACTIVE status, except for duplicate checks, which only apply for billers in ACTIVE status).
If all validations pass, the biller is created and the response will contain the newly created biller ID.
If there is a conflict with an existing biller, its biller ID is provided in the technicalReason of the error response.

The network partner that successfully creates a biller becomes the primary network partner for this biller.
All other network partners will immediately be able to see a limited set of data of the the newly created biller.

The following diagram gives an overview of the organizational and technical steps of the biller creation:

createBiller
Figure 22. Create a biller

  1. Biller signs a contract with the network partner to use his services.

  2. The network partner creates the biller on the eBill infrastructure using the operation Section 5.3.1, “Create a biller”.

  3. The eBill infrastructure validates the request.

  4. After a successful validation, the API returns a new biller ID.

  5. The biller can start to use the eBill services via its network partner as soon as the registration is completed (e.g. searching bill recipients, creating business cases).

  6. Bill recipients can search for the newly created biller and subscribe with it.

Validations

All validations according to Section 7.1, “Basic Validations” and [Biller Validations] except INVALID_ASSET_ID and some of [Shared Validations].

Parameters
Body Parameter
Name Description Schema

BillerDetail

required

Data for the biller to be added

Section 6.28, “BillerDetail”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

201

Biller created

Section 6.28, “BillerDetail”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.2. Create business case in PDF/A-3b-format

POST /billers/{billerId}/business-cases

Operation ID

createBusinessCase

Description

The creation of a business case in PDF/A-3b format works with a simple POST request where the PDF is the binary payload of the request. The PDF needs to hold an embedded attachment in XML format describing
the business case according to the eBill-SIX_v6.xsd schema definition. Note that only one PDF can be submitted at a time.
The submitted payload has to comply to the standard conformance level PDF/A-3b whose set of requirements, restrictions and rules are being validated immediately upon submission.
The response either confirms the successful creation of the business case within the eBill system or presents the respective error details for the failed submission.

createBusinessCase
Figure 23. Create a business case

  1. A network partner submits a business case on behalf of a biller.

  2. Processing takes place in the eBill infrastructure.

  3. The response contains the generated business case id.

  4. As of this moment the business case is visible to bill recipients.

Addressing of a Business Case to a Bill Recipient

A submitted business case can be addressed to a bill recipient by the bill recipient’s email address or by its billRecipientId or by its swiss enterprise identification number (UID) from the commercial register (Handelsregister). Business cases addressing a bill recipient by its email address can be successfully submitted even if the bill recipient’s email address has been changed in the meantime (at least for a limited time). For further details see: Section 5.6.1, “Find events for bill recipients email address changes”

Validations

All validations according to Section 7.1, “Basic Validations”, [Business Case Validations], [Business Case Payment Validations], [Business Case Instalment Validations], [Business Case Donation Inquiry Validations], [PDF Validations] and some of [Shared Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Body Parameter
Name Description Schema

body

required

PDF as binary data

File
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105

x-filename

Filename for the business case PDF. This is only used for analytical purposes and support. The filename is not visible for the bill recipient.

Minimum Length: 1
Maximum Length: 99

x-anomaly-detection

If the optional header is provided with the value 'SKIP', the anomaly detection does not prevent business case submission

Minimum Length: 4
Maximum Length: 4
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

201

Business case created

Section 6.39, “BusinessCase”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.3. Delete asset

DELETE /billers/{billerId}/assets/{assetId}

Operation ID

deleteBillerAsset

Description

Delete the asset, this includes its binary and content type data. Only the primary network partner of a biller is allowed to manage its assets.

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456

assetId

required

Asset ID

Pattern: ASID[0-9]{10}
Maximum Length: 14
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/problem+json

Responses
Code Message Datatype

204

Biller asset deleted

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.4. Delete the subscription form of a biller

DELETE /billers/{billerId}/subscription-form

Operation ID

deleteBillerSubscriptionForm

Description

Deletes the subscription form. Only the primary network partner of the biller may call this endpoint.

Details regarding the subscription processes in general can be found in Section 4.3, “Subscriptions and subscription cancellations”. A description of bill recipient subscriptions with custom subscription form is in Section 4.3.1, “Bill recipient driven subscription”.

Validations

All validations according to Section 7.1, “Basic Validations” and the problem descriptions in [Custom Subscription Form Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/problem+json

Responses
Code Message Datatype

204

Biller subscription form deleted

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.5. Get asset data by ID

GET /billers/{billerId}/assets/{assetId}

Operation ID

getBillerAsset

Description

Get the binary data for a specific asset. Depending on the content type of the asset, it produces the response accordingly. Only the primary network partner of a biller is allowed to manage its assets.

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456

assetId

required

Asset ID

Pattern: ASID[0-9]{10}
Maximum Length: 14
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • image/jpeg

  • image/png

  • image/gif

  • application/pdf

  • application/problem+json

Responses
Code Message Datatype

200

Biller asset found

File

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.6. Get biller by ID

GET /billers/{billerId}

Operation ID

getBillerById

Description

Get all information for a specific biller. Calls are validated and only network partners are allowed to retrieve information for billers where they are assigned as primary network partner.

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Biller found

Section 6.28, “BillerDetail”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.7. Get business case

GET /billers/{billerId}/business-cases/{businessCaseId}

Operation ID

getBusinessCase

Description

Depending on the accept header, this operation either returns a JSON business case object or the original PDF.
The returned JSON object contains one of the business case subtypes: Bill, InstalmentBill, Reminder, CreditNote, Advice or DonationInquiry.

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456

businessCaseId

required

Pattern: BCID[0-9A-Z]{32}
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/pdf

  • application/problem+json

Responses
Code Message Datatype

200

Business case found

Section 6.39, “BusinessCase”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.8. Get the custom subscription form of a biller

GET /billers/{billerId}/subscription-form

Operation ID

getSubscriptionFormByBillerId

Description

Returns the custom subscription form of a biller.

Details regarding the subscription processes in general can be found in Section 4.3, “Subscriptions and subscription cancellations”. A description of bill recipient subscriptions with custom subscription form is in Section 4.3.1, “Bill recipient driven subscription”.

Validations

All validations according to Section 7.1, “Basic Validations” and the problem descriptions in [Custom Subscription Form Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

The custom subscription form of this biller

Section 6.33, “BillerSubscriptionForm”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.9. Search for multiple bill recipients for this biller

POST /billers/{billerId}/bill-recipients/search

Operation ID

searchBillRecipientsForBiller

Description

For each item in the request body, the endpoint will respond if the biller is allowed to submit a business case for a bill recipient with the provided ID.
In addition to the provided ID, the response will always contain the billRecipientId, if a business case submission is allowed.

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Body Parameter
Name Description Schema

BillRecipientsForBillerSearchRequest

required

Parameters for the search, at least one ID per entry is required

Section 6.21, “BillRecipientsForBillerSearchRequest”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Search successfully executed

Section 6.22, “BillRecipientsForBillerSearchResponse”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.10. Search billers

POST /billers/search

Operation ID

searchBillers

Description

A public listing of billers in the eBill infrastructure, refined by filter, limit and offset parameters. Can be used by all network partners to retrieve public data about each biller.

findBillers
Figure 24. Search billers

  1. A network partner sends the request to the eBill infrastructure

  2. The eBill infrastructure finds billers (active + inactive)

  3. and returns the answer to the network partner.

Validations

All validations according to Section 7.1, “Basic Validations”.

Parameters
Body Parameter
Name Description Schema

BillerSearchFilter

required

Filter object for search action

Section 6.30, “BillerSearchFilter”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Query Parameters
Name Description Schema

limit

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Maximum Value: 1000

offset

Indicates the distance between the first existing item (offset 0) and the first item to be returned.
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Response object containing billers matching the filter, limit and offset parameters.

Section 6.32, “BillerSearchResult”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.11. Update biller

PUT /billers/{billerId}

Operation ID

updateBiller

Description

Updates a biller with the given biller details. Only the primary network partner of a biller is allowed to update biller details.

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Body Parameter
Name Description Schema

BillerDetail

required

Biller, which should be updated

Section 6.28, “BillerDetail”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Biller updated

Section 6.28, “BillerDetail”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.12. Add/update asset

PUT /billers/{billerId}/assets/{assetId}

Operation ID

updateBillerAsset

Description

Update the asset's binary data or adds new binary data to the asset. Depending on the accept header the corresponding content type is stored along with the asset's binary data.
Note the different content types that are accepted: Biller logo assets have to be one of image/jpeg, image/png or image/gif.

Validations

All validations according to Section 7.1, “Basic Validations” and [Asset Validations] and some of [Shared Validations].

For image assets:

ASSET_IMAGE_INVALID
ASSET_MIME_TYPE_DOES_NOT_CORRESPOND_TO_CONTENT_TYPE
ASSET_IMAGE_EXCEEDS_MAXIMUM_SIZES

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456

assetId

required

Asset ID

Pattern: ASID[0-9]{10}
Maximum Length: 14
Body Parameter
Name Description Schema

body

required

Binary of biller asset

File
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/problem+json

Responses
Code Message Datatype

204

Biller asset updated

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.3.13. Create or update the custom subscription form of a biller

PUT /billers/{billerId}/subscription-form

Operation ID

updateBillerSubscriptionForm

Description

Only the primary network partner of the biller may maintain the subscription form. Since there may be only one form per biller, the endpoint url not only specifies the intent but also identifies the resource. A separate post-command is therefore omitted.

Details regarding the subscription processes in general can be found in Section 4.3, “Subscriptions and subscription cancellations”. A description of bill recipient subscriptions with custom subscription form is in Section 4.3.1, “Bill recipient driven subscription”.

Validations

All validations according to Section 7.1, “Basic Validations” and the problem descriptions in [Custom Subscription Form Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Body Parameter
Name Description Schema

BillerSubscriptionForm

required

Biller subscription form to create or update.

Section 6.33, “BillerSubscriptionForm”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Biller subscription form created or updated

Section 6.33, “BillerSubscriptionForm”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.4. Biller-Driven Subscriptions

Further information about subscription processes can be found in Section 4.3.2, “Biller driven subscription”.

5.4.1. Confirm bill recipient subscription initiation

PUT /billers/{billerId}/bill-recipient-subscription-initiations/{subscriptionInitiationToken}

Operation ID

confirmBillRecipientSubscriptionInitiation

Description

This endpoint verifies the combination of subscriptionInitiationToken and activation code. If the combination is valid, it creates an active biller relation.
Only the primary network partner of a biller is allowed to confirm the subscription at the biller initiation.

More details regarding bill recipient subscriptions can be found in Section 4.3.2.2, “Subscription at the biller”.

Validations

All validations according to Section 7.1, “Basic Validations” and the "INVALID_TOKEN_AND_ACTIVATION_CODE_COMBINATION" validation from Section 7.2, “Subscription Validations”.

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456

subscriptionInitiationToken

required

Subscription initiation token.

Minimum Length: 36
Maximum Length: 36
Body Parameter
Name Description Schema

SubscriptionInitiationActivationCode

required

activation code send to the user through

Section 6.71, “SubscriptionInitiationActivationCode”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Bill recipient relation initiated

Section 6.7, “BillRecipient”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.4.2. Initiate bill recipient subscription

POST /billers/{billerId}/bill-recipient-subscription-initiations

Operation ID

createBillRecipientSubscriptionInitiation

Description

This endpoint initiates the Section 4.3.2.2, “Subscription at the biller” process, returns a subscription token to the caller and sends a verification code to the eBill subscribers email address.
Only the primary network partner of a biller is allowed to initiate the subscription at the biller.

More details regarding bill recipient subscriptions can be found in Section 4.3.2.2, “Subscription at the biller”.

Validations

All validations according to Section 7.1, “Basic Validations” and the "INVALID_TOKEN_AND_ACTIVATION_CODE_COMBINATION" validation from Section 7.2, “Subscription Validations”.

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Body Parameter
Name Description Schema

SubscriptionInitiationEmailAddress

required

Email address for bill recipient subscription initiation.

Section 6.72, “SubscriptionInitiationEmailAddress”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

201

Subscription initiation token which was sent to the user

Section 6.73, “SubscriptionInitiationToken”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.4.3. Initiate a generic bill recipient subscription and return the URL to the eBill infrastructure

POST /billers/{billerId}/bill-recipient-subscription-initiations-generic-url

Operation ID

createBillRecipientSubscriptionInitiationGenericURL

Description

This endpoint initiates a bill recipient subscription. It returns a generic bill recipient URL pointing to the subscription initiation at the eBill infrastructure, where the subscription may be concluded. Only the primary network partner of a biller is allowed to initiate a subscription.

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Body Parameter
Name Description Schema

BillRecipientSubscriptionInitiationGenericURL

required

Properties of the generic bill recipient subscription url.

Section 6.17, “BillRecipientSubscriptionInitiationGenericURL”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

201

Generic bill recipient URL to subscribe through the eBill infrastructure

Section 6.11, “BillRecipientGenericUrlSubscriptionResponse”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.4.4. Initiate a bill recipient specific subscription and return the URL to the eBill infrastructure

POST /billers/{billerId}/bill-recipient-subscription-initiations-url

Operation ID

createBillRecipientSubscriptionInitiationURL

Description

This endpoint initiates a bill recipient specific subscription. It returns a bill recipient personalized URL pointing to the subscription initiation at the eBill infrastructure, where the subscription may be concluded. Only the primary network partner of a biller is allowed to initiate a subscription.

More details regarding this type of bill recipient subscription can be found in [Subscription at the eBill infrastructure].

Validations

All validations according to Section 7.1, “Basic Validations”, [Biller Validations] and [Custom Subscription Form Data Validations].

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Body Parameter
Name Description Schema

BillRecipientURLSubscription

required

Bill recipient identifying information for the subscription initiation at the eBill infrastructure.

Section 6.20, “BillRecipientURLSubscription”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

201

Bill recipient personalized URL to subscribe through the eBill infrastructure

Section 6.13, “BillRecipientPersonalizedUrlSubscriptionResponse”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.4.5. Update a generic bill recipient subscription url

PUT /billers/{billerId}/bill-recipient-subscription-initiations-generic-url/{subscriptionAtEbillTokenId}

Operation ID

updateBillRecipientSubscriptionInitiationGenericURL

Description

This endpoint updates a bill recipient subscription url. Only the primary network partner of a biller is allowed to update a subscription url.

Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456

subscriptionAtEbillInitiationTokenId

required

ID of the subscription at ebill initiation token

Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Body Parameter
Name Description Schema

BillRecipientSubscriptionInitiationGenericURL

required

Properties of the generic bill recipient subscription url.

Section 6.17, “BillRecipientSubscriptionInitiationGenericURL”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Bill recipient generic URL to subscribe through the eBill infrastructure

Section 6.11, “BillRecipientGenericUrlSubscriptionResponse”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.5. Industry Sectors

Industry sectors are valid system wide. Each biller will reference one or several industry sectors.

5.5.1. Find Sectors

GET /sectors

Operation ID

findSectors

Description

Get the industry sector list of the eBill infrastructure. The sectors are more or less static and can therefore be cached.

Validations

All validations according to Section 7.1, “Basic Validations”.

Parameters
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Sectors found

List of Section 6.69, “Sector”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.6. Notification Events

The event resource allows the network partner to retrieve all changes addressed to it. There is one specific operation for every type of event (for example: Subscription status changes or business case status changes), where the network partner can pull new changes from.
More details can be found in Section 3.3.11, “Guidelines for polling events”.

5.6.1. Find events for bill recipients email address changes

GET /events/bill-recipient-email-address-changed

Operation ID

findBillRecipientEmailAddressChangedEvents

Description

This event is triggered after a biller has submitted a business case with an outdated, so called historically available email address. It notifies about the changed email address of a bill recipient, which has been adjusted in eBill.

An email address is considered to be historically available if it was present up to 15 months prior to the submission time.

The billers are able to submit business cases with historically available email addresses of a bill recipient. However, latest 15 months after the email address changed, the billers are required to submit the business cases with the currently valid email address of the bill recipient.

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Query Parameters
Name Description Schema

lastEventId

ID of the last received event. If omitted, the result starts with the oldest available event.

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36
Example: EVID82A65938766547EBBBA39BA6F7B07F24

limit

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Maximum Value: 1000
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Bill recipient email address changed events found

List of Section 6.9, “BillRecipientEmailAddressChangedEvent”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.6.2. Find events for bill recipient subscriptions which changed status

GET /events/bill-recipient-subscription-status-changed

Operation ID

findBillRecipientSubscriptionStatusChangedEvents

Description

More information about the subscription process can be found in Section 4.3, “Subscriptions and subscription cancellations”.

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Query Parameters
Name Description Schema

lastEventId

ID of the last received event. If omitted, the result starts with the oldest available event.

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36
Example: EVID82A65938766547EBBBA39BA6F7B07F24

limit

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Maximum Value: 1000
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Bill recipient subscription changed events found

List of Section 6.19, “BillRecipientSubscriptionStatusChangedEvent”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.6.3. Find events for business cases which changed status

GET /events/business-case-status-changed

Operation ID

findBusinessCaseStatusChangedEvents

Description

Events for status changes of bills, reminders and donation inquiries.

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Query Parameters
Name Description Schema

lastEventId

ID of the last received event. If omitted, the result starts with the oldest available event.

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36
Example: EVID82A65938766547EBBBA39BA6F7B07F24

limit

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Maximum Value: 1000
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Business case status changed events found

List of Section 6.40, “BusinessCaseStatusChangedEvent”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.6.4. Find events for instalments which changed status

GET /events/instalment-status-changed

Operation ID

findInstalmentStatusChangedEvents

Description

Events for status changes of instalment bills only.

Validations

All validations according to Section 7.1, “Basic Validations” and some of [Shared Validations].

Parameters
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Query Parameters
Name Description Schema

lastEventId

ID of the last received event. If omitted, the result starts with the oldest available event.

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36
Example: EVID82A65938766547EBBBA39BA6F7B07F24

limit

Maximum number of items to be returned (technical maximum is 1000, no more will be returned).

Maximum Value: 1000
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Instalment status changed events found

List of Section 6.52, “InstalmentStatusChangedEvent”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.7. System Health Checks

This allows to check the basic state of the system (can it be reached, does authentication and authorization work, does it respond).
As some infrastructures block certain HTTP methods by default, the healthcheck allows to test if all required methods (GET, POST, PUT, DELETE) work across all layers.

5.7.1. Health check using DELETE method

DELETE /healthcheck

Operation ID

healthCheckForDelete

Description

Returns without further content. This operation will not modify the system.

Validations

All validations according to Section 7.1, “Basic Validations”.

Parameters
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/problem+json

Responses
Code Message Datatype

204

Healthcheck successful

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.7.2. Health check using GET method

GET /healthcheck

Operation ID

healthCheckForGet

Description

Returns a status message of the system.

Validations

All validations according to Section 7.1, “Basic Validations”.

Parameters
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Healthcheck successful

Section 6.49, “HealthCheckResponse”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.7.3. Health check using POST method

POST /healthcheck

Operation ID

healthCheckForPost

Description

Returns the request body. This operation will not modify the system.

Validations

All validations according to Section 7.1, “Basic Validations”.

Parameters
Body Parameter
Name Description Schema

HealthCheckRequest

required

Any message which is expected in the response

Section 6.48, “HealthCheckRequest”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Healthcheck successful

Section 6.49, “HealthCheckResponse”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.7.4. Health check using PUT method

PUT /healthcheck

Operation ID

healthCheckForPut

Description

Returns the request body. This operation will not modify the system.

Validations

All validations according to Section 7.1, “Basic Validations”.

Parameters
Body Parameter
Name Description Schema

HealthCheckRequest

required

Any message which is expected in the response

Section 6.48, “HealthCheckRequest”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

200

Healthcheck successful

Section 6.49, “HealthCheckResponse”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

5.8. eBill Direct Debit

Operations that are associated with eBill Direct Debit.
More details can be found in Section 4.5, “eBill Direct Debit”.

5.8.1. Propose eBill Direct Debit to the bill recipient

POST /billers/{billerId}/ebill-direct-debit-proposal

Operation ID

createEbillDirectDebitProposal

Description
Parameters
Path Parameters
Name Description Schema

billerId

required

Biller unique ID.

Pattern: BIID[0-9]{10}
Maximum Length: 14
Example: BIID0000123456
Body Parameter
Name Description Schema

EbillDirectDebitProposal

required

Definition of the eBill Direct Debit proposal

Section 6.46, “EbillDirectDebitProposal”
Header Parameters
Name Description Schema

x-networkpartner-id

required

ID which will identify the calling network partner

Pattern: NWID[0-9]{10}
Minimum Length: 14
Maximum Length: 14
Example: NWID0000123456

x-correlation-id

required

ID which will unambiguously identify this request to the API.

Minimum Length: 1
Maximum Length: 36
Example: fc83a5bf-85b8-4f8b-a09c-b4eb6ef12105
Content Type

  • application/json

  • application/problem+json

Responses
Code Message Datatype

201

eBill Direct Debit proposal created.

Section 6.46, “EbillDirectDebitProposal”

default

See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Section 6.63, “Problem”

6. Definitions

6.1. AccountNumber

For the account number, an IBAN has to be specified.

Field Name Description Schema

iban

Credit account

- The requirements for IBAN usage are limited to the country codes CH and LI, otherwise the business case will be rejected.

- The IBAN should match an already existing credit account of the biller, otherwise the business case will be rejected.

- See also ISO-13616-1

Type: String

Pattern: (CH|LI)\d{7}[0-9A-Z]{12}
Maximum Length: 21

Example: CH100023000A109822346

6.2. Advice

A business case of type Advice

Field Name Description Schema

id

required

A unique ID for this business case. Property must not be given when creating a new business case.

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

type

required

The type of the business case.

Type: String

Enum: Bill, InstalmentBill, Advice, CreditNote, Reminder, DonationInquiry

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

referenceNumber

required

A business case reference given by the biller. Must be unique in combination with the billerId.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 120

Example: 2018-123456-22

referencedBill

Section 6.67, “ReferencedBill”

businessCaseDate

required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Type: date
Format: date

Example: 2017-12-22

status

The status of the business case.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED, CHARGEBACK_INITIATED

subscriptionRole

Role for the activation of a subscription

Type: String

Enum: ACTIVATED_SUBSCRIPTION, NONE

totalAmount

required

Section 6.62, “OptionalAmountWithCurrency”

6.3. AllowedEbillDirectDebitSubmission

Defines the relevant information what type of eBill Direct Debit submission the biller is allowed to do.

Field Name Description Schema

currencyCode

required

The amount currency code according to ISO-4217 used for eBill Direct Debit.

Type: String

Pattern: CHF|EUR
Maximum Length: 3

Example: CHF

chargebackMode

required

Section 6.42, “ChargebackMode”

6.4. AnomalyDetectionConfig

Configuration of the anomaly detection for biller submissions.

Field Name Description Schema

monthlySubmissionLimit

required

Biller submissions are only allowed up to this monthly count limit.

Type: Integer

Minimum Value: 0
Maximum Value: 2147483647

6.5. ApprovalAmountWithCurrency

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

Field Name Description Schema

value

required

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java).

Type: BigDecimal

Maximum Value: 99999999.99

Example: 99.99

currencyCode

required

The amount currency code according to ISO-4217.

Type: String

Pattern: [A-Z]{3}
Maximum Length: 3

Example: CHF

6.6. Bill

A business case of type Bill

Field Name Description Schema

id

required

A unique ID for this business case. Property must not be given when creating a new business case.

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

type

required

The type of the business case.

Type: String

Enum: Bill, InstalmentBill, Advice, CreditNote, Reminder, DonationInquiry

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

referenceNumber

required

A business case reference given by the biller. Must be unique in combination with the billerId.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 120

Example: 2018-123456-22

referencedBill

Section 6.67, “ReferencedBill”

businessCaseDate

required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Type: date
Format: date

Example: 2017-12-22

status

The status of the business case.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED, CHARGEBACK_INITIATED

subscriptionRole

Role for the activation of a subscription

Type: String

Enum: ACTIVATED_SUBSCRIPTION, NONE

totalAmount

required

Section 6.62, “OptionalAmountWithCurrency”

6.7. BillRecipient

Field Name Description Schema

emailAddress

Email address of the bill recipient.

Type: String
Format: email
Minimum Length: 1
Maximum Length: 256

Example: peter@muster.ch

billRecipientId

required

ID of the bill recipient

Type: String

Pattern: ([0-9])*
Minimum Length: 1
Maximum Length: 17

Example: 41010560425610173

enterpriseIdentificationNumber

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

Type: String

Pattern: CHE[0-9]{9}
Maximum Length: 12

Example: CHE123456789

type

required

The type of the bill recipient.

Type: String

Enum: PRIVATE, COMPANY

name

required

Last name, if private bill recipient.
Company name, if company bill recipient.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 70

Example: for private bill recipient: Muster, for company name: Muster AG

firstName

First name, if private bill recipient.
Empty, if company bill recipient.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Maximum Length: 35

Example: Peter

correspondenceLanguage

required

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

Type: String

Minimum Length: 1
Maximum Length: 3

Example: ger

address

required

Section 6.66, “RecipientAddress”

6.8. BillRecipientById

Field Name Description Schema

billRecipientId

ID of the bill recipient

Type: String

Pattern: ([0-9])*
Minimum Length: 1
Maximum Length: 17

Example: 41010560425610173

6.9. BillRecipientEmailAddressChangedEvent

An Event describing the change of the email address of a bill recipient.

Field Name Description Schema

eventId

required

Event ID.

Type: String

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36

Example: EVID82A65938766547EBBBA39BA6F7B07F24

timestamp

required

Timestamp of the event.

Type: Date
Format: date-time

Example: 2015-01-01T10:00Z

oldEmailAddress

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

Type: String
Format: email
Minimum Length: 1
Maximum Length: 256

Example: peter@muster.ch

newEmailAddress

The new email address of the bill recipient.

Type: String
Format: email
Minimum Length: 1
Maximum Length: 256

Example: peter_new@muster.ch

triggeredBy

Section 6.10, “BillRecipientEmailAddressChangedEventAllOfTriggeredBy”

6.10. BillRecipientEmailAddressChangedEventAllOfTriggeredBy

Field Name Description Schema

businessCaseId

required

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

6.11. BillRecipientGenericUrlSubscriptionResponse

Field Name Description Schema

subscriptionAtEbillInitiationTokenId

Type: String


Example: c376b56-e71d-485d-b639-2a06222db031

subscriptionUrl

Type: String


Example: https://qr-connect-app.ebill.six-group.com?token=c376b56-e71d-485d-b639-2a06222db031

subscriptionInfo

Type: String


Example: Marketing campaign for central Switzerland

validTo

Type: date
Format: date

Example: 2018-03-25

6.12. BillRecipientIdentification

One property out of emailAddress, billRecipientId or enterpriseIdentificationNumber must be set.
Optionally birthDate and postalCode can be set to narrow down the results.

Field Name Description Schema

emailAddress

Email address of the bill recipient.

Type: String
Format: email
Minimum Length: 1
Maximum Length: 256

Example: peter@muster.ch

billRecipientId

ID of the bill recipient

Type: String

Pattern: ([0-9])*
Minimum Length: 1
Maximum Length: 17

Example: 41010560425610173

enterpriseIdentificationNumber

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

Type: String

Pattern: CHE[0-9]{9}
Maximum Length: 12

Example: CHE123456789

birthDate

Birth date of the bill recipient (ISO-8601 format).
Note that this field is optional and is used to narrow down the search result.

Type: date
Format: date

Example: 2015-01-01

postalCode

Postal code of the bill recipient, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.
Note that this field is optional and is used to narrow down the search result.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 9

Example: 6025

6.13. BillRecipientPersonalizedUrlSubscriptionResponse

Field Name Description Schema

subscriptionUrl

Type: String


Example: https://qr-connect-app.ebill.six-group.com?token=c376b56-e71d-485d-b639-2a06222db031

validTo

Type: date
Format: date

Example: 2018-03-25

6.14. BillRecipientSubscription

Field Name Description Schema

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

billRecipient

required

Section 6.7, “BillRecipient”

accountNumber

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

Type: String

Maximum Length: 21

referenceStructured

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

Type: String

Pattern: ([a-zA-Z0-9])*
Maximum Length: 27

Example: 123456123456789012345678901

6.15. BillRecipientSubscriptionForm

Contains additional information regarding a bill recipient subscription. It contains the users input to the BillerSubscriptionForm.

Field Name Description Schema

billRecipientSubscriptionFormFields

Type: List of Section 6.16, “BillRecipientSubscriptionFormField”

6.16. BillRecipientSubscriptionFormField

Field Name Description Schema

technicalId

required

The identifying token of this subscription form field. Corresponds to the property technicalId of BillerSubscriptionFormField.

Type: String

Minimum Length: 1
Maximum Length: 35

Example: customerNumber

value

required

The value of this subscription form field as entered by the user. If a pattern is defined, it has been checked against it.

Type: String

Minimum Length: 1
Maximum Length: 256

6.17. BillRecipientSubscriptionInitiationGenericURL

Field Name Description Schema

subscriptionInfo

Provides details about the requested generic URL.

Type: String

Pattern: [\p{IsLatin}\p{P}\p{S} \d]*
Minimum Length: 1
Maximum Length: 150

Example: Marketing campaign for central Switzerland

validTo

required

The last date on which the URL will be valid. It can be set to a maximum of 1 year in the future

Type: date
Format: date

Example: 2018-03-25

6.18. BillRecipientSubscriptionStatus

If allowed, the biller can be found and bill recipients can subscribe with this biller.

Enum Values

ALLOWED

NOT_ALLOWED

6.19. BillRecipientSubscriptionStatusChangedEvent

An Event describing the status change of a bill recipient subscription.

Field Name Description Schema

eventId

required

Event ID.

Type: String

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36

Example: EVID82A65938766547EBBBA39BA6F7B07F24

timestamp

required

Timestamp of the event.

Type: Date
Format: date-time

Example: 2015-01-01T10:00Z

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

billRecipient

required

Section 6.7, “BillRecipient”

accountNumber

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

Type: String

Maximum Length: 21

referenceStructured

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

Type: String

Pattern: ([a-zA-Z0-9])*
Maximum Length: 27

Example: 123456123456789012345678901

billRecipientSubscriptionFormFields

Type: List of Section 6.16, “BillRecipientSubscriptionFormField”

newStatus

The new status of the bill recipient subscription, see Section 4.3, “Subscriptions and subscription cancellations” for further information.

Type: String

Enum: INACTIVE, REQUESTED, ACTIVE

allowedEbillDirectDebitSubmissions

Defines what kind of eBill Direct Debit submissions are allowed.

Type: List of Section 6.3, “AllowedEbillDirectDebitSubmission”

subscriptionSource

Type: String

Enum: WITH_SUBSCRIPTION_FORM, DIRECTLY, DIRECT_DEBIT_STANDING_APPROVAL_FROM_PROPOSAL, DIRECT_DEBIT_STANDING_APPROVAL_FROM_REQUEST_PARAMETERS, EBILL_CONNECT_PERSONALIZED, EBILL_CONNECT_GENERIC, BANK_PORTAL, ADMIN_PORTAL

subscriptionInfo

Type: String


Example: Marketing campaign for central Switzerland

6.20. BillRecipientURLSubscription

Field Name Description Schema

referenceStructured

If provided, must be of type QR reference number.

Type: String

Pattern: ([a-zA-Z0-9])*
Maximum Length: 27

Example: 123456123456789012345678901

subscriptionFormData

Section 6.15, “BillRecipientSubscriptionForm”

6.21. BillRecipientsForBillerSearchRequest

Field Name Description Schema

items

required

Type: List of Section 6.12, “BillRecipientIdentification”

6.22. BillRecipientsForBillerSearchResponse

Field Name Description Schema

items

required

Type: List of Section 6.23, “BillRecipientsForBillerSearchResponseItem”

6.23. BillRecipientsForBillerSearchResponseItem

Field Name Description Schema

emailAddress

Email address of the bill recipient.

Type: String
Format: email
Minimum Length: 1
Maximum Length: 256

Example: peter@muster.ch

billRecipientId

ID of the bill recipient

Type: String

Pattern: ([0-9])*
Minimum Length: 1
Maximum Length: 17

Example: 41010560425610173

enterpriseIdentificationNumber

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

Type: String

Pattern: CHE[0-9]{9}
Maximum Length: 12

Example: CHE123456789

birthDate

Birth date of the bill recipient (ISO-8601 format).
Note that this field is optional and is used to narrow down the search result.

Type: date
Format: date

Example: 2015-01-01

postalCode

Postal code of the bill recipient, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.
Note that this field is optional and is used to narrow down the search result.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 9

Example: 6025

ebillSubmissionStatus

required

Defines if the biller can submit a business-case for the provided bill recipient identification in the request (ALLOWED) or if the bill recipient identification is either not known to the eBill infrastructure or the submission is not allowed (NOT_ALLOWED).

Type: String

Enum: ALLOWED, NOT_ALLOWED

ebillDirectDebitProposalStatus

required

Defines if the biller can submit an eBill Direct Debit proposal for the provided bill recipient ID in the request (ALLOWED) or if the bill recipient is either not known to the eBill infrastructure or the submission of an eBill Direct Debit proposal is not allowed (NOT_ALLOWED).

Type: String

Enum: ALLOWED, NOT_ALLOWED

allowedEbillDirectDebitSubmissions

Defines what kind of eBill Direct Debit submissions are allowed.

Type: List of Section 6.3, “AllowedEbillDirectDebitSubmission”

6.24. Biller

Field Name Description Schema

id

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

status

required

The status of the biller.

Type: String

Enum: ACTIVE, INACTIVE

legalName

required

Legal name of the company which is displayed in the invoice overview, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 70

Example: Verlag Neuer

enterpriseIdentificationNumber

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

Type: String

Pattern: CHE[0-9]{9}
Maximum Length: 12

Example: CHE123456789

billRecipientSubscriptionStatus

required

Section 6.18, “BillRecipientSubscriptionStatus”

localizedData

required

Section 6.29, “BillerLocalizedData”

sectorIds

required

List of assigned sector ids to the biller.

Type: List of string

allowedToSubmitDonationInquiries

required

States whether the biller is allowed to submit donation inquiries. Only billers that have been verified to be non-profit organisations (NPO) may be granted this permission.

Type: Boolean

ebillDirectDebitSupport

required

Defines whether the biller supports eBill Direct Debit.
Only billers that support eBill Direct Debit are allowed to create eBill Direct Debit proposals and submit bills with eBill Direct Debit payment.
Only network partners that support eBill Direct Debit themselves are allowed to enable eBillDirectDebitSupport.
As soon as the biller is enabled for eBill Direct Debit, it is possible to submit eBill Direct Debit proposals.
For details see Section 4.5, “eBill Direct Debit” part in the documentation.

Type: String

Enum: ENABLED, DISABLED

billerDirectSubscriptionSupport

required

Defines whether the biller supports direct subscription.

Type: String

Enum: ENABLED, DISABLED

certificationIds

List of assigned certification ids.

Type: List of string

6.25. BillerAccount

Field Name Description Schema

accountNumber

required

Section 6.1, “AccountNumber”

iid

required

The required institution identification of the associated financial institute.
Please use leading zeroes to reach the 5 digit value.

Type: String

Pattern: [0-9]{5}
Minimum Length: 5
Maximum Length: 5

Example: 00100

qrIbanAccountSupplement

In case the account number is of type QR-IBAN the account supplement can be used as additional information to this account number for distinguishing billers using the same QR-IBAN. The combination of QR-IBAN and account supplement must be unique. The account supplement is used during business case validation (if an account supplement is defined the QR-Reference has to start with these exact digits) and during direct subscription from online banking (if an account supplement is defined the QR-Reference has to start with these exact digits to produce a match for direct subscription).

Type: String

Pattern: [0-9]{6}
Minimum Length: 6
Maximum Length: 6

Example: 345924

currencyCode

required

Currency code in ISO-4217.

Type: String

Pattern: [A-Z]{3}
Maximum Length: 3

Example: CHF

ebillDirectDebitSupport

Represents whether the associated financial institution for the biller account has enabled the account for eBill Direct Debit.
Property must not be given when creating or updating a biller account, this is considered a 'read only' property.
As soon as the biller account supports eBill Direct Debit and the biller itself supports eBill Direct Debit, the network partner can submit bills with eBill Direct Debit payment.
For details see Section 4.5, “eBill Direct Debit” part in the documentation.

Type: String

Enum: ENABLED, DISABLED

6.26. BillerAccountsAnomalyDetection

Field Name Description Schema

accounts

required

List of biller accounts.

Type: List of Section 6.25, “BillerAccount”

anomalyConfiguration

required

Section 6.4, “AnomalyDetectionConfig”

6.27. BillerAddress

Field Name Description Schema

streetName

required

Street name, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 70

Example: Neustadtstrasse

buildingNumber

Building number, the pattern restricts to word characters of the US-ASCII, slashes, empty spaces and hyphens.

Type: String

Pattern: [\w/ -]*
Minimum Length: 1
Maximum Length: 16

Example: 20a

postalCode

required

Postal code, the pattern restricts to word characters of the US-ASCII, empty spaces and hyphens.

Type: String

Pattern: [\w -]*
Minimum Length: 1
Maximum Length: 9

Example: 6025

city

required

City name, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 35

Example: Neudorf

countryCode

required

In format ISO 3166-1 alpha 2.

Type: String

Pattern: [A-Z]{2}
Maximum Length: 2

Example: CH

6.28. BillerDetail

Field Name Description Schema

id

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

status

required

The status of the biller.

Type: String

Enum: ACTIVE, INACTIVE

legalName

required

Legal name of the company which is displayed in the invoice overview, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 70

Example: Verlag Neuer

enterpriseIdentificationNumber

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

Type: String

Pattern: CHE[0-9]{9}
Maximum Length: 12

Example: CHE123456789

billRecipientSubscriptionStatus

required

Section 6.18, “BillRecipientSubscriptionStatus”

localizedData

required

Section 6.29, “BillerLocalizedData”

sectorIds

required

List of assigned sector ids to the biller.

Type: List of string

allowedToSubmitDonationInquiries

required

States whether the biller is allowed to submit donation inquiries. Only billers that have been verified to be non-profit organisations (NPO) may be granted this permission.

Type: Boolean

ebillDirectDebitSupport

required

Defines whether the biller supports eBill Direct Debit.
Only billers that support eBill Direct Debit are allowed to create eBill Direct Debit proposals and submit bills with eBill Direct Debit payment.
Only network partners that support eBill Direct Debit themselves are allowed to enable eBillDirectDebitSupport.
As soon as the biller is enabled for eBill Direct Debit, it is possible to submit eBill Direct Debit proposals.
For details see Section 4.5, “eBill Direct Debit” part in the documentation.

Type: String

Enum: ENABLED, DISABLED

billerDirectSubscriptionSupport

required

Defines whether the biller supports direct subscription.

Type: String

Enum: ENABLED, DISABLED

certificationIds

List of assigned certification ids.

Type: List of string

accounts

required

List of biller accounts.

Type: List of Section 6.25, “BillerAccount”

anomalyConfiguration

required

Section 6.4, “AnomalyDetectionConfig”

6.29. BillerLocalizedData

Field Name Description Schema

defaultLanguage

required

Section 6.44, “DefaultLanguage”

ger

Section 6.53, “LocalizedBillerData”

fre

Section 6.53, “LocalizedBillerData”

ita

Section 6.53, “LocalizedBillerData”

eng

Section 6.53, “LocalizedBillerData”

6.30. BillerSearchFilter

Filter object for the search of billers. Filter attributes may be omitted or empty. All filter parameters are combined by AND. See also Section 3.3.10, “Search operations”

Field Name Description Schema

filter

required

Section 6.31, “BillerSearchFilterFilter”

6.31. BillerSearchFilterFilter

Field Name Description Schema

name

Search pattern applied on legal and display names of all languages. All names conforming to or containing the pattern are matches. The search is case insensitive.

Type: String

enterpriseIdentificationNumber

Search pattern applied on the swiss enterprise identification number (UID). The search argument may not contain dashes, dots or extensions. The pattern must be an exact match.

Type: String

iban

Search pattern applied on the IBAN credit account. The pattern must be an exact match.

Type: String

billerId

Search pattern applied on biller ID. Only exact matches, will always return maximum one record.

Type: String

6.32. BillerSearchResult

Field Name Description Schema

totalCount

required

Total count of matching billers, regardless of limit and offset applied.

Type: BigDecimal

items

required

An array of found items that might be empty.

Type: List of Section 6.24, “Biller”

6.33. BillerSubscriptionForm

A custom subscription form of a biller.

Field Name Description Schema

defaultLanguage

required

Section 6.44, “DefaultLanguage”

infoText

Section 6.58, “LocalizedBillerSubscriptionFormInfoText”

billerSubscriptionFormFields

An array of custom subscription form fields. The number of fields within the context of a bill recipient type may be zero and may not exceed three (See the description of the property "applyToBillRecipientType" for more details). Specified fields are mandatory to successfully complete the subscription process to the biller.

Type: List of Section 6.36, “BillerSubscriptionFormField”

6.34. BillerSubscriptionFormChoice

Textual representation of a subscription form field of type CHOICE in specific locales.

Field Name Description Schema

choiceId

required

The choiceId, which the user has selected, will be delivered as "value" along with the technicalId in the object billRecipientSubscriptionFormFields of the bill-recipient-subscription-status-changed-event. The pattern restricts to word characters of the US-ASCII

Type: String

Pattern: [\w]*
Minimum Length: 1
Maximum Length: 36

defaultChoice

required

Exactly one of the subscription form field choices must be marked as a pre-selected default choice.

Type: Boolean

localizedData

required

Section 6.35, “BillerSubscriptionFormChoiceLocalizedData”

6.35. BillerSubscriptionFormChoiceLocalizedData

Translations of one particular choice into potential target languages of a recipient. At least the default language of the subscription form must be provided.

Field Name Description Schema

ger

Section 6.56, “LocalizedBillerSubscriptionFormChoice”

fre

Section 6.56, “LocalizedBillerSubscriptionFormChoice”

ita

Section 6.56, “LocalizedBillerSubscriptionFormChoice”

eng

Section 6.56, “LocalizedBillerSubscriptionFormChoice”

6.36. BillerSubscriptionFormField

An abstract biller subscription form field. Depicts all common properties. Not used directly but rather subclassed by several concrete variants.

Field Name Description Schema

type

required

Designates the type of form field. The individual form field types behave as follows:
- CUSTOM: The biller pre-defines and delivers all field-properties. Localized data is mandatory for this type. A constraint may be given but remains optional.
- BIRTHDATE: Static definition data is kept and maintained by the eBill infrastructure. No constraint or localized data is allowed for this type.
- CHOICE: The biller has to specify localized data for the field as well as an array of possible choices. A constraint is not allowed for this type. For example, if the biller is a non-profit organisation a subscription form field of this type can represent the different proposed donation purposes.

Type: String

Enum: CUSTOM, BIRTHDATE, CHOICE

applyToBillRecipientType

required

Establishes the type of bill recipient for which this field shall be used. For example, for bill recipients of type COMPANY only form fields of type COMPANY and ALL will be shown. Fields of type ALL will be included in every form. The maximum of three fields may not be exceeded for any bill recipient type. For example, if one field is specified for the bill recipient type "ALL", a maximum of two other fields per bill recipient type "PRIVATE" and "COMPANY" are allowed to be specified.

Type: String

Enum: ALL, PRIVATE, COMPANY

technicalId

required

The identifying name of a subscription form field. The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: \^[\u0021-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]+$
Minimum Length: 1
Maximum Length: 35

Example: customerNumber

constraint

Section 6.37, “BillerSubscriptionFormFieldConstraint”

localizedData

Section 6.38, “BillerSubscriptionFormFieldLocalizedData”

choices

An array of possible choices for this form field. Only allowed for form fields of type CHOICE, for which it is mandatory.

Type: List of Section 6.34, “BillerSubscriptionFormChoice”

6.37. BillerSubscriptionFormFieldConstraint

Constraints to be applied on the input of this field.

Field Name Description Schema

pattern

Regex pattern limiting possible input values. Adheres to the Java regex syntax and must conform to these restrictions:
* No unbounded quantifiers '\d+' or '\d*' or '\d{4,}' and no more than 30 repetitions. Use exact cardinalities '\d{5}' or ranges '\d{4,7}'.
* No alternations within a repeated group '((abc){3}|(def){2}){30}'.
* No partial or multiple matches '[a-f]{2}'. Use only exact matches '^[a-f]{7}$'.
* No longer than 100 characters.
The string to define the pattern must be a subset of XML1.0 conform characters to avoid downstream issues.
If a pattern is given to validate the user input, a concise explanation and example for the end user must be provided in the description field of LocalizedBillerSubscriptionFormField.

Type: String

Pattern: [\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 100

Example: ^\d{3}-\w{4}-\d{3}$

minLength

If given, specifies the minimum length of the field. Must be between 1 and 256.

Type: BigDecimal

Minimum Value: 1
Maximum Value: 256

maxLength

If given, specifies the maximum length of the field. Must be between 1 and 256.

Type: BigDecimal

Minimum Value: 1
Maximum Value: 256

6.38. BillerSubscriptionFormFieldLocalizedData

Field Name Description Schema

ger

Section 6.57, “LocalizedBillerSubscriptionFormField”

fre

Section 6.57, “LocalizedBillerSubscriptionFormField”

ita

Section 6.57, “LocalizedBillerSubscriptionFormField”

eng

Section 6.57, “LocalizedBillerSubscriptionFormField”

6.39. BusinessCase

The abstract business case object containing the shared properties.

Field Name Description Schema

id

required

A unique ID for this business case. Property must not be given when creating a new business case.

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

type

required

The type of the business case.

Type: String

Enum: Bill, InstalmentBill, Advice, CreditNote, Reminder, DonationInquiry

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

referenceNumber

required

A business case reference given by the biller. Must be unique in combination with the billerId.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 120

Example: 2018-123456-22

referencedBill

Section 6.67, “ReferencedBill”

businessCaseDate

required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Type: date
Format: date

Example: 2017-12-22

status

The status of the business case.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED, CHARGEBACK_INITIATED

subscriptionRole

Role for the activation of a subscription

Type: String

Enum: ACTIVATED_SUBSCRIPTION, NONE

totalAmount

required

Section 6.62, “OptionalAmountWithCurrency”

6.40. BusinessCaseStatusChangedEvent

An event describing the status change of a business case.
These events are sent for bills, reminders and donation inquiries.
The approved amount does always contain a value and a currency, but is only provided for the status APPROVED.

Field Name Description Schema

eventId

required

Event ID.

Type: String

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36

Example: EVID82A65938766547EBBBA39BA6F7B07F24

timestamp

required

Timestamp of the event.

Type: Date
Format: date-time

Example: 2015-01-01T10:00Z

billerId

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

businessCaseId

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

newStatus

The new status of the business case.
CHARGEBACK_INITIATED is only used in conjunction with bills containing an eBill Direct Debit payment.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED, CHARGEBACK_INITIATED

approvedAmount

Section 6.5, “ApprovalAmountWithCurrency”

externalDonationPurposeId

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.

Type: String

6.41. Certification

Field Name Description Schema

id

A unique ID for this certification.

Type: String

Pattern: CEID[0-9]{10}
Maximum Length: 14

Example: CEID0000000000

name

Name of the certification.

Type: String

Minimum Length: 2
Maximum Length: 70

Example: ZEWO

6.42. ChargebackMode

If supported, the bill recipient can initiate a chargeback of the corresponding payment.

Enum Values

SUPPORTED

NOT_SUPPORTED

6.43. CreditNote

A business case of type CreditNote

Field Name Description Schema

id

required

A unique ID for this business case. Property must not be given when creating a new business case.

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

type

required

The type of the business case.

Type: String

Enum: Bill, InstalmentBill, Advice, CreditNote, Reminder, DonationInquiry

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

referenceNumber

required

A business case reference given by the biller. Must be unique in combination with the billerId.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 120

Example: 2018-123456-22

referencedBill

Section 6.67, “ReferencedBill”

businessCaseDate

required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Type: date
Format: date

Example: 2017-12-22

status

The status of the business case.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED, CHARGEBACK_INITIATED

subscriptionRole

Role for the activation of a subscription

Type: String

Enum: ACTIVATED_SUBSCRIPTION, NONE

totalAmount

required

Section 6.62, “OptionalAmountWithCurrency”

6.44. DefaultLanguage

From the provided localizedData, one has to be marked as the default language.
The eBill infrastructure will use this localizedData in case a user requests a language where no localizedData have been provided.

Enum Values

ger

fre

ita

eng

6.45. DonationInquiry

A business case of type donation inquiry. Please note for donation inquiries ReferencedBill is not supported and must not to be specified

Field Name Description Schema

id

required

A unique ID for this business case. Property must not be given when creating a new business case.

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

type

required

The type of the business case.

Type: String

Enum: Bill, InstalmentBill, Advice, CreditNote, Reminder, DonationInquiry

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

referenceNumber

required

A business case reference given by the biller. Must be unique in combination with the billerId.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 120

Example: 2018-123456-22

referencedBill

Section 6.67, “ReferencedBill”

businessCaseDate

required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Type: date
Format: date

Example: 2017-12-22

status

The status of the business case.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED, CHARGEBACK_INITIATED

subscriptionRole

Role for the activation of a subscription

Type: String

Enum: ACTIVATED_SUBSCRIPTION, NONE

totalAmount

required

Section 6.62, “OptionalAmountWithCurrency”

6.46. EbillDirectDebitProposal

eBill Direct Debit proposal for the bill recipient.

Field Name Description Schema

id

A unique ID for this eBill Direct Debit proposal. Property must not be given when creating a new object.

Type: String

Minimum Length: 36
Maximum Length: 36

billRecipientIdentification

required

Section 6.12, “BillRecipientIdentification”

currencyCode

required

The amount currency code according to ISO-4217 used for eBill Direct Debit.

Type: String

Pattern: CHF|EUR
Maximum Length: 3

Example: CHF

chargebackMode

required

Section 6.42, “ChargebackMode”

6.47. Event

Contains common fields for all events.

Field Name Description Schema

eventId

required

Event ID.

Type: String

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36

Example: EVID82A65938766547EBBBA39BA6F7B07F24

timestamp

required

Timestamp of the event.

Type: Date
Format: date-time

Example: 2015-01-01T10:00Z

6.48. HealthCheckRequest

Field Name Description Schema

message

required

Expected response message from health check.

Type: String

Minimum Length: 1
Maximum Length: 100

Example: any string

6.49. HealthCheckResponse

Field Name Description Schema

message

required

Response message from health check.

Type: String

Maximum Length: 100

Example: The healthcheck GET request was successfully received and processed

requestDateTime

required

According to RFC3339, section 5.6 in ISO 8601 with timezone and milliseconds.

Type: Date
Format: date-time

Example: 2018-10-03T16:03:09.101+02:00

receivedHeaders

required

Type: List of Section 6.50, “HealthCheckResponseReceivedHeader”

environmentStage

required

The instance which the request was sent to.

Type: String


Example: XE

applicationVersion

required

The version of the eBill infrastructure.

Type: String


Example: 1.4.3.0-desire-20180927091004161-71-5e3ca91

apiVersion

required

The version of the network partner api.

Type: String


Example: 1.0.23

maintenanceWindows

Information about the upcoming maintenance windows. If no maintenance is planned, an empty list is returned.

Type: List of Section 6.61, “MaintenanceWindow”

6.50. HealthCheckResponseReceivedHeader

Field Name Description Schema

headerName

The name of the provided header.

Type: String


Example: x-correlation-id

headerValue

As received

Type: String


Example: 9bcd4351-4b7b-4017-9b63-9613414c6ff1

6.51. InstalmentBill

A business case of type InstalmentBill

Field Name Description Schema

id

required

A unique ID for this business case. Property must not be given when creating a new business case.

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

type

required

The type of the business case.

Type: String

Enum: Bill, InstalmentBill, Advice, CreditNote, Reminder, DonationInquiry

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

referenceNumber

required

A business case reference given by the biller. Must be unique in combination with the billerId.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 120

Example: 2018-123456-22

referencedBill

Section 6.67, “ReferencedBill”

businessCaseDate

required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Type: date
Format: date

Example: 2017-12-22

status

The status of the business case.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED, CHARGEBACK_INITIATED

subscriptionRole

Role for the activation of a subscription

Type: String

Enum: ACTIVATED_SUBSCRIPTION, NONE

totalAmount

required

Section 6.62, “OptionalAmountWithCurrency”

6.52. InstalmentStatusChangedEvent

An Event describing the status change of an instalment.
These events are only sent for instalment bills.
The approved amount does always contain a value and a currency, but is only provided for the status APPROVED.

Field Name Description Schema

eventId

required

Event ID.

Type: String

Pattern: EVID[0-9A-Z]{32}
Maximum Length: 36

Example: EVID82A65938766547EBBBA39BA6F7B07F24

timestamp

required

Timestamp of the event.

Type: Date
Format: date-time

Example: 2015-01-01T10:00Z

billerId

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

businessCaseId

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

externalPaymentByInstalmentsId

External ID of the respective paymentByInstalment.

Type: String

Minimum Length: 1
Maximum Length: 36

Example: 298031-2999

externalInstalmentId

External ID of the instalment.

Type: String

Minimum Length: 1
Maximum Length: 36

Example: 298031-2999-ACX01

newStatus

The new status of the instalment.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED

approvedAmount

Section 6.5, “ApprovalAmountWithCurrency”

6.53. LocalizedBillerData

Field Name Description Schema

displayName

required

Display name which will be used for presentation in the biller overview, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 100

Example: Neuers Neuste Nachrichten

emailAddress

Email address to contact the biller. It is recommended to provide a specific address for questions concerning eBill, if available.

Type: String
Format: email
Minimum Length: 1
Maximum Length: 256

Example: nnn@nnn-verlag.info

phone

Section 6.55, “LocalizedBillerDataPhone”

website

Website to contact the biller. It is recommended to provide a specific website for questions concerning eBill, if available. The pattern restricts to word characters of the US-ASCII and some special characters.

Type: String

Pattern: [\w .:/@?&=%-]*
Minimum Length: 1
Maximum Length: 1000

Example: http://www.nnn-verlag.info

address

required

Section 6.27, “BillerAddress”

logo

Section 6.54, “LocalizedBillerDataLogo”

Biller logos may be provided and will be scaled down to the necessary size.
Contains the reference to a logo as binary from the /biller/{billerId}/assets endpoint.
For create/update: if assetId is empty, a new assetId will be returned, were the logo can be uploaded.

6.55. LocalizedBillerDataPhone

Phone number to contact the biller. It is recommended to provide a specific phone number for questions concerning eBill, if available.

Both the countryCode and the nationalNumber are as defined in International Telecommunication Union (ITU) Recommendation E.164, without any leading zeros.

Field Name Description Schema

countryCode

required

Country code.

Type: Integer

Maximum Value: 999999

Example: 41

nationalNumber

required

National number.

Type: Long
Format: int64
Maximum Value: 999999999999999999

Example: 446681800

6.56. LocalizedBillerSubscriptionFormChoice

Textual properties of a subscription form choice in a specific locale.

Field Name Description Schema

label

required

The display label of a subscription form choice. The pattern restricts to any latin letter and any digit.

Type: String

Pattern: [\p{IsLatin}\p{P} \d]+
Minimum Length: 1
Maximum Length: 36

Example: Ozeane

6.57. LocalizedBillerSubscriptionFormField

Textual properties of a subscription form field in a specific locale.

Field Name Description Schema

label

required

The display label of a subscription form field. The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 35

Example: Kundennummer

description

An additional field description to a subscription form field. The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues

Type: String

Pattern: [\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 256

Example: Kundennummer nach diesem Beispiel eingeben: "123-abcd-456".

6.58. LocalizedBillerSubscriptionFormInfoText

Introductory text presented to the user as part of a biller subscription form.

Field Name Description Schema

localizedData

required

Section 6.59, “LocalizedBillerSubscriptionFormInfoTextLocalizedData”

6.59. LocalizedBillerSubscriptionFormInfoTextLocalizedData

Field Name Description Schema

ger

Type: String

Pattern: [\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Maximum Length: 500

Example: Diese Anmeldung gilt für "xy Unfallversicherungen", für "xy Lebensversicherungen" müssen Sie sich gesondert anmelden. The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

fre

Type: String

Pattern: [\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Maximum Length: 500

Example: Cette inscription est valable pour "xy assurance accident", pour "xy assurance vie" vous devez vous inscrire séparément. The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

ita

Type: String

Pattern: [\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Maximum Length: 500

Example: Questa registrazione è valida per "xy assicurazione infortuni", per "xy assicurazione sulla vita" dovete registrarvi separatamente. The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

eng

Type: String

Pattern: [\u0009\u000A\u000D\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Maximum Length: 500

Example: This registration is valid for "xy accident insurance", for
"xy life insurance" you must register separately. The pattern restricts
to a subset of XML1.0 conform characters to avoid downstream issues.

6.60. LocalizedSectorData

Field Name Description Schema

name

required

Name of the sector.

Type: String

Minimum Length: 1
Maximum Length: 36

Example: Transport

6.61. MaintenanceWindow

Field Name Description Schema

start

required

Start time of the maintenance window.

Type: Date
Format: date-time

Example: 2021-01-01T10:00Z

end

required

End time of the maintenance window.

Type: Date
Format: date-time

Example: 2021-01-01T14:00Z

6.62. OptionalAmountWithCurrency

An amount whose value may be omitted.

Field Name Description Schema

value

The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java).

Type: BigDecimal

Maximum Value: 99999999.99

Example: 99.99

currencyCode

required

The amount currency code according to ISO-4217.

Type: String

Pattern: [A-Z]{3}
Maximum Length: 3

Example: CHF

6.63. Problem

An error occurred while processing the request.
See section Error Handling of the Network Partner API documentation for further details about errors and error handling.

Field Name Description Schema

type

required

Section 6.65, “ProblemType”

title

A short, human readable summary of the problem type.

Type: String


Example: Payload has missing or invalid values

status

The HTTP status code generated by the origin server for this occurrence
of the problem.

Type: Integer
Format: int32
Minimum Value: 100
Maximum Value: 600

Example: 400

detail

A human readable explanation specific to this occurrence of the
problem.

Type: String


Example: The submitted request contains invalid or missing data which can not be processed.

instance

A URI that identifies the specific occurrence of the problem.

Type: URI
Format: uri

Example: /api/pns/networkpartner/v5/billers/errors/NWID0090000001/provided-x-correlation-id

technicalReason

The Technical Description/Reason for engineers might contain addition system information on the problem.

Type: String


Example: Some field validations failed

fieldErrors

Type: List of Section 6.64, “ProblemFieldError”

6.64. ProblemFieldError

Field Name Description Schema

fieldName

The name of the field with the error.

Type: String


Example: localizedData.ger.address.city

message

The message describing the error.

Type: String


Example: size must be between 1 and 35

rejectedValue

The provided value which was rejected if available.

Type: String


Example: Very Long Invalid City Name Which Is Rejected

6.65. ProblemType

Identifies the problem type.
Consult the Network Partner API documentation for further information.

Enum Values

UNAUTHORIZED

REQUEST_URL_MALFORMED

NETWORK_PARTNER_UNKNOWN

NETWORK_PARTNER_NOT_ACTIVE

REQUEST_CONTENT_TYPE_UNSUPPORTED

REQUEST_METHOD_NOT_ALLOWED

INVALID_RESOURCE

REQUEST_PAYLOAD_EXCEEDS_MAXIMUM_SIZE

REQUEST_PAYLOAD_IS_EMPTY

REQUEST_BODY_VALIDATION_FAILED

REQUEST_HEADER_VALIDATION_FAILED

HTTP_MEDIA_TYPE_NOT_ACCEPTABLE

NETWORK_PARTNER_OPERATION_NOT_ALLOWED

REQUEST_QUERY_PARAMETER_VALIDATION_FAILED

INVALID_EMAIL

INVALID_CURRENCY_CODE

INVALID_ASSET_ID

ASSET_ID_MUST_NOT_BE_PROVIDED

LOCALIZED_DATA_FOR_DESIRED_DEFAULT_LANGUAGE_MISSING

BILL_RECIPIENT_IDENTIFICATION_INVALID

BILL_RECIPIENT_EMAIL_NOT_FOUND

BILL_RECIPIENT_ID_NOT_FOUND

BILL_RECIPIENT_HRUID_NOT_FOUND

BILLER_ACCOUNT_COMBINATION_ALREADY_EXISTS

BILLER_ACCOUNT_CURRENCY_CODE_COMBINATION_REJECTED

BILLER_NAME_HRUID_COMBINATION_ALREADY_EXISTS

BILLER_NAME_POSTAL_CODE_COMBINATION_ALREADY_EXISTS

BILLER_REFERENCED_SECTOR_DOES_NOT_EXIST

BILLER_INVALID_IBAN_NUMBER

BILLER_ACCOUNT_QR_IBAN_ACCOUNT_SUPPLEMENT_UNSUPPORTED

BILLER_ACCOUNT_WITH_INVALID_QR_IBAN_ACCOUNT_SUPPLEMENT_COMBINATION

BILLER_REFERENCED_CERTIFICATION_DOES_NOT_EXIST

ASSET_IMAGE_INVALID

ASSET_MIME_TYPE_DOES_NOT_CORRESPOND_TO_CONTENT_TYPE

ASSET_IMAGE_EXCEEDS_MAXIMUM_SIZES

CUSTOM_SUBSCRIPTION_FORM_CONSTRAINT_INVALID

CUSTOM_SUBSCRIPTION_FORM_TOO_MANY_FIELDS

CUSTOM_SUBSCRIPTION_FORM_INVALID

CUSTOM_SUBSCRIPTION_FORM_CHOICE_ID_NOT_UNIQUE

BILL_RECIPIENT_SUBSCRIPTION_FORM_INVALID

BC_PDF_ATTACHMENT_VALIDATION_FAILED

BC_FILENAME_HEADER_EXCEEDS_MAXIMUM_LENGTH

BC_ANOMALY_DETECTION_HEADER_INVALID

BC_EBILL_SIX_XML_SCHEMA_VALIDATION_FAILED

BC_BILLER_NOT_ACTIVE

BC_BILLER_SUBMISSION_FORBIDDEN

BC_BILLER_SUBMISSION_LIMIT_EXCEEDED

BC_BILLER_BILLRECIPIENT_SUBSCRIPTION_SUBMISSION_LIMIT_EXCEEDED

BC_BILLER_ID_INCONSISTENT

BC_BILLER_NAME_INCONSISTENT

BC_BILLER_BILLRECIPIENT_RELATION_INSUFFICIENT

BC_INVALID_DATE

BC_INVALID_REFERENCE_NUMBER

BC_REFERENCED_BILL_IS_NOT_A_BILL

BC_REFERENCE_NUMBER_FOR_REFERENCED_BILL_REQUIRED

BC_INVALID_REFERENCE_NUMBER_FOR_REFERENCED_BILL

BC_INVALID_TOTAL_AMOUNT

EBILL_SALES_CHANNEL_ECOMMERCE_NOT_ALLOWED

BC_PAYMENT_INFORMATION_INVALID_PAYMENT_DUE_DATE

BC_INCONSISTENT_CURRENCY_CODES

BC_PAYMENT_INFORMATION_INVALID_CURRENCY_CODE_FOR_QR_IBAN

BC_PAYMENT_INFORMATION_ACCOUNT_INFORMATION_INCONSISTENT

BC_PAYMENT_INFORMATION_INVALID_REFERENCE_TYPE

BC_PAYMENT_INFORMATION_INVALID_STRUCTURED_REFERENCE

BC_PAYMENT_INFORMATION_INVALID_FOR_QR_IBAN_ACCOUNT_SUPPLEMENT

BC_INVALID_TOTAL_PAYMENT_OPTION

BC_EXTERNAL_PAYMENT_BY_INSTALMENTS_ID_NOT_UNIQUE

BC_EXTERNAL_INSTALMENT_ID_NOT_UNIQUE

BC_INVALID_INSTALMENT_AMOUNT

BC_BILLER_DONATION_INQUIRIES_NOT_ALLOWED

BC_DONATION_INQUIRY_AMOUNT_INVALID

BC_DONATION_INQUIRY_AMOUNT_INCONSISTENT

BC_DONATION_INQUIRY_REFERENCED_BILL_UNSUPPORTED

BC_EXTERNAL_DONATION_PURPOSE_ID_NOT_UNIQUE

BC_EBILL_DIRECT_DEBIT_SUBMISSION_NOT_ALLOWED

BC_EBILL_DIRECT_DEBIT_REFERENCED_BILL_UNSUPPORTED

BC_EBILL_DIRECT_DEBIT_DONATION_INQUIRY_UNSUPPORTED

BC_EBILL_DIRECT_DEBIT_REMINDER_UNSUPPORTED

BC_EBILL_DIRECT_DEBIT_BILLER_ACCOUNT_UNSUPPORTED

BC_EBILL_DIRECT_DEBIT_SUBMISSION_LIMIT_UNDEFINED

BC_EBILL_DIRECT_DEBIT_SUBMISSION_LIMIT_EXCEEDED

PDF_INVALID_SIGNATURE

PDF_IS_NOT_PDFA3B

PDF_INVALID

INVALID_TOKEN_AND_ACTIVATION_CODE_COMBINATION

VALID_TO_DATE_FOR_GENERIC_BILL_RECIPIENT_SUBSCRIPTION_URL_OUT_OF_RANGE

EBILL_DIRECT_DEBIT_NETWORK_PARTNER_NOT_ALLOWED

EBILL_DIRECT_DEBIT_BILLER_NOT_ALLOWED

EBILL_DIRECT_DEBIT_SUPPORT_READ_ONLY_FOR_BILLER_ACCOUNT

EBILL_DIRECT_DEBIT_PROPOSAL_NOT_ALLOWED

EBILL_DIRECT_DEBIT_PROPOSAL_REDUNDANT

EBILL_DIRECT_DEBIT_CHARGEBACK_MODE_UNSUPPORTED

TECHNICAL_ERROR

6.66. RecipientAddress

Field Name Description Schema

streetName

required

Street name, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 70

Example: Neustadtstrasse

postalCode

required

Postal code, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 9

Example: 6025

city

required

City name, the pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 35

Example: Neudorf

countryCode

required

In format ISO 3166-1 alpha 2.

Type: String

Pattern: [A-Z]{2}
Maximum Length: 2

Example: CH

6.67. ReferencedBill

The business case can only reference bills or instalment bills.

Field Name Description Schema

businessCaseId

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

referenceNumber

required

The reference number of the referenced bill.

Type: String

Minimum Length: 1
Maximum Length: 120

Example: 2018-123456-22

6.68. Reminder

A business case of type Reminder

Field Name Description Schema

id

required

A unique ID for this business case. Property must not be given when creating a new business case.

Type: String

Pattern: BCID[0-9A-Z]{32}

Example: BCID0FB909852BBC4D06AD8336AAE87D7FC9

type

required

The type of the business case.

Type: String

Enum: Bill, InstalmentBill, Advice, CreditNote, Reminder, DonationInquiry

billerId

required

A unique ID for this biller. Property must not be given when creating a new biller.

Type: String

Pattern: BIID[0-9]{10}
Maximum Length: 14

Example: BIID0000123456

referenceNumber

required

A business case reference given by the biller. Must be unique in combination with the billerId.
The pattern restricts to a subset of XML1.0 conform characters to avoid downstream issues.

Type: String

Pattern: [\u0020-\u007E\u0085\u00A0-\uD7FF\uE000-\uFDCF\uFDF0-\uFFFD]*
Minimum Length: 1
Maximum Length: 120

Example: 2018-123456-22

referencedBill

Section 6.67, “ReferencedBill”

businessCaseDate

required

The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.

Type: date
Format: date

Example: 2017-12-22

status

The status of the business case.

Type: String

Enum: OPEN, APPROVED, REJECTED, COMPLETED, CHARGEBACK_INITIATED

subscriptionRole

Role for the activation of a subscription

Type: String

Enum: ACTIVATED_SUBSCRIPTION, NONE

totalAmount

required

Section 6.62, “OptionalAmountWithCurrency”

6.69. Sector

Field Name Description Schema

id

Unique Sector ID

Type: String

Pattern: SCID[0-9]{10}
Maximum Length: 14

Example: SCID0000000000

localizedData

Section 6.70, “SectorLocalizedData”

6.70. SectorLocalizedData

Field Name Description Schema

ger

Section 6.60, “LocalizedSectorData”

fre

Section 6.60, “LocalizedSectorData”

ita

Section 6.60, “LocalizedSectorData”

eng

Section 6.60, “LocalizedSectorData”

6.71. SubscriptionInitiationActivationCode

Field Name Description Schema

activationCode

required

Activation code provided by the user.

Type: String

Minimum Length: 6
Maximum Length: 6

Example: 123456

6.72. SubscriptionInitiationEmailAddress

Field Name Description Schema

emailAddress

required

Email address the user entered for subscription initiation

Type: String
Format: email
Minimum Length: 1
Maximum Length: 256

Example: hansmuster@muster.info

6.73. SubscriptionInitiationToken

Field Name Description Schema

subscriptionInitiationToken

required

Subscription initiation token which will be used to confirm the subscription initiation.

Type: String

Minimum Length: 36
Maximum Length: 36

Example: 0dc2ff79-db4c-4635-a4aa-f93f36ab5dbf

7. Problem Descriptions Overview

7.1. Basic Validations

UNAUTHORIZED
Status code: 401
Request failed authorization validation
All requests require a combination of a valid client certificate and an associated x-networkpartner-id header.
For more information about authentication, see network partner API documentation in Section 3.2.2, “Authentication”.

REQUEST_URL_MALFORMED
Status code: 400
Request failed url parsing
The request URL must be a valid normalized URL.
Request URLs must not contain path traversal sequences or multiple forward slashes.

NETWORK_PARTNER_UNKNOWN
Status code: 401
Network partner is unknown
The x-networkpartner-id header of the request has to reference a known and active network partner in the system.
This also requires an associated and valid client certificate, see network partner API documentation in Section 3.2.2, “Authentication”.

NETWORK_PARTNER_NOT_ACTIVE
Status code: 401
Network partner is not active
The x-networkpartner-id header of the request has to reference a known and active network partner in the system.
This also requires an associated and valid client certificate, see network partner API documentation in Section 3.2.2, “Authentication”.

REQUEST_CONTENT_TYPE_UNSUPPORTED
Status code: 415
The content type of the request is unsupported
Content type of a POST or PUT request should be set to the allowed content type for this resource, see network partner API documentation for details.
For JSON content this has to be application/json, an image asset must be one of image/png, image/jpeg or image/gif and for PDF content it has to be application/pdf. Other content types are not supported.

REQUEST_METHOD_NOT_ALLOWED
Status code: 405
HTTP method of the request is not allowed
HTTP method of a request is validated and has to be one of the supported methods for this resource, see network partner API documentation for details.
INVALID_RESOURCE
Status code: 404
Resource not found
The requested resource or endpoint does not exist.
REQUEST_PAYLOAD_EXCEEDS_MAXIMUM_SIZE
Status code: 413
Payload of the request is too large
Submitted POST or PUT request payload data should be smaller than 10'000'000 bytes, otherwise it is discarded without further analysis.
REQUEST_PAYLOAD_IS_EMPTY
Status code: 400
Payload of the request is empty
Empty payload content is not allowed for POST or PUT.
REQUEST_BODY_VALIDATION_FAILED
Status code: 400
Payload has missing or invalid values
The submitted request contains invalid or missing data in its payload and can not be processed.
REQUEST_HEADER_VALIDATION_FAILED
Status code: 400
Header is missing or has invalid value
The submitted request contains an invalid or missing header and can not be processed.
HTTP_MEDIA_TYPE_NOT_ACCEPTABLE
Status code: 406
No acceptable representation for requested http media-type
The request URL ends with an unsupported file-extension or the content-type header of the request specifies an unsupported media-type value.
=== Shared Validations
NETWORK_PARTNER_OPERATION_NOT_ALLOWED
Status code: 403
Requested operation not allowed for network partner
There are restrictions regarding access to some resources. See network partner API documentation in Section 2.3, “Primary network partners” for details.
REQUEST_QUERY_PARAMETER_VALIDATION_FAILED
Status code: 400
Request query parameter has missing or invalid values
The submitted request contains invalid or missing query parameters which can not be processed.
This problem type is used in case of missing or invalid input values.

INVALID_EMAIL
Status code: 400
Payload contains not well formed email address
The submitted request contains a not well formatted email address which can not be processed.
INVALID_CURRENCY_CODE
Status code: 400
Payload contains invalid currency code
The submitted request contains a currency code which can not be processed.
The currency code must be according to ISO-4217.

INVALID_ASSET_ID
Status code: 400
The assetId is invalid
The provided assetId is invalid as it doesn’t match the existing assetId, which was generated by the system.
ASSET_ID_MUST_NOT_BE_PROVIDED
Status code: 400
The assetId must not be provided by the client
The assetId must not be provided by the client, it will be generated by the system.
LOCALIZED_DATA_FOR_DESIRED_DEFAULT_LANGUAGE_MISSING
Status code: 400
Payload does not contain the localized data for the given default language
For the specified default language no localized data could be found in the request. Make sure for the referenced localizedData.language you also provide the data set.
=== Bill Recipient Validations
BILL_RECIPIENT_IDENTIFICATION_INVALID
Status code: 400
Provided bill recipient identification is invalid
The provided bill recipient identification object is invalid. Exactly one identifying property must be set.
BILL_RECIPIENT_EMAIL_NOT_FOUND
Status code: 404
Provided bill recipient email not found
The bill recipient email must be currently or historically available in the system.
An e-mail address is considered to be historically available if it was present in the period of 15 months up to the submission time.
For further details see network partner API documentation in Section 5.6.1, “Find events for bill recipients email address changes”.

BILL_RECIPIENT_ID_NOT_FOUND
Status code: 404
Provided bill recipient id not found
The bill recipient id must be available in the system.
BILL_RECIPIENT_HRUID_NOT_FOUND
Status code: 404
Provided bill recipient enterprise identification number (UID) not found
The provided swiss enterprise identification number (UID) of the bill recipient must be available in the system.
=== Biller Validations
BILLER_ACCOUNT_COMBINATION_ALREADY_EXISTS
Status code: 400
Biller account number combination already exists in the system
The combination of biller account and optional qrIbanAccountSupplement must not conflict with any existing account information.
BILLER_ACCOUNT_CURRENCY_CODE_COMBINATION_REJECTED
Status code: 400
Biller account / currency code combination is not allowed
The currency code of the biller account has to match the allowed currencies for the account type. Account type QR-IBAN only supports payment type 3 and therefore currency code is limited to CHF or EUR.
See the definition of payment types in https://www.six-group.com/dam/download/banking-services/standardization/sps/ig-credit-transfer-v2.0.2-en.pdf.
More information about QR in
https://www.paymentstandards.ch/dam/downloads/ig-qr-bill-en.pdf.

BILLER_NAME_HRUID_COMBINATION_ALREADY_EXISTS
Status code: 400
Biller name / UID combination already exists in the system
The combination of display name and swiss enterprise identification number (UID) from the commercial register (Handelsregister) must be unique for every biller in the system.
BILLER_NAME_POSTAL_CODE_COMBINATION_ALREADY_EXISTS
Status code: 400
Biller name / postal code combination already exists in the system
Display name and postal code combination must be unique for every biller in the system.
BILLER_REFERENCED_SECTOR_DOES_NOT_EXIST
Status code: 400
One or more referenced sectorIds do not exist
One or more referenced sectorIds do not exist. Make sure you use only existing sectorIds.
BILLER_INVALID_IBAN_NUMBER
Status code: 400
Payload contains invalid IBAN number
The submitted request contains an IBAN number which can not be processed.
BILLER_ACCOUNT_QR_IBAN_ACCOUNT_SUPPLEMENT_UNSUPPORTED
Status code: 400
IBAN can not be combined with a qrIbanAccountSupplement
Only QR-IBAN can be used in combination with qrIbanAccountSupplement.
BILLER_ACCOUNT_WITH_INVALID_QR_IBAN_ACCOUNT_SUPPLEMENT_COMBINATION
Status code: 400
Invalid constellation of QR-IBAN using account supplement
If an account supplement is provided with a QR-IBAN, there must be no empty account supplement entries for the same QR-IBAN. The same applies if there is already a QR-IBAN without an account supplement, then no QR-IBAN with an account supplement may be used.
BILLER_REFERENCED_CERTIFICATION_DOES_NOT_EXIST
Status code: 400
One or more referenced certification ids do not exist
One or more referenced certification IDs do not exist. Make sure you use only existing certification IDs.
=== Asset Validations
ASSET_IMAGE_INVALID
Status code: 400
Asset payload does not seem to be a valid image
The submitted binary data has to be a valid image.
ASSET_MIME_TYPE_DOES_NOT_CORRESPOND_TO_CONTENT_TYPE
Status code: 415
Asset mime type does not correspond to content type
The mime type of the uploaded asset does not correspond to the provided content type.
ASSET_IMAGE_EXCEEDS_MAXIMUM_SIZES
Status code: 413
Image asset maximum sizes exceeded
Image asset size must be at maximum 100'000 bytes and 1024x1024 pixels.
=== Custom Subscription Form Validations
CUSTOM_SUBSCRIPTION_FORM_CONSTRAINT_INVALID
Status code: 400
Custom subscription form contains invalid field constraint
The custom subscription form contains a field with an invalid constraint.
The constraint pattern of fields in a biller’s custom subscription form must comply to the restrictions defined in Section 6.36, “BillerSubscriptionFormField”.

CUSTOM_SUBSCRIPTION_FORM_TOO_MANY_FIELDS
Status code: 400
Custom subscription form contains too many fields
The amount of form fields within the context of a bill recipient type may not exceed three.
CUSTOM_SUBSCRIPTION_FORM_INVALID
Status code: 400
Custom subscription form invalid
The custom subscription form is invalid.
The biller’s custom subscription form contains invalid fields or field combinations.

CUSTOM_SUBSCRIPTION_FORM_CHOICE_ID_NOT_UNIQUE
Status code: 400
The identifications of different choices in custom subscription form are not unique
The different choices must be uniquely identified within a biller subscription form field of type 'CHOICE'.
=== Custom Subscription Form Data Validations
BILL_RECIPIENT_SUBSCRIPTION_FORM_INVALID
Status code: 400
The bill recipient subscription form data is invalid
The provided bill recipient subscription form data is invalid.
=== Business Case Validations
BC_PDF_ATTACHMENT_VALIDATION_FAILED
Status code: 400
Business case PDF does not contain a valid attachment
PDF file contains exactly one embedded attachment with the exact name eBill-SIX_v6.xml and none of any other version.
More attachments are allowed - and ignored - as long as they have different names.

BC_FILENAME_HEADER_EXCEEDS_MAXIMUM_LENGTH
Status code: 400
HTTP header x-filename exceeds maximum length
The request can contain a custom HTTP header x-filename of max length 99.
BC_ANOMALY_DETECTION_HEADER_INVALID
Status code: 400
HTTP header x-anomaly-detection is not set correctly
For more information, see the network partner API documentation in Section 5.3.2, “Create business case in PDF/A-3b-format”.
BC_EBILL_SIX_XML_SCHEMA_VALIDATION_FAILED
Status code: 400
XML schema validation of the eBill-SIX_v6.xml attachment failed
The eBill-SIX_v6.xml file has to be schema valid.
BC_BILLER_NOT_ACTIVE
Status code: 400
Biller is not active
The request has to refer to an active biller in the system.
BC_BILLER_SUBMISSION_FORBIDDEN
Status code: 403
Biller is currently suspended from submitting business cases
Submissions are not permitted for suspended billers.
Due to detected anomaly the biller has been suspended from submitting business cases.
For further details please contact the infrastructure provider.

BC_BILLER_SUBMISSION_LIMIT_EXCEEDED
Status code: 403
Biller has reached the specified submission limit
Submissions are not permitted after reaching a specified submission limit.
Due to reached submission limit the submission of the biller has been rejected. Check whether the 'x-anomaly-detection' header should be set.

BC_BILLER_BILLRECIPIENT_SUBSCRIPTION_SUBMISSION_LIMIT_EXCEEDED
Status code: 403
Biller has reached the maximum number of submissions allowed per bill recipient subscription
Submissions are not permitted after reaching a specified submission limit per bill recipient subscription.
The submission has been rejected because the bill recipient subscription limit has been reached.

BC_BILLER_ID_INCONSISTENT
Status code: 400
Business case has inconsistent biller id
The biller id in url must match the value in the submitted xml file.
BC_BILLER_NAME_INCONSISTENT
Status code: 400
Business case has inconsistent biller legal name
The biller legal name must match the value from the system.
The submitted biller legal name must match the value from the biller data managed in system. Otherwise the business case will be rejected.

BC_BILLER_BILLRECIPIENT_RELATION_INSUFFICIENT
Status code: 400
Biller and bill recipient do not have the required relation
Check for a sufficient biller - bill recipient relation, see network partner API documentation for details.
If none of the following conditions are met, the business case is rejected:
. There is an active biller - bill recipient relation (say, the subscription process was completed beforehand).
. There is a biller - bill recipient relation in 'initiated' status (say, a registration process was at least started by the bill recipient).
. There is no biller - bill recipient relation in 'inactive' status and the bill recipient has enabled to be found.

BC_INVALID_DATE
Status code: 400
Business case has invalid date
On the submission date, the business case date can not be more than 90 days in the past and it can not be in the future.
BC_INVALID_REFERENCE_NUMBER
Status code: 400
Business case has invalid reference number
The reference number must be unique per biller
BC_REFERENCED_BILL_IS_NOT_A_BILL
Status code: 400
Provided business case referenced bill is not a bill
The business case must not reference other business cases types but bill or instalment bill.
BC_REFERENCE_NUMBER_FOR_REFERENCED_BILL_REQUIRED
Status code: 400
Referenced number for referenced bill is missing
The reference number of the referenced bill is mandatory in case of reminder.
BC_INVALID_REFERENCE_NUMBER_FOR_REFERENCED_BILL
Status code: 400
Referenced business case has invalid reference number
The reference number of the referenced business case has to be valid.
BC_INVALID_TOTAL_AMOUNT
Status code: 400
Business case has invalid total amount
The total amount of the business case must fulfill the requirements for minimum and maximum value.
See eBill-SIX_v6.xsd for details about total amount validation.

EBILL_SALES_CHANNEL_ECOMMERCE_NOT_ALLOWED
Status code: 400
Provided sales channel is not supported
The sales channel ECOMMERCE is only allowed for single payment bills.
=== Business Case Payment Validations
BC_PAYMENT_INFORMATION_INVALID_PAYMENT_DUE_DATE
Status code: 400
Business case has invalid payment due date
On the submission date, the payment due date cannot be more than 3 years (1095 days) in the future for payment mode ebill and cannot be more than 30 days in the future for payment mode ebill direct debit and cannot be more than 90 days in the past for both payment modes. It is also not allowed to submit business cases with missing or unstructured addresses and due date after 2025-10-31.
BC_INCONSISTENT_CURRENCY_CODES
Status code: 400
Business case has inconsistent currency codes
In the entire business case only one currency is allowed.
It is not allowed to submit instalments, total amount or workflow specifications with different currencies.

BC_PAYMENT_INFORMATION_INVALID_CURRENCY_CODE_FOR_QR_IBAN
Status code: 400
The business case contains a payment information with an invalid currency code for the QR-IBAN payment type
Payment type QR-IBAN only supports payment type 3 and therefore currency code is limited to CHF or EUR.
See the definition of payment types in
https://www.six-group.com/dam/download/banking-services/standardization/sps/ig-credit-transfer-v2.0.2-en.pdf.
More information about QR in
https://www.paymentstandards.ch/dam/downloads/ig-qr-bill-en.pdf.

BC_PAYMENT_INFORMATION_ACCOUNT_INFORMATION_INCONSISTENT
Status code: 400
The business case contains a biller account that has inconsistent information
The biller account in the business case 'payment information' must match the account information in the biller master data.
BC_PAYMENT_INFORMATION_INVALID_REFERENCE_TYPE
Status code: 400
The business case has an invalid reference type
In case of structured reference the biller account has to contain a valid reference type. See definitions and documentation in eBill-SIX_v6.xsd for more details.
The allowed values for reference type are: QRR: QR-Reference, SCOR: Creditor Reference (according to ISO 11649), NON: no reference

BC_PAYMENT_INFORMATION_INVALID_STRUCTURED_REFERENCE
Status code: 400
The business case contains invalid structured reference
Validation of the structured reference failed for the given referenceType.
QRR: QR-Reference, the submitted QR-Reference must be numeric and 27 characters long. The 27th digit (check digit) must be in accordance with Modulo 10, recursive.
SCOR: Creditor Reference (according to ISO 11649), it must be alphanumeric and its maximal length is 25.
NON: no reference, only reference type NON allows empty structured reference.

BC_PAYMENT_INFORMATION_INVALID_FOR_QR_IBAN_ACCOUNT_SUPPLEMENT
Status code: 400
Payment information contains QR reference which is not valid for the existing qrIbanAccountSupplement
The submitted QR reference number must begin with the qrIbanAccountSupplement of the matching biller account.
=== Business Case Instalment Validations
BC_INVALID_TOTAL_PAYMENT_OPTION
Status code: 400
Payload contains invalid total payment option for instalments
Validation of the total payment option failed.
BC_EXTERNAL_PAYMENT_BY_INSTALMENTS_ID_NOT_UNIQUE
Status code: 400
The identifications for the instalment options are not unique
The instalment options must be uniquely identified within a business case.
BC_EXTERNAL_INSTALMENT_ID_NOT_UNIQUE
Status code: 400
The identifications for the instalments are not unique
The instalments must be uniquely identified within a business case.
BC_INVALID_INSTALMENT_AMOUNT
Status code: 400
Business case has instalment with invalid amount
The instalment amount must be positive.
=== Business Case Donation Inquiry Validations
BC_BILLER_DONATION_INQUIRIES_NOT_ALLOWED
Status code: 403
Biller is not allowed to submit donation inquiries
Submission of donation inquiries is only allowed for billers who have been granted special permission to do so.
Only billers that have been verified to be non-profit organisations (NPO) may be granted the permission to submit donation inquiries.
For further details see network partner API documentation in Section 4.1, “Biller management”.

BC_DONATION_INQUIRY_AMOUNT_INVALID
Status code: 400
Donation inquiry has invalid donation amount(s)
The donation amount(s) must be greater or equal to the minimum amount value specified for donation inquiries.
The minimum amount for donation inquiries is CHF 5.

BC_DONATION_INQUIRY_AMOUNT_INCONSISTENT
Status code: 400
The donation inquiry has inconsistent amount(s)
If proposed donation amounts are specified, the total and the payment information amount value must not be specified and vice versa. It is also not allowed to have proposed donation amounts with the same values.
BC_DONATION_INQUIRY_REFERENCED_BILL_UNSUPPORTED
Status code: 400
Submission of donation inquiry with referenced bill is not supported
A donation inquiry must not reference any other donation inquiry or business case of other types.
BC_EXTERNAL_DONATION_PURPOSE_ID_NOT_UNIQUE
Status code: 400
The identifications of different donation purposes are not unique
The different donation purposes must be uniquely identified within a donation inquiry.
=== Business Case eBill Direct Debit Validations
BC_EBILL_DIRECT_DEBIT_SUBMISSION_NOT_ALLOWED
Status code: 403
Submission of a bill with eBill Direct Debit payment not allowed
The submission of a bill with eBill Direct Debit payment requires the permission of the bill recipient.
BC_EBILL_DIRECT_DEBIT_REFERENCED_BILL_UNSUPPORTED
Status code: 400
Submission of a bill with eBill Direct Debit payment and referenced bill is not supported
eBill Direct Debit does not support referenced bills.
BC_EBILL_DIRECT_DEBIT_DONATION_INQUIRY_UNSUPPORTED
Status code: 400
Submission of a donation inquiry with eBill Direct Debit payment is not supported
eBill Direct Debit does not support donation inquiries.
BC_EBILL_DIRECT_DEBIT_REMINDER_UNSUPPORTED
Status code: 400
Submission of a reminder with eBill Direct Debit payment is not supported
eBill Direct Debit does not support reminders.
BC_EBILL_DIRECT_DEBIT_BILLER_ACCOUNT_UNSUPPORTED
Status code: 400
Biller account does not support eBill Direct Debit
Biller account has not been enabled for eBill Direct Debit.
BC_EBILL_DIRECT_DEBIT_SUBMISSION_LIMIT_UNDEFINED
Status code: 400
Submission rejected due to missing eBill Direct Debit submission limit
No eBill Direct Debit submission limit defined for biller, financial institution and currency.
BC_EBILL_DIRECT_DEBIT_SUBMISSION_LIMIT_EXCEEDED
Status code: 400
Submission exceeds the defined eBill Direct Debit submission limit
eBill Direct Debit submission limit exceeded for biller, financial institution and currency.
=== PDF Validations
PDF_INVALID
Status code: 400
Payload does not seem to be a valid PDF
The submitted binary data has to be a valid PDF document.
PDF_IS_NOT_PDFA3B
Status code: 400
PDF is not PDF/A-3b
PDFs must be provided in a valid PDF/A-3b format.
PDF_INVALID_SIGNATURE
Status code: 400
PDF does not contain a valid signature
The PDF must contain a valid PAdES-B-B-level signature.
For more information, see network partner API documentation in Section 4.2.1.4, “File specification and signatures”.

7.2. Subscription Validations

INVALID_TOKEN_AND_ACTIVATION_CODE_COMBINATION
Status code: 400
The subscription initiation token / activation code combination is invalid
The subscription initiation token and activation code combination should be valid, can only be consumed once and are only valid for a limited time.
The initiation token has a 60 minute lifetime and a maximum of 3 tries for the activation code before it is invalidated.

VALID_TO_DATE_FOR_GENERIC_BILL_RECIPIENT_SUBSCRIPTION_URL_OUT_OF_RANGE
Status code: 400
Invalid 'validTo' date
The 'validTo' date must be within the allowable date range.
The 'validTo' date can be set to a maximum of 1 year in the future.

7.3. eBill Direct Debit Validations

EBILL_DIRECT_DEBIT_NETWORK_PARTNER_NOT_ALLOWED
Status code: 403
Network partner is not allowed for eBill Direct Debit actions
eBill Direct Debit has not been enabled for the network partner.
EBILL_DIRECT_DEBIT_BILLER_NOT_ALLOWED
Status code: 403
Biller is not allowed for eBill Direct Debit actions
eBill Direct Debit has not been enabled for the biller. Neither submissions of bills with eBill Direct Debit payment nor eBill Direct Debit proposals are allowed.
EBILL_DIRECT_DEBIT_SUPPORT_READ_ONLY_FOR_BILLER_ACCOUNT
Status code: 400
ebillDirectDebitSupport is 'read only' for biller accounts
ebillDirectDebitSupport for the biller´s accounts can not be set by the network partner, neither for creating nor for updating a biller.
EBILL_DIRECT_DEBIT_PROPOSAL_NOT_ALLOWED
Status code: 403
Biller is not allowed to propose eBill Direct Debit to the bill recipient
The submission of an eBill Direct Debit proposal requires the permission of the bill recipient.
EBILL_DIRECT_DEBIT_PROPOSAL_REDUNDANT
Status code: 400
The same eBill Direct Debit proposal is already known to the system
eBill Direct Debit proposals that exactly match an existing eBill Direct Debit standing approval or an existing proposal are rejected.
EBILL_DIRECT_DEBIT_CHARGEBACK_MODE_UNSUPPORTED
Status code: 400
Provided chargeback mode is not supported
The chargeback mode NOT_SUPPORTED is only valid for business eBill users.
=== Technical Errors
TECHNICAL_ERROR
Status code: 500
Technical error on server side
Processing yielded a technical error. This is a probable server-side bug and was automatically flagged for review.

Appendix A: Roadmap API Versions

Version Go Live End of Life

Network Partner API V4

June 2023

March 2025

Network Partner API V5

July 2024

not planned

Network Partner API V6.2

July 2025

not planned

Appendix B: Changelog

B.1. Changes between v5 and v6.0.1

B.1.1. Overview

B.1.2. Documentation Changes

  • Added documentation for bill-recipient-subscription-initiations-generic-url

B.1.3. OpenAPI technical Changes

  • API Specification in Open API 3.0 instead of Swagger 2.0

  • In the Problems model, the type attribute has no prefix "/problems/" anymore

B.1.4. OpenAPI operation Changes

  • introduced new operation bill-recipient-subscription-initiations-generic-url for subscription option 'Subscription at the eBill infrastructure' to create a new bill recipient subscription generic url

  • introduced new operation bill-recipient-subscription-initiations-generic-url/{subscriptionAtEbillTokenId} for subscription option 'Subscription at the eBill infrastructure' to update an existing bill recipient subscription generic url

B.1.5. OpenAPI definition Changes

  • added new problem type:

    • VALID_TO_DATE_FOR_GENERIC_BILL_RECIPIENT_SUBSCRIPTION_URL_OUT_OF_RANGE

  • added new definition 'SubscriptionAtEbillInitiationTokenId'

  • added new definition 'BillRecipientSubscriptionInitiationGenericURL'

  • added new definition 'BillRecipientPersonalizedUrlSubscriptionResponse'

  • added new definition 'BillRecipientGenericUrlSubscriptionResponse'

  • added new optional property 'subscriptionSource' to 'BillRecipientSubscriptionStatusChangedEvent'

  • added new optional property 'subscriptionInfo' to 'BillRecipientSubscriptionStatusChangedEvent'

B.2. Changes between v6.0.1 and v6.1.0

B.2.1. Documentation Changes

  • fixed broken links

B.2.2. OpenAPI definition Changes

  • added new value 'CHARGEBACK_INITIATED' in enum property 'status' of object 'BusinessCase'

B.3. Changes between v6.1.0 and v6.2.0

B.3.1. eBill XSD Changes

  • removed IPI from the documentation as possible referenceType of accountIBANAndReference

  • removed IPI from the documentation as possible referenceStructured of accountIBANAndReference

  • paymentModeType EBILL_DEBIT renamed to EBILL_DIRECT_DEBIT

B.3.2. Documentation Changes

  • generally renamed ebillDebit to ebillDirectDebit

B.3.3. OpenAPI operation Changes

  • /billers/{billerId}/ebill-debit-proposal renamed to /billers/{billerId}/ebill-direct-debit-proposal

B.3.4. OpenAPI definition Changes

  • renamed following problem types:

    • BC_EBILL_DEBIT_SUBMISSION_NOT_ALLOWED to BC_EBILL_DIRECT_DEBIT_SUBMISSION_NOT_ALLOWED

    • BC_EBILL_DEBIT_REFERENCED_BILL_UNSUPPORTED to BC_EBILL_DIRECT_DEBIT_REFERENCED_BILL_UNSUPPORTED

    • BC_EBILL_DEBIT_DONATION_INQUIRY_UNSUPPORTED to BC_EBILL_DIRECT_DEBIT_DONATION_INQUIRY_UNSUPPORTED

    • BC_EBILL_DEBIT_REMINDER_UNSUPPORTED to BC_EBILL_DIRECT_DEBIT_REMINDER_UNSUPPORTED

    • BC_EBILL_DEBIT_BILLER_ACCOUNT_UNSUPPORTED to BC_EBILL_DIRECT_DEBIT_BILLER_ACCOUNT_UNSUPPORTED

    • BC_EBILL_DEBIT_SUBMISSION_LIMIT_UNDEFINED to BC_EBILL_DIRECT_DEBIT_SUBMISSION_LIMIT_UNDEFINED

    • BC_EBILL_DEBIT_SUBMISSION_LIMIT_EXCEEDED to BC_EBILL_DIRECT_DEBIT_SUBMISSION_LIMIT_EXCEEDED

    • EBILL_DEBIT_NETWORK_PARTNER_NOT_ALLOWED to EBILL_DIRECT_DEBIT_NETWORK_PARTNER_NOT_ALLOWED

    • EBILL_DEBIT_BILLER_NOT_ALLOWED to EBILL_DIRECT_DEBIT_BILLER_NOT_ALLOWED

    • EBILL_DEBIT_SUPPORT_READ_ONLY_FOR_BILLER_ACCOUNT to EBILL_DIRECT_DEBIT_SUPPORT_READ_ONLY_FOR_BILLER_ACCOUNT

    • EBILL_DEBIT_PROPOSAL_NOT_ALLOWED to EBILL_DIRECT_DEBIT_PROPOSAL_NOT_ALLOWED

    • EBILL_DEBIT_PROPOSAL_REDUNDANT to EBILL_DIRECT_DEBIT_PROPOSAL_REDUNDANT

    • EBILL_DEBIT_CHARGEBACK_MODE_UNSUPPORTED to EBILL_DIRECT_DEBIT_CHARGEBACK_MODE_UNSUPPORTED

  • renamed following objects:

    • EbillDebitProposal to EbillDirectDebitProposal

    • AllowedEbillDebitSubmission to AllowedEbillDirectDebitSubmission

    • EbillDebitCurrencyCode to EbillDirectDebitCurrencyCode

  • renamed property ebillDebitSupport to ebillDirectDebitSupport of object Biller and BillerAccount

  • renamed ebillDebitProposalStatus to ebillDirectDebitProposalStatus of object BillRecipientsForBillerSearchResponseItem

  • renamed allowedEbillDebitSubmissions to allowedEbillDirectDebitSubmissions of object BillRecipientsForBillerSearchResponseItem

  • renamed allowedEbillDebitSubmissions to allowedEbillDirectDebitSubmissions of object BillRecipientSubscriptionStatusChangedEvent

  • renamed following values of property subscriptionSource of object BillRecipientSubscriptionStatusChangedEvent:

    • DEBIT_STANDING_APPROVAL_FROM_PROPOSAL to DIRECT_DEBIT_STANDING_APPROVAL_FROM_PROPOSAL

    • DEBIT_STANDING_APPROVAL_FROM_REQUEST_PARAMETERS to DIRECT_DEBIT_STANDING_APPROVAL_FROM_REQUEST_PARAMETERS

B.4. Changes between v6.2.0 and v6.3.0

B.4.1. eBill XSD Changes

B.4.2. Documentation Changes

B.4.3. OpenAPI operation Changes

B.4.4. OpenAPI definition Changes

  • Punctuation characters were added to the pattern for the property "label" of the LocalizedBillerSubscriptionFormChoice

  • added problem type BC_BILLER_BILLRECIPIENT_SUBSCRIPTION_SUBMISSION_LIMIT_EXCEEDED

  • added new property 'subscriptionRole' to 'BusinessCase'