AgentCASH SDK for Windows

AgentCASH SDK for Windows makes it easy to integrate your Windows Store 8.1 apps, Windows Phone 8.1 apps, or UWP applications with AgentCASH payment gateway.

Getting started

Main type that you will be using is AgentCash.SDK.PgClient.

Typically, you will create and initialize a PgClient instance during startup of the application, register handlers for events and then call appropriate method depending on type of transaction you want to perform (authorization, purchase or refund)

Here’s an example:

// At the beginning you will create a PgClient instance and set it up
// Create an instance of AgentCash.SDK.PgClient
PgClient client = new PgClient();
// Initalize the client with your API key
client.Initialize(API_KEY);

// Subscribe to the events you are interested in. Typically, you would want
// to know when the transaction is finished and whether it has failed so you
// can provide feedback to the customer.
// There are also other events as we will see later
client.Error += OnError;
client.TransactionFinished += OnTransactionFinished;

// Later, for each transaction you will create a payment and execute it.
// Here we create a new TransactionRequest. Only the amount is mandatory.
var payment = new TransactionRequest { Amount = amount };
// Execute the transaction request - the outcome will be notified by events
client.Charge(payment);

This is the main part of your application. Let’s take a closer look at it.

PgClient client = new PgClient();
client.Initialize(API_KEY);

After you have created the client, you need to initialize it with your API key. This key is assigned to you by AgentCASH and you can find it at http://dev.agentcash.net/admin#/webshop/api. We suggest that you initialize the client when the application form is already created. See here and SerializeEvents property for more details why.

You can also specify a Configuration instance here, but for the moment let’s use the default settings.

Now you have to subscribe for the events:

client.Error += OnError;
client.TransactionFinished += OnTransactionFinished;

You will at least want to handle these:

  • TransactionFinished: raised after the transaction is processed. it carries the information about outcome (approved/declined) and other transaction details (identifier, receipt URL, etc)
  • Error: raised if an error has happened, which prevented the transaction to be carried out.

There are also other events:

  • TransactionStarted: raised when the transaction is started.
  • ProgressInfo: raised to provide notifications of transaction progress (insert card, enter PIN, etc)
  • TransactionCanceled: raised if you cancel the transaction by calling Cancel method.
  • SignatureRequired: raised when you need to provide the signature for transaction that require it.
  • BeepRequested: raised when sound confirmation is required for contactless transactions.

For more details, please consult PgClient reference.

When the client is configured, you can execute a transaction.

var payment = new TransactionRequest { Amount = amount };
client.Charge(payment);

There are three types of transaction:

  • Authorize: authorizes the specified amount
  • Charge: performs authorization and capture of funds.
  • Refund: performs a refund.

For Authorize and Charge transactions, you only have to specify the amount of the transaction. The currency will be deduced from your merchant account settings.

For Refund transaction you must specify transaction ID of the transaction being refunded. You can use PgClient.FindTransactions method to look up transactions by authorization code or card PAN. Please note that searching for previous transactions, as well as performing refunds, requires that you provide username and password in Configuration data.

The methods that execute the transaction are not blocking: transaction processing can take time and, as we primarily target GUI apps, this would freeze the GUI.

Instead, the method call will execute immediately, and the outcome will be provided through one of the events. Every transaction must trigger one of these events:

  • TransactionFinished: transaction was processed. You can use the data provided with the event to notify customer or store in your local system.
  • Error: an error prevented the transaction from being processed.
  • TransactionCanceled: your application has canceled the transaction.

For more details, check Handling events.

Here’s an example:

void OnTransactionFinished(object sender, TransactionFinishedEventArgs e)
{
  Log("Transaction finished: {0}", e.Succeeded ? "Success" : "Failure");
  Log("Status: {0}", e.TransactionInfo.Status);
  if (e.Succeeded)
  {
    Log(" Authorization code: {0}", e.TransactionInfo.AuthorizationCode);
    Log(" Card number: {0}", e.TransactionInfo.CardInfo.MaskedPan);
  }
  Log("Transaction ID: {0}", e.TransactionInfo.TransactionId);
  Log("Amount: {0} {1}", e.TransactionInfo.Amount, e.TransactionInfo.Currency);
  Log("Receipt URL: {0}", e.TransactionInfo.ReceiptUrl);
}