A charge is created by providing order details (if not existing invoice) and a payment source. The response is a HTTP 200 if the request is understood and processed by Billwerk+Optimize, but not necessarily with succesful charge. The HTTP status code relates to the communication with Billwerk+Optimize and Billwerk+Optimizes ability to process the request, not the result of the charge. The result of the charge operation should be determined from the state parameter which will be settled, authorized, failed or pending. Errors relating to the payment method or acquirer processing, e.g. insufficient funds, or processing errors at the acquirer, will result in a HTTP 200 OK with a charge object with state failed and error indication in the error_state and error parameters. If the charge is failed it can be retried with the same handle. The pending state is only used for asynchronous payment methods (e.g. MobilePay Subscriptions) where the result of the charge operation is not known immediately. Webhooks must be used to listen for the state change. Card payments are always synchronous.
Even though the handle can be up to 255 characters it is not recommended to use more than 20 characters as this will allow for the use of handle as reference on bank statements without truncation.
Below is given recommended error handling for the charge operation.
| Error | Handling |
|---|---|
Communication error (no HTTP respoonse)or HTTP server error 5xx | Retry operation immediately or later, preferably with an idempotency key. Retry is important if instant settle is used as the settle operation can actually have gone through so money has been moved. |
HTTP 400 client error and error code 147 | The stored payment method referenced is in state failed, and it is not allowed to make charges because of scheme or payment provider rules. E.g. Visa Token Service token. Treat this the same way as a hard decline and mark payment method as failed and not eligible for use. |
Other HTTP 4xx client errors | Check your implementation. One error that can be expected is that invoice is already authorized or settled if no idempotency key is used and there has been a retry. |
Other non 200 HTTP response | Something is wrong. Handle as for communication error and contact Billwerk+Optimize if the problem persists. |
state = authorized or state = settled | Success |
state = pending | The charge has successfully been sent for asynchronous processing. The result of the charge will be given in webhook, or the state of the charge can be polled with get charge. |
error_state = hard_declined | The charge operation has been declined by acquirer or issuer. The hard decline means that no further attempts should be made using the same payment method. All subsequent attempts will fail. See below for potential scheme fees in case of excessive retrying. |
error_state = soft_declined | The charge operation has been declined by acquirer or issuer with a soft decline. This is ususally due to insufficient funds. Future attempts may succeed. See below for recommendation regarding retries and potential scheme fee in case of excessive retrying. |
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 a successful charge, 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 if the error persists for days the payment method should be marked as failed. |
Retries
Schemes have implemented fees on excessive retries to enforce their rules prohibiting excessive payment reattempts. Visa’s rules broadly prohibit more than 15 retries of a single payment over 30 calendar days. Mastercard disallows more than 10 reattempts within a 24-hour period. We recommend not to retry hard declined cards and limit retrying on soft declines to once every 24 hours and at most 15 times.
Errors
The operation can generate the following errors beside the generic HTTP error codes described here.
| Error code | HTTP code | Description |
|---|---|---|
79 | 400 | Invoice already settled |
105 | 400 | Invoice already authorized |
29 | 400 | Invoice already cancelled |
71 | 400 | The customer is deleted |
11 | 400 | Duplicate customer handle provided |
18 | 400 | Customer could not be determined from either reference, create customer object or payment method source |
99 | 400 | Customer object given does not match handle of existing customer or handle given does not match existing customer reference |
40 | 404 | Payment method not found |
34 | 400 | Invalid card token |
24 | 400 | No amount or order lines was provided |
80 | 400 | Existing charge has processing transactions |
100 | 400 | Amount change is not allowed when charging an existing invoice |
72 | 400 | Currency change not allowed on existing invoice or charge |
147 | 400 | Stored payment method is in failed state and it is not allowed to retry because of scheme or payment provider rules |