/// <summary>
/// Requests a new device key from Humm using the (initialisation) device token created in the Humm Seller (merchant) portal.
/// </summary>
/// <param name="request">A <see cref="CreateKeyRequest" /> instance containing details of the request to make.</param>
/// <returns>
/// <para>A <see cref="CreateKeyResponse" /> instance containing the Humm response.</para>
/// <para>See the Humm documentation at https://docs.shophumm.com.au/pos/api/create_key/ </para>
/// </returns>
/// <remarks>
/// If the <see cref="CreateKeyRequest.AutoUpdateClientToken" /> argument is true and the request is successsful, the client will automatically call <see cref="SetDeviceKey(string)" /> with the value of <see cref="CreateKeyResponse.Key" /> for you, ensuring all future calls made with this client instance use the new token.
/// </remarks>
/// <seealso cref="CreateKeyRequest" />
/// <seealso cref="CreateKeyResponse" />
/// <seealso cref="SetDeviceKey(string)" />
/// <exception cref="System.ArgumentNullException">Thrown if <paramref name="request"/>, <see cref="CreateKeyRequest.DeviceToken"/> or <see cref="CreateKeyRequest.PosVendor"/> is null.</exception>
/// <exception cref="System.ArgumentException">Thrown if <see cref="CreateKeyRequest.DeviceToken"/> or <see cref="CreateKeyRequest.PosVendor"/> is an empty string or contain only whitespace characters.</exception>
/// <exception cref="System.ObjectDisposedException">Thrown if this instance has been disposed.</exception>
/// <exception cref="HummResponseSignatureException">Thrown if the response signature cannot be validated.</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 <CreateKeyResponse> CreateKeyAsync(CreateKeyRequest request)
{
if (_IsDisposed)
{
throw new ObjectDisposedException(nameof(HummClient));
}
request.GuardNull(nameof(request));
request.FillFromConfig(_Config);
if (_Config.AutoValidateRequests)
{
request.Validate();
}
#pragma warning disable CS8604 // Possible null reference argument.
using (var sigGen = new Hmac256SignatureGenerator(request.DeviceToken))
#pragma warning restore CS8604 // Possible null reference argument.
using (var writer = new SignedRequestWriter(sigGen))
{
var response = await SendRequest <CreateKeyRequest, CreateKeyResponse>(RelativePath_CreateKey, request, writer, sigGen).ConfigureAwait(false);
if (request.AutoUpdateClientToken && !String.IsNullOrEmpty(response.Key) && response.Status == RequestStates.Success)
{
SetDeviceKey(response.Key);
}
return(response);
}
}
public void Writes_Expected_ProcessAuthorisation_Request_With_Signature()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
var request = new ProcessAuthorisationRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
OperatorId = "test_operator",
PosVersion = "123",
ClientTransactionReference = "tnx-ref1",
PreapprovalCode = "6111NHQMAM4Z",
FinanceAmount = 100,
PurchaseAmount = 500,
PurchaseItems = new PurchaseItemsCollection
(
new string[]
{
"Item1",
"Item2"
}
)
};
var result = writer.WriteRequest(request);
Assert.AreEqual("{\"x_pos_transaction_ref\":\"tnx-ref1\",\"x_pre_approval_code\":\"6111NHQMAM4Z\",\"x_finance_amount\":10000,\"x_purchase_amount\":50000,\"purchase_items\":\"{\\\"PurchaseItems\\\":[\\\"Item1\\\",\\\"Item2\\\"]}\",\"buyer_confirms\":false,\"x_merchant_id\":\"30299999\",\"x_device_id\":\"d555\",\"x_firmware_version\":\"123\",\"x_operator_id\":\"test_operator\",\"signature\":\"d6967970b99e585fc7d1a11702690f25b4be0c5fbfd10b39fbea3953ba48bad2\"}", result);
Assert.IsTrue(result.Contains("d6967970b99e585fc7d1a11702690f25b4be0c5fbfd10b39fbea3953ba48bad2"));
}
public void Throws_On_Null_Request()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
_ = writer.WriteRequest <CreateKeyRequest>(null);
}
public void Writes_Expected_ProcessSalesAdjustment_Request_With_Signature()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
var request = new ProcessSalesAdjustmentRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
OperatorId = "test_operator",
PosVersion = "123",
ClientTransactionReference = "tnx-ref1",
PurchaseReference = "123456789",
Amount = 10
};
var result = writer.WriteRequest(request);
//Note: The signature expected here is different to the one shown in the Humm sample page (https://docs.shophumm.com.au/pos/api_information/http_examples/).
//The sample C# code provided by Humm at (https://docs.shophumm.com.au/pos/security/signature_generation/) generates the same code used here
//and this signature gen works with the API endpoints, so it would appear the sample was updated using a different key or something, and the
//sample signature is now incorrect.
Assert.AreEqual("{\"x_pos_transaction_ref\":\"tnx-ref1\",\"x_purchase_ref\":\"123456789\",\"x_amount\":1000,\"x_merchant_id\":\"30299999\",\"x_device_id\":\"d555\",\"x_firmware_version\":\"123\",\"x_operator_id\":\"test_operator\",\"signature\":\"77d67d8dbae3aa2b403adc65c4e957af6dd918e62276a1cae0fadac743433f3b\"}", result);
Assert.IsTrue(result.Contains("ce20e2f1a9fe0d92b3d021ba7f1b372b006778cfab5fc4c09efa60a6d910c471"));
}
public void Can_Dispose_Mutiple_Times_Without_Exception()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
writer.Dispose();
writer.Dispose();
writer.Dispose();
writer.Dispose();
}
public void Throws_On_Null_OutputStream()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
var request = new ProcessSalesAdjustmentReversalRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
OperatorId = "test_operator",
PosVersion = "123",
ClientTransactionReference = "tnx-rev1",
AdjustmentSignature = "ce20e2f1a9fe0d92b3d021ba7f1b372b006778cfab5fc4c09efa60a6d910c471"
};
writer.WriteRequest(request, null);
}
public void Writes_Full_Request_When_Passed_Base_Type()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
RequestBase request = new InviteRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
OperatorId = "test_operator",
PosVersion = "123",
MobileNumber = "0400000000",
PurchaseAmount = 100M
};
var result = writer.WriteRequest(request);
Assert.AreEqual("{\"x_mobile\":\"0400000000\",\"x_purchase_amount\":10000,\"x_merchant_id\":\"30299999\",\"x_device_id\":\"d555\",\"x_firmware_version\":\"123\",\"x_operator_id\":\"test_operator\",\"signature\":\"e8045e8fdd521d9da2b4cd0c00f816680e9ec4d85bddab95c839d91f170f9deb\"}", result);
Assert.IsTrue(result.Contains("e8045e8fdd521d9da2b4cd0c00f816680e9ec4d85bddab95c839d91f170f9deb"));
}
public void Writes_Expected_CreateKey_Request_With_Signature()
{
var sigGen = new Hmac256SignatureGenerator("nb4i6ldxuVQC");
var writer = new SignedRequestWriter(sigGen);
var request = new CreateKeyRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
DeviceToken = "nb4i6ldxuVQC",
OperatorId = "test_operator",
PosVersion = "123",
PosVendor = "Pos Provider"
};
var result = writer.WriteRequest(request);
Assert.AreEqual("{\"x_device_token\":\"nb4i6ldxuVQC\",\"x_pos_vendor\":\"Pos Provider\",\"x_merchant_id\":\"30299999\",\"x_device_id\":\"d555\",\"x_firmware_version\":\"123\",\"x_operator_id\":\"test_operator\",\"signature\":\"cf4f4a19662c7617ea83a47456934123f530c82cdfdd66f5b706dd2263806848\"}", result);
Assert.IsTrue(result.Contains("cf4f4a19662c7617ea83a47456934123f530c82cdfdd66f5b706dd2263806848"));
}
public void Can_Write_Multiple_Requests_With_Signature()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
var request = new InviteRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
OperatorId = "test_operator",
PosVersion = "123",
MobileNumber = "0400000000",
PurchaseAmount = 100M
};
var result = writer.WriteRequest(request);
//Note: The signature expected here is different to the one shown in the Humm sample page (https://docs.shophumm.com.au/pos/api_information/http_examples/).
//The sample C# code provided by Humm at (https://docs.shophumm.com.au/pos/security/signature_generation/) generates the same code used here
//and this signature gen works with the API endpoints, so it would appear the sample was updated using a different key or something, and the
//sample signature is now incorrect.
Assert.AreEqual("{\"x_mobile\":\"0400000000\",\"x_purchase_amount\":10000,\"x_merchant_id\":\"30299999\",\"x_device_id\":\"d555\",\"x_firmware_version\":\"123\",\"x_operator_id\":\"test_operator\",\"signature\":\"e8045e8fdd521d9da2b4cd0c00f816680e9ec4d85bddab95c839d91f170f9deb\"}", result);
Assert.IsTrue(result.Contains("e8045e8fdd521d9da2b4cd0c00f816680e9ec4d85bddab95c839d91f170f9deb"));
request = new InviteRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
OperatorId = "test_operator",
PosVersion = "123",
MobileNumber = "0410000000",
PurchaseAmount = 10M
};
result = writer.WriteRequest(request);
Assert.AreEqual("{\"x_mobile\":\"0410000000\",\"x_purchase_amount\":1000,\"x_merchant_id\":\"30299999\",\"x_device_id\":\"d555\",\"x_firmware_version\":\"123\",\"x_operator_id\":\"test_operator\",\"signature\":\"4e4927bee1ab8e3e5ea354766ba81982ad5da8e65653cb696e140a2e784d6238\"}", result);
Assert.IsTrue(result.Contains("4e4927bee1ab8e3e5ea354766ba81982ad5da8e65653cb696e140a2e784d6238"));
}
private System.Net.Http.StreamContent GetRequestContent <T>(T request, SignedRequestWriter writer) where T : class
{
System.IO.Stream?stream = null;
try
{
stream = MemoryStreamFactory.CreateStream();
writer.WriteRequest(request, stream);
stream.Seek(0, System.IO.SeekOrigin.Begin);
var retVal = new System.Net.Http.StreamContent(stream);
retVal.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/json")
{
CharSet = System.Text.UTF8Encoding.UTF8.HeaderName
};
return(retVal);
}
catch
{
stream?.Dispose();
throw;
}
}
public void Writes_Expected_SendReceipt_Request_With_Signature()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
var request = new SendReceiptRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
OperatorId = "test_operator",
PosVersion = "123",
ClientTransactionReference = "tnx-ref1",
ReceiptNumber = "NewReceipt"
};
var result = writer.WriteRequest(request);
//Note: The signature expected here is different to the one shown in the Humm sample page (https://docs.shophumm.com.au/pos/api_information/http_examples/).
//The sample C# code provided by Humm at (https://docs.shophumm.com.au/pos/security/signature_generation/) generates the same code used here
//and this signature gen works with the API endpoints, so it would appear the sample was updated using a different key or something, and the
//sample signature is now incorrect.
Assert.AreEqual("{\"x_pos_transaction_ref\":\"tnx-ref1\",\"x_receipt_number\":\"NewReceipt\",\"x_merchant_id\":\"30299999\",\"x_device_id\":\"d555\",\"x_firmware_version\":\"123\",\"x_operator_id\":\"test_operator\",\"signature\":\"ac164e40585474838641bde1ad9bab08b6e6e0ab0c2dae814298e4fcef9c52fa\"}", result);
Assert.IsTrue(result.Contains("ac164e40585474838641bde1ad9bab08b6e6e0ab0c2dae814298e4fcef9c52fa"));
}
public void Writes_Expected_ProcessSalesAdjustmentReversal_Request_With_Signature()
{
var sigGen = new Hmac256SignatureGenerator("dy33vQhksVsv");
var writer = new SignedRequestWriter(sigGen);
var request = new ProcessSalesAdjustmentReversalRequest()
{
MerchantId = "30299999",
DeviceId = "d555",
OperatorId = "test_operator",
PosVersion = "123",
ClientTransactionReference = "tnx-rev1",
AdjustmentSignature = "ce20e2f1a9fe0d92b3d021ba7f1b372b006778cfab5fc4c09efa60a6d910c471"
};
var result = writer.WriteRequest(request);
//Note: The signature expected here is different to the one shown in the Humm sample page (https://docs.shophumm.com.au/pos/api_information/http_examples/).
//The sample C# code provided by Humm at (https://docs.shophumm.com.au/pos/security/signature_generation/) generates the same code used here
//and this signature gen works with the API endpoints, so it would appear the sample was updated using a different key or something, and the
//sample signature is now incorrect.
Assert.AreEqual("{\"x_pos_transaction_ref\":\"tnx-rev1\",\"x_adjustment_signature\":\"ce20e2f1a9fe0d92b3d021ba7f1b372b006778cfab5fc4c09efa60a6d910c471\",\"x_merchant_id\":\"30299999\",\"x_device_id\":\"d555\",\"x_firmware_version\":\"123\",\"x_operator_id\":\"test_operator\",\"signature\":\"83a8f5b53cbd205474cd8c993f911b465d25a381d3fc09c781fefb9bef18859d\"}", result);
Assert.IsTrue(result.Contains("1949a14cfdd8e6062a54f28ab3a607637f081afb7b8f4cffa3fb413fadab963b"));
}
public void Constructor_Throws_On_Null_Signature_Generator()
{
_ = new SignedRequestWriter(null);
}
