/// <summary>
/// Requests an authorisation (for payment) be processed.
/// </summary>
/// <remarks>
/// <para>This method is used to request a payment contract be setup for a specified amount using an approval code generated by the customer's device.
/// It is the most common API call made to Humm in a 'happy path'.
/// </para>
/// <para>If the <see cref="ProcessAuthorisationRequest.AutoHandlePendingResponse"/> value is true and the response indicates a <see cref="RequestStates.Pending"/> status then
/// this call will raise the <see cref="PendingAuthorisation"/> event, wait for the specified retry interval, and the re-make the request again. This will be repeated until a
/// non-pending status is returned, or an error is thrown from one of the handlers for the <see cref="PendingAuthorisation"/> event. In this case the response returned
/// to the caller will be the final status (success/failure/error).
/// </para>
/// <para>
/// If <see cref="ProcessAuthorisationRequest.AutoHandlePendingResponse"/> is false then the first response will be returned to the caller and if the status is <see cref="RequestStates.Pending"/>
/// it is up to the caller to repeat the request until a final state is reached.
/// </para>
/// <para>See the Humm documentation at https://docs.shophumm.com.au/pos/api/process_authorisation/ and https://docs.shophumm.com.au/pos/api_information/retries_and_idempotency/ </para>
/// </remarks>
/// <param name="request">A <see cref="ProcessAuthorisationRequest"/> instance.</param>
/// <returns>A <see cref="ProcessAuthorisationResponse"/> instance.</returns>
/// <seealso cref="PendingAuthorisation"/>
/// <seealso cref="ProcessAuthorisationRequest"/>
/// <seealso cref="ProcessAuthorisationResponse"/>
/// <exception cref="System.ArgumentNullException">Thrown if <paramref name="request"/> is null.</exception>
/// <exception cref="HummResponseSignatureException">Thrown if the response signature cannot be validated.</exception>
/// <exception cref="System.ObjectDisposedException">Thrown if this instance has been disposed.</exception>
/// <exception cref="System.InvalidOperationException">Thrown if this instance has not been initialised with a non-null device key (<see cref="SetDeviceKey(string)"/> and <see cref="HummClientConfiguration.DeviceKey"/>)..</exception>
/// <exception cref="System.Net.Http.HttpRequestException">Thrown if an HTTP protocol level or <see cref="System.Net.Http.HttpClient"/> pipeline error occurs.</exception>
public async Task <ProcessAuthorisationResponse> ProcessAuthorisationAsync(ProcessAuthorisationRequest request)
{
GuardClientState();
while (true)
{
var response = await SendRequest <ProcessAuthorisationRequest, ProcessAuthorisationResponse>(RelativePath_ProcessAuthorisation, request).ConfigureAwait(false);
#pragma warning disable CA1062 // Validate arguments of public methods
if (request.AutoHandlePendingResponse && response.Status == RequestStates.Pending)
#pragma warning restore CA1062 // Validate arguments of public methods
{
OnPendingAuthorisation(response, request);
await Task.Delay(response.RetryDuration * 1000).ConfigureAwait(false);
}
else
{
return(response);
}
}
}
private void OnPendingAuthorisation(ProcessAuthorisationResponse response, ProcessAuthorisationRequest request)
{
PendingAuthorisation?.Invoke(this, new PendingAuthorisationEventArgs(request.ClientTransactionReference, response.RetryDuration, response.TrackingData));
}
