Class HummClient

The primary object used to make requests to Humm.

Inheritance

Object

HummClient

Implements

IHummClient

IDisposable

Inherited Members

Object.Equals(Object)

Object.Equals(Object, Object)

Object.GetHashCode()

Object.GetType()

Object.MemberwiseClone()

Object.ReferenceEquals(Object, Object)

Object.ToString()

Namespace: Yort.Humm.InStore

Assembly: Yort.Humm.InStore.dll

Syntax

public sealed class HummClient : IHummClient, IDisposable

Remarks

Each instance of this class represents a single POS device, if being used from a centralised service or a web server then you will need to create an instance for each device, either per-request or pooled as neccesary.

Details about the device the instance represents are provided via the HummClientConfiguration instance passed into the constructor.

Note that financial/dollar values should be expressed as Decimal in their dollar & cents format, i.e $20.50 should be set as 20.50 on a request object, the library will take care of converting this to a cents value for Humm.

This object makes requests via the REST interface, SOAP is not currently supported by this library.

See the Humm API documentation at; https://docs.shophumm.com.au/pos/getting-started/

Constructors

HummClient(HummClientConfiguration)

Constructs a new instance using the specified configuration.

Declaration

public HummClient(HummClientConfiguration config)

Parameters

Type	Name	Description
HummClientConfiguration	config	A HummClientConfiguration specifying details of how this instance is configured.

Exceptions

Type	Condition
ArgumentNullException	Thrown if config is null, or BaseApiUrl is null.

Methods

CreateKeyAsync(CreateKeyRequest)

Requests a new device key from Humm using the (initialisation) device token created in the Humm Seller (merchant) portal.

Declaration

public Task<CreateKeyResponse> CreateKeyAsync(CreateKeyRequest request)

Parameters

Type	Name	Description
CreateKeyRequest	request	A CreateKeyRequest instance containing details of the request to make.

Returns

Type	Description
Task<CreateKeyResponse>	A CreateKeyResponse instance containing the Humm response. See the Humm documentation at https://docs.shophumm.com.au/pos/api/create_key/

Remarks

If the AutoUpdateClientToken argument is true and the request is successsful, the client will automatically call SetDeviceKey(String) with the value of Key for you, ensuring all future calls made with this client instance use the new token.

Exceptions

Type	Condition
ArgumentNullException	Thrown if request, DeviceToken or PosVendor is null.
ArgumentException	Thrown if DeviceToken or PosVendor is an empty string or contain only whitespace characters.
ObjectDisposedException	Thrown if this instance has been disposed.
HummResponseSignatureException	Thrown if the response signature cannot be validated.
HttpRequestException	Thrown if an HTTP protocol level or HttpClient pipeline error occurs.

See Also

CreateKeyRequest

CreateKeyResponse

SetDeviceKey(String)

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration

public void Dispose()

Remarks

Once disposed, calls to most methods on this object with throw ObjectDisposedException.

This method is safe to call multiple times in series. It is not guarateed to call in parallel, though no known issues exist.

InviteAsync(InviteRequest)

Sends an SMS to the customer's mobile phone inviting them to sign-up as a Humm customer.

Declaration

public Task<InviteResponse> InviteAsync(InviteRequest request)

Parameters

Type	Name	Description
InviteRequest	request	A InviteRequest instance.

Returns

Type	Description
Task<InviteResponse>	A InviteResponse.

Exceptions

Type	Condition
ArgumentNullException	Thrown if request is null.
HummResponseSignatureException	Thrown if the response signature cannot be validated.
ObjectDisposedException	Thrown if this instance has been disposed.
InvalidOperationException	Thrown if this instance has not been initialised with a non-null device key (SetDeviceKey(String) and DeviceKey)..
HttpRequestException	Thrown if an HTTP protocol level or HttpClient pipeline error occurs.

See Also

InviteRequest

InviteResponse

ProcessAuthorisationAsync(ProcessAuthorisationRequest)

Requests an authorisation (for payment) be processed.

Declaration

public Task<ProcessAuthorisationResponse> ProcessAuthorisationAsync(ProcessAuthorisationRequest request)

Parameters

Type	Name	Description
ProcessAuthorisationRequest	request	A ProcessAuthorisationRequest instance.

Returns

Type	Description
Task<ProcessAuthorisationResponse>	A ProcessAuthorisationResponse instance.

Remarks

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'.

If the AutoHandlePendingResponse value is true and the response indicates a Pending status then this call will raise the 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 PendingAuthorisation event. In this case the response returned to the caller will be the final status (success/failure/error).

If AutoHandlePendingResponse is false then the first response will be returned to the caller and if the status is Pending it is up to the caller to repeat the request until a final state is reached.

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/

Exceptions

Type	Condition
ArgumentNullException	Thrown if request is null.
HummResponseSignatureException	Thrown if the response signature cannot be validated.
ObjectDisposedException	Thrown if this instance has been disposed.
InvalidOperationException	Thrown if this instance has not been initialised with a non-null device key (SetDeviceKey(String) and DeviceKey)..
HttpRequestException	Thrown if an HTTP protocol level or HttpClient pipeline error occurs.

See Also

PendingAuthorisation

ProcessAuthorisationRequest

ProcessAuthorisationResponse

ProcessSalesAdjustmentAsync(ProcessSalesAdjustmentRequest)

A sales adjustment is used to refund money in the case of an item that is returned or fails to ship etc.

Declaration

public Task<ProcessSalesAdjustmentResponse> ProcessSalesAdjustmentAsync(ProcessSalesAdjustmentRequest request)

Parameters

Type	Name	Description
ProcessSalesAdjustmentRequest	request	A ProcessSalesAdjustmentRequest instance.

Returns

Type	Description
Task<ProcessSalesAdjustmentResponse>	A ProcessSalesAdjustmentResponse instance.

Remarks

A sales adjustment can be used for full or partial refund of previously approved ProcessAuthorisationAsync(ProcessAuthorisationRequest).

See the Humm documentation at https://docs.shophumm.com.au/pos/api/process_sales_adjustment/ and https://docs.shophumm.com.au/pos/api_information/retries_and_idempotency/

Exceptions

Type	Condition
ArgumentNullException	Thrown if request is null.
HummResponseSignatureException	Thrown if the response signature cannot be validated.
ObjectDisposedException	Thrown if this instance has been disposed.
InvalidOperationException	Thrown if this instance has not been initialised with a non-null device key (SetDeviceKey(String) and DeviceKey)..
HttpRequestException	Thrown if an HTTP protocol level or HttpClient pipeline error occurs.

See Also

ProcessAuthorisationAsync(ProcessAuthorisationRequest)

ProcessSalesAdjustmentReversalAsync(ProcessSalesAdjustmentReversalRequest)

ProcessSalesAdjustmentReversalAsync(ProcessSalesAdjustmentReversalRequest)

This endpoint is used to process a reversal of a ProcessSalesAdjustmentAsync(ProcessSalesAdjustmentRequest) at the point-of-sale

Declaration

public Task<ProcessSalesAdjustmentReversalResponse> ProcessSalesAdjustmentReversalAsync(ProcessSalesAdjustmentReversalRequest request)

Parameters

Type	Name	Description
ProcessSalesAdjustmentReversalRequest	request	A ProcessSalesAdjustmentReversalRequest instance.

Returns

Type	Description
Task<ProcessSalesAdjustmentReversalResponse>	A ProcessSalesAdjustmentReversalResponse instance.

Remarks

This is typically used to undo a refund in the case where it was made in error, or where the outcome was unknown (due to a network timeout/error) and an idempotent retry is not desirable. See the Humm documentation at; https://docs.shophumm.com.au/pos/api_information/retries_and_idempotency/

Exceptions

Type	Condition
ArgumentNullException	Thrown if request is null.
HummResponseSignatureException	Thrown if the response signature cannot be validated.
ObjectDisposedException	Thrown if this instance has been disposed.
InvalidOperationException	Thrown if this instance has not been initialised with a non-null device key (SetDeviceKey(String) and DeviceKey)..
HttpRequestException	Thrown if an HTTP protocol level or HttpClient pipeline error occurs.

See Also

ProcessSalesAdjustmentAsync(ProcessSalesAdjustmentRequest)

SendReceiptAsync(SendReceiptRequest)

Registers a POS transaction number against a prior authorisation.

Declaration

public Task<SendReceiptResponse> SendReceiptAsync(SendReceiptRequest request)

Parameters

Type	Name	Description
SendReceiptRequest	request	A SendReceiptRequest instance.

Returns

Type	Description
Task<SendReceiptResponse>	A SendReceiptResponse instance containing the result of the request.

Remarks

This method is only used if the ClientTransactionReference was a temporary value and not a POS transaction number. In this case, when the POS finally assigns a permanent transaction number this method can be called to update the payment with the relevant reference.

See the Humm documentation at https://docs.shophumm.com.au/pos/api/send_receipt/ and https://docs.shophumm.com.au/pos/api_information/retries_and_idempotency/

Exceptions

Type	Condition
ArgumentNullException	Thrown if request is null.
HummResponseSignatureException	Thrown if the response signature cannot be validated.
ObjectDisposedException	Thrown if this instance has been disposed.
InvalidOperationException	Thrown if this instance has not been initialised with a non-null device key (SetDeviceKey(String) and DeviceKey)..
HttpRequestException	Thrown if an HTTP protocol level or HttpClient pipeline error occurs.

See Also

ProcessAuthorisationAsync(ProcessAuthorisationRequest)

SetDeviceKey(String)

Sets the device key used for generating digital signatures.

Declaration

public void SetDeviceKey(string deviceKey)

Parameters

Type	Name	Description
String	deviceKey	A string containing the device key previously returns by a CreateKeyAsync(CreateKeyRequest) request.

Remarks

The device key is usually provided via the HummClientConfiguration constructor argument if known before client is created. This method is typically used when registering a new device via CreateKeyAsync(CreateKeyRequest) and not electing to have the token automatically applied.

Null can be provided to clear the currently assigned device key (if any), prior to calling CreateKeyAsync(CreateKeyRequest) to generate a new device key.

See Also

CreateKeyAsync(CreateKeyRequest)

HummClientConfiguration

Events

PendingAuthorisation

Raised when a ProcessAuthorisationResponse is received with a status of Pending and the AutoHandlePendingResponse property of the request was true.

Declaration

public event EventHandler<PendingAuthorisationEventArgs> PendingAuthorisation

Event Type

Type	Description
EventHandler<PendingAuthorisationEventArgs>

Remarks

While the AutoHandlePendingResponse option frees the client from having to handle the repeat API call logic to Humm in the case of a pending 'big things' purchase flow, this event can be used by the client to update it's UI to indicate the pending status and/or when the next recheck will occur if it desires.

Implements

IHummClient

System.IDisposable

See Also

HummClientConfiguration

IDisposable