Validation Metadata

Validation metadata is included in KontoCloud API responses to help interpret how the system processed a request. It provides additional context about the request outcome and appears in both successful and failed responses. This metadata supports consistent handling on the merchant side by clarifying whether a request was accepted, partially processed, or rejected, and by indicating how specific request elements were treated during validation.

The presence of this metadata does not affect the core response but serves as a complement to it. It is particularly useful in identifying issues such as missing fields, unexpected parameters, or failed validations without requiring merchants to perform manual debugging. Even in successful scenarios, the metadata can include identifiers that aid in tracing or linking the request across different endpoints or systems.

"additionalInformation" Validation Metadata

The additionalInformation object is included in API responses to provide supplementary, context-specific data which supports integration diagnostics and troubleshooting. Its presence and contents vary depending on the outcome of the request and can appear in both success and failure scenarios. This object can contain a range of metadata elements such as transaction identifiers, unrecognized request fields, validation errors, or security-related parameters. These values are intended to help merchants identify the root cause of a failed request, track transaction flow, and apply appropriate logic for handling or recovery.

In successful responses, the object can contain metadata such as requestId, which helps with request tracing and logging. For example, in a successful 1.45 Issue Token response:

{
   ...
  "responseCode": "0000",
  "responseDescription": "Successful execution.",
  "additionalInformation": {
    "requestId": "aff2728481a181dc36daedc14055b516"
  }
}

In case of a successful processing (response code 0000 - Successful execution.), some fields (example, paymentProviderResponse) will be returned at root-level response. In contrast, for failed transactions (with transaction status FAILED), the failed parameters will be returned in the additionalInformation object as a additionalInformation.paymentProviderResponse.

Observe below the paymentProviderResponse parameter in the 1.29 Capture:

Successful response:

{
   ...
   "statusCode":"CAPTURED",
   "statusReason":"Request successfully processed in Merchant in Integrator Test Mode",
   "paymentProviderResponse":{
      "result":{
         "code":"000.100.110",
         "description":"Request successfully processed in \u0027Merchant in Integrator Test Mode\u0027"
      },
   ...
   "responseCode":"0000",
   "responseDescription":"Successful execution.",
   "additionalInformation":{
      "requestId":"01980d30dc754b0cb3a531a95c25872a"
   }
}
}

Unsuccessful response:

{
   ...
   "statusCode":"FAILED",
   "statusReason":"Request failed.",
   ...
   "responseCode":"0006",
   "responseDescription":"External payment provider failed to process the operation.",
   "additionalInformation":{
      "requestId":"01980d30dc754b0cb3a531a95c25872a",
      "paymentProviderResponse": "Operation failed."
   }
}
}

If an API request contains fields that are not recognized or supported, these are ignored during processing but echoed back in the additionalInformation object under unrecognizedFields array to support debugging.

{
   ...
    "additionalInformation": {
            "requestId": "ddaefacc12ea476c802cb0856ba1fcd5",
            "unrecognizedFields": [
                "useDifferentBillingAddress",
                "customerFullName",
                "emailAddress",
                "addr1",
                "houseNumber",
                "city",
                "countryCode",
                "postCode"
            ]
    }
}    

In validation failure cases, the object may contain an array with one or more items describing which fields were invalid and why. For example, in responses with code 0001 - One or more of the required fields have not been sent or some fields were not in a correct format: { list of all required or incorrect fields }., the additionalInformation object includes an errors array, where each item provides a name and a corresponding message describing the issue.

{
"errors": [
    {
        "name": "Request Parameter Name",
        "message": "Error Message"
    }
    ]
}

The additionalInformation object serves as a flexible container for contextual response data. Its structure is dynamic and depends on the nature of the request, the fields provided, and the response status. Merchants should implement logic to read this object consistently, regardless of whether the request was a success or not, to ensure traceability, validation awareness, and smoother error handling.

tip

For a full overview of KontoCloud's Response Codes, please refer to the Lookups section.