MiKaDiv Third-Party Disclosure — Response

MiKaDiv Third-Party Disclosure Response -- a module of the OpenFASTER family,

This version:
https://openfaster.org/mikadiv-vib/response
Issue Tracking:
GitHub
Editor:
Julian Nalenz

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2 September 2026, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

Abstract

This document is for developers implementing a MiKaDiv integration against this platform -- banks never see this raw response directly. It documents the format the German paying agent (via the custodian, VIB) uses to acknowledge, confirm, or reject a submitted MiKaDiv disclosure request.

1. The MiKaDiv Third-Party Disclosure Response format

VIB publishes a second schema, ThirdPartyDisclosureResponse.xsd, for the message a custodian sends back after processing a submitted request. One response file can batch responses for multiple requests: each ResponseToDisclosureForIncomeType entry answers exactly one prior request, correlated by RequestId.

1.1. Source schema

This document’s field definitions, requiredness, and enumerations are generated directly from VIB’s published ThirdPartyDisclosureResponse.xsd, the same way the Request document is generated from ThirdPartyDisclosureRequest.xsd — regenerating from the updated XSD keeps this document in lock-step with the VIB source.

Unlike the Request side, ResponseId and RequestId are typed as plain text in this schema, not the UUID-pattern-constrained type the Request side’s own RequestId uses — the wire format doesn’t itself enforce a UUID shape on either identifier here, even though VIB’s own real sample data uses UUID-looking values for both.

1.2. Identifiers

A response carries three separate identifiers, with no formal relationship declared between them by the schema:

1.3. Processing status and result

ProcessingStatus and ProcessingResult are independent fields, not one combined status. ProcessingStatus names a 6-stage pipeline (Receive → StructureValidation → ContentValidation → Plausibilization → Reporting → TaxCertification); a response can be emitted after any stage, not only the last, so an early-stage Error represents a structural/format rejection, distinct from a later business-rule rejection or a final certificate-issuance failure. ProcessingCompleted is the schema’s actual mechanism for expressing an in-progress vs. final state — a stage can succeed (ProcessingResult = Success) while ProcessingCompleted = false, signaling that further responses are still to come. There is no explicit Pending or Rejected value anywhere in this schema; both are inferred by combining ProcessingStatus, ProcessingResult, and ProcessingCompleted, never read off one field alone.

2. Response fields

Every response batches one or more ResponseToDisclosureForIncomeType entries, each answering one prior request. Fields below are grouped by where they appear in that structure.

2.1. Response envelope

Field Requiredness Type / Allowed values Description
ResponseId Required Text Unique identifier for the response. Must be unique even over subsequent files. To be defined by the custodian.
RequestId Required Text Unique identifier for the request that was sent to the custodian and is target of the response.
ResponseDate Required Date (YYYY-MM-DD) Date at which the response was generated.
ProcessingStatus Required Text Processing status.
ProcessingResult Required Text Processing result.
ProcessingCompleted Required Boolean (true / false) Whether processing of this item is fully finished (true) or further responses covering later stages are still to follow (false). Independent of ProcessingResult: a stage can succeed with ProcessingCompleted=false, meaning more responses are still to come.

2.2. Messages

Field Requiredness Type / Allowed values Description
Code Optional Text Machine-readable code identifying this message, for programmatic handling. Optional -- omitted when Text alone is sufficient.
Text Required Text Human-readable text of the message, describing what happened.
Level Required Text Severity of the message -- see the Message.Level enumeration below.
Reference Optional Text Identifier of the record, document, or field this message relates to, if applicable.

2.3. Records

Field Requiredness Type / Allowed values Description
Content Required Text The record’s actual content/value.
RecordType Required Text What kind of record this is -- see the Record.RecordType enumeration below.
RecordTypeInfo Required Text Additional free-text information about this record, complementing RecordType.

2.4. Documents

Field Requiredness Type / Allowed values Description
FilePath Required Text Path or filename of the delivered document.
ContentMimeType Required Text MIME type of the document’s content, e.g. application/pdf.
DocumentType Required Text What kind of document this is -- see the Document.DocumentType enumeration below.
Reference Optional Text Identifier of the record or request this document relates to, if applicable.

3. Enumerations

Every value that an enum-typed field in the response may carry, with its meaning.

3.1. ProcessingStatus

Value Meaning
Receive The response file itself was received by the custodian’s intake; no validation has taken place yet.
StructureValidation The request was checked against the schema’s structural/format rules.
ContentValidation The request’s content was checked against business-rule/content-level validation.
Plausibilization The request’s data was checked for plausibility against other known data.
Reporting The disclosure was reported onward to the relevant tax authority.
TaxCertification The tax certificate was issued as the final step of processing.

3.2. ProcessingResult

Value Meaning
Success This processing stage completed successfully.
Error This processing stage failed; see the accompanying Messages for details.

3.3. Message.Level

Value Meaning
Information Informational message; no action required.
Warning Warning message, flagging a non-fatal issue worth reviewing.
Error Error message, describing why processing failed at this stage.

3.4. Record.RecordType

Value Meaning
TaxDocumentIdentifier The tax certificate’s own official reference number (the "Ordnungsnummer"), see the Identifiers section above.
Other A record whose content doesn’t fit any of the schema’s other defined record types.

3.5. Document.DocumentType

Value Meaning
TaxCertificate The issued tax certificate document itself.
Information A supplementary informational document, not itself the tax certificate.
Other A document that doesn’t fit any of the schema’s other defined document types.

4. Known gaps in this schema

Worth disclosing rather than silently working around: ResponseToDisclosureForIncomeType is documented in the XSD itself as "Not for direct use" (a base type, presumably meant to be subtyped per income category), yet no derived subtype exists and the schema’s own root element references this exact type directly — in practice, this base type is the only one ever used. Also, the only real sample VIB has published for this schema (Sample1-TaxCertificateSuccess.xml) demonstrates the full-success path only — there is no published example of an Error or a ProcessingCompleted = false response, so this document’s coverage of those states is derived from the schema’s own structure, not confirmed against a real example.