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 thex_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, thex_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 thex_purchase_number
returned by ProcessAuthorisation.
Updated 4 months ago