The response is a HTTP 200 if the request is understood and processed by Billwerk+Optimize, but not necessarily with success. The HTTP status code relates to the communication with Billwerk+Optimize and Billwerk+Optimizes ability to process the request, not the result of the refund. The result of the refund operation should be determined from the state parameter which will be refunded, failed or processing (only asynchronous payment methods). The error state and error reason can be found in error_state and error parameters.
Error handling if a refund operation fails is important, as this is a money carrying operation. We recommend using an idempotency key for retrying the same refund operation. This is especially important for partial refunds so a retry does not result in additional partial refund. Our recommendations for error handling is given in the tables below.
| Error | Handling |
|---|---|
Communication error (no HTTP respoonse)or HTTP server error 5xx | Retry operation immediately or later, preferably with an idempotency key to avoid multiple refunds if a partial refund is performed. Retry is important as the refund operation can actually have gone through so money has been moved. |
HTTP client error 4xx | Check your implementation. One error that can be expected for full refunds, and if an idempotency key is not used is “Refund amount too high”, as described below. For a retry it can be interpreted as success if the idempotency key is not used. |
Other non 200 HTTP response | Something is wrong. Handle as for communication error and contact Billwerk+Optimize if the problem persists. |
state = refunded | Success |
state = processing | Success - The payment type has asynchronous refunds (e.g. MobilePay Subscriptions). The result of the refund will be deliverd in webhook. |
error_state = hard_declined | The refund operation has been declined by acquirer or issuer. No further attempts with same arguments will succeed. |
error_state = processing_error | A processing error can happen if something goes wrong at, or in between, any of the parties involved in a transaction. A processing error can potentially have resulted in an approved refund, but the result never reaches Billwerk+Optimize. E.g. a timeout somewhere in the chain. Processing errors leading to transactions actually having been completed without knowing the result is frustrating, but luckily quite rare. We recommend to retry later on a processing error, but only a few times. |
Errors
The operation can generate the following errors beside the generic HTTP error codes described here.
| Error code | HTTP code | Description |
|---|---|---|
31 | 404 | Invoice not found |
64 | 400 | Invoice not settled |
65 | 400 | The refund amount exceeds settled amount minus already refunded or credited amounts |
80 | 400 | Invoice has processing transactions - an asynchronous refund is in progress - result will be reported in webhook |