Error Handling

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:

1InitiatedIndicates the transaction is created locally and has not yet been transferred to the integration.
2PendingThe transaction has been transferred to the integration but is not yet confirmed.
3SucceededThe transaction is confirmed with the full amount paid or overpaid.
4FailedIndicates a processing error occurred during the transaction.
5CancelledThe transaction was cancelled, rejected, or declined.
6ExpiredThe 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:

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