Billwerk+ Transform expects an error object to be returned for any HTTP request that does not result in a successful outcome. This ensures that there is clear communication regarding the nature of the issue and what may have caused it. The error object should conform to the structure defined earlier in this document and should be included in the response body of any HTTP response with a status code that indicates a failure (typically any 4xx or 5xx status codes).

Error Response Structure

Errors are returned in a JSON format that includes key details about the nature and specifics of the error encountered. Here is the general structure of an error response:

{
  "ErrorCode": 8,
  "ErrorMessage": "verify3D failed. 3D Secure failed: Declined by card issuing bank",
  "PspErrorCode": "422",
  "ReceivedAt": "2024-06-18T20:23:59+02:00",
  "Status": 4
}

This example shows a common error related to 3D Secure verification where the transaction was declined by the card-issuing bank.

Fields Description

ErrorCode: An integer which provides specific details about the error type.
ErrorMessage: A description of the error, providing context or details about why the error occurred.
PspErrorCode: The error code is returned from the Payment Service Provider if applicable.
ReceivedAt: The timestamp in UTC when the error was received.
Status: Describes the transaction status.

Status Values

Transaction statuses provide a snapshot of the payment transaction state when an error occurs:

Code	Value	Description
1	Initiated	Indicates the transaction is created locally and has not yet been transferred to the integration.
2	Pending	The transaction has been transferred to the integration but is not yet confirmed.
3	Succeeded	The transaction is confirmed with the full amount paid or overpaid.
4	Failed	Indicates a processing error occurred during the transaction.
5	Cancelled	The transaction was cancelled, rejected, or declined.
6	Expired	The transaction was not completed within the expected time frame and has expired.

Error Codes Values

The error codes include specific error codes that describe common issues encountered during transaction processing:

Code	Description
0	Unmapped Error
1	Limit Exceeded
2	Bearer Invalid
3	Bearer Expired
4	Invalid Country
5	Invalid Amount
6	Invalid Currency
7	Login Error
8	Invalid Data
9	Insufficient Balance
10	Already Executed
11	Invalid Preconditions
12	Internal Error
13	Internal Provider Error
14	Rate Limit
15	Invalid Configuration
16	Permission Denied
17	Cancelled
18	Rejected
19	PSP Connection Problem
20	Invalid BIC
21	Invalid IBAN
22	PSP Connection Timeout
23	Invalid National Id Number
24	Failed Customer Update
25	Reiterated Internally