Settle an authorized charge. This is the second step in a two-step payment process with an authorization and subsequent settle. Optionally the amount and order lines of the charge can be adjusted. Multiple settles can be performed up to the authorized amount if the payment method allows this. If order lines are provided the first settle will change the order lines and subsequent settles will add the order lines provided.
Errors relating to acquirer declines and acquirer processing errors will result in a HTTP 200 OK with an error description in the error_state and error parameters. For processing errors the state is left unchanged. For irrecoverable acquirer declines for the first settle, the state of the charge will be changed to failed. Use the error_state, error and state parameters to determine if the operation was successful. If only one settle is performed the state parameter can solely be used. It should be settled after successful settle. For multiple settles the state is already settled so the error and/or error_state parameter must be used to determine success.
Error handling if a settle operation fails is important, as this is a money carrying operation. We recommend using an idempotency key for retrying the same settle operation. This is especially important for partial settles so a retry does not result in additional partial captures. 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 settles if a partial settle is performed. Retry is important as the settle 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 settles, and if an idempotency key is not used is “Invoice already settled”, 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 = settled and error_state = <null> | Success |
error_state = hard_declined | The settle operation has been declined by acquirer or issuer. No further attempts should be made. |
error_state = soft_declined | In rare occasions the result of a settle operation can be a soft decline (possibly recoverable). A retry could be performed later, but is not required, as no money has been moved. Most notable soft decline is for acquirer Nets and Forbrugsforeningen cards. Partial captures need to be 24 hours apart, otherwise the following acquirer_code is returned in addition to the soft decline 999. In this case wait until 24 hours has elapsed since last settle. When retrying a new idempotency key must be used as it is a separate transaction. |
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 settle, 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 |
79 | 400 | Invoice already settled - no remaining authorized amount to settle |
106 | 400 | Invoice not authorized |
102 | 400 | New amount provided is higher than the authorized amount |
129 | 400 | Multiple settles not allowed - invoice has already been settled once and payment method does not allow multiple settles |
130 | 400 | Partial settle not allowed - payment method does not allow a partial settle |