Retries & Idempotency

Process Authorisation

On calls to the ProcessAuthorisation API, the pre-approval code (as specified by the x_pre_approval_code parameter) is flagged as 'used'. Once used, a pre-approval code can never again be reused to get consumer finance. If an already used pre-approval code is passed through on a separate call to ProcessAuthorisation (with a different digital-signature to the initial call), a status code of 'FPRA22' (see Status Codes)) will be returned - the Barcode has already been used.

There is one exception to the above; In a timeout scenario (e.g. where the bank takes longer than expected to process the initial payment), the same pre-approval can be passed through in a subsequent retry attempt - as long as the request is exactly the same, that is, with a digital-signature that matches the initial call. In this scenario, the ProcessAuthorisation API will instead return the current authorisation status. It is therefore safe to call the ProcessAuthorisation API using the same pre-approval code (and same message with the same digital-signature) until a status is returned.

Send Receipt

The SendReceipt API simply associates a POS transaction reference to the authorisation. An authorisation can have zero-to-many POS transaction references, which means that this API can be called as many times as needed to associate more POS transaction references to the authorisation.

Process Sales Adjustment

Similar to the ProcessAuthorisation API, there are certain scenarios, such as timeouts and network failures, where we might need to 'retry' a single sales adjustment attempt. However, unlike the ProcessAuthorisation API, it is actually valid to call this API multiple times e.g. multiple partial refunds for individual line-items.

For this reason, every sales adjustment which is not a reattempt must specify a unique transaction reference for the adjustment, x_pos_transaction_ref, in addition to the original purchase reference, x_purchase_ref. The x_pos_transaction_ref field allows humm to determine if this is a retry on a single sales adjustment attempt, or if it's a new sales adjustment attempt.

In the event that a response is not received from humm, the same refund request may be sent again, ensuring that the x_pos_transaction_ref field is the same as the original request.

📘

As per the Process Sales Adjustment API reference, x_purchase_ref is defined as follows:

The original transaction reference.
It can either be the x_pos_transaction_ref that was passed through as part of the ProcessAuthorisation request (or the SendReceipt request), or the humm purchase number that was returned from the call to ProcessAuthorisation. In the case of the former, the x_pos_transaction_ref must be unique among all sellers in a chain of sellers. In the case of the latter, the POS software would be required to store the x_purchase_number returned by ProcessAuthorisation.