> For the complete documentation index, see [llms.txt](https://developer.magtek.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.magtek.com/sdks-and-tools/~/revisions/7gQMuwvu8JKvxaHJDCR8/universal-sdk-documentation/.net-windows/appendices/appendix-b-api-walk-through.md).

# Appendix B - API Walk Through

### CoreAPI Walk Trough

The following walks through how to create instances of a device.

* CoreAPI.createDevice à IDevice
* CoreAPI.getDeviceList à List\<IDevice>
* CoreAPI.createPPSCRA à MTPPSCRA

&#x20;These examples demonstrate methods for creating an IDevice to be used in the MagTek Universal SDK. This also shows how to establish a device specific API, which is not used with the MagTek Universal SDK.

Here, a single of IDevice is established.

{% code overflow="wrap" %}

```
// Access MMS with Universal SDK using createDevice()

IDevice mtmms = CoreAPI.createDevice( 
    DeviceType.MMS, 
    ConnectionType.USB,
    "",
    "",
    "DynaFlex", "");
mtmms.requestSignature(0xff);
```

{% endcode %}

Here, a list of IDevice is established. The first device is accessed at index 0.

{% code overflow="wrap" %}

```
// Acess MMS with Universal SDK using getDeviceList()

List<IDevice> mtmms = CoreAPI.getDeviceList(DeviceType.MMS); 
mtmms[0].requestSignature(0xff); 
```

{% endcode %}

Here the CoreAPI creates an instance of MTPPSCRA. The MTPPSCRANET is referenced and its library file is included in the application development project.

{% code overflow="wrap" %}

```
Using MTUSDKNET; 
Using MTPPSCRANET;


// Directly access PPSCRA with MTPPSCRANET by createPPSCRA()

MTPPSCRANET.MTPPSCRA mtppscra = CoreAPI.createPPSCRA(); 
mtppscra.openDevice("");
mtppscra.requestSignature(30, 2, 0);
```

{% endcode %}

### IDevice Walk Through <a href="#b.2_idevice_walk_through" id="b.2_idevice_walk_through"></a>

The following walks through how to make use of IDevice.

* Implement device events within the class to receive events.
* CoreAPI --> IDevice.
* IDevice --> subscribeAll().
* IDevice --> other functions.
* IDevice à startTransaction().

**Example**

<pre data-overflow="wrap"><code>Using MTUSDKNET;
.
// Extend the main window to receive events.
public class MainWindow : IEventSubscriber, IConfigurationCallback
{
 
// Establish a device from CoreAPI.
List&#x3C;IDevice> deviceList = CoreAPI.getDeviceList(); 
IDevice device = deviceList[0];
 
/* For a list of a single device type. 
DeviceType deviceType = DeviceType.MMS; 
List&#x3C;IDevice> deviceList = CoreAPI.getDeviceList(deviceType); 
IDevice device = deviceList[0];
*/
 
/* For a list of multiple device types. List&#x3C;DeviceType> deviceTypes = null; deviceTypes.Add(DeviceType.MMS); 
deviceTypes.Add(DeviceType.CMS);
List&#x3C;IDevice> deviceList = CoreAPI.getDeviceList(deviceTypes); 
IDevice device = deviceList[0];
*/
 
/* Suscribe to events sent from the device.
    These would be but not limited to: card inserted, card removed, connection state...
 
<strong>    Set MainWindow to receive the events. */ 
</strong><strong>bool return = device.unsubscribeAll(this); 
</strong><strong>bool return = device.subscribeAll(this);
</strong> 
/* To handle events from some other class. 
EventsVector eventsVector = new EventsVector() 
bool return = device.unsubscribeAll(eventsVector); 
bool return = device.subscribeAll(eventsVector);
*/

// Assign parameters for the transaction. ITransaction transaction = new Transaction(); transaction.Amount = “1.00”;
transaction.CashBack = “0.00”;
transaction.EMVOnly = true;
transaction.PaymentMethods = new List&#x3C;PaymentMethod>(); transaction.PaymentMethods.Add(PaymentMethod.MSR); transaction.PaymentMethods.Add(PaymentMethod.Contact); transaction.PaymentMethods.Add(PaymentMethod.Contactless); transaction.QuickChip = false;

// Start transaction.
bool result = device.startTransaction(transaction);

// Assign parameters for the transaction. ITransaction transaction = new Transaction(); transaction.Amount = “1.00”;
transaction.CashBack = “0.00”;
transaction.EMVOnly = true;
transaction.PaymentMethods = new List&#x3C;PaymentMethod>(); transaction.PaymentMethods.Add(PaymentMethod.MSR); transaction.PaymentMethods.Add(PaymentMethod.Contact); transaction.PaymentMethods.Add(PaymentMethod.Contactless); transaction.QuickChip = false;

// Start transaction.
bool result = device.startTransaction(transaction);
</code></pre>

### Handling Events <a href="#b.2.1_handling_events" id="b.2.1_handling_events"></a>

Application Main window may extent the IEventSubscriber Delegate, or events can be interfaced by a separate class. This example uses a separate class and demonstrates how to parse for the various event types.

**Example**

<pre data-overflow="wrap"><code>// A class to handle events.
public class EventsVector : IEventSubscriber
{
<strong>        public void OnEvent(EventType eventType, IData data)
</strong>        {
                switch (eventType)
                {
</code></pre>

Various events are separately shown below.

{% code overflow="wrap" %}

```
case EventType.ConnectionState:
// Parse for the ConnectionState 
ConnectionState value =
ConnectionStateBuilder.GetValue(data.StringValue);

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.DeviceResponse:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.DeviceExtendedResponse:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.DeviceNotification:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.CardData:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
 case EventType.TransactionStatus:
// Parse for the transaction status code and detail. 
TransactionStatus status = 
TransactionStatusBuilder.GetStatusCode(data.StringValue);

string statusDetail = 
TransactionStatusBuilder.GetStatusDetail(data.StringValue);

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.DisplayMessage: 

string message;

// Get the message.
message = data.StringValue;

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.InputRequest:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
 case EventType.AuthorizationRequest:

// Forward ARQC to processor.
/* data[0..1] – ARQC length
data[2..n] – remainder contains the ARQC TLV object
*/

IData ARQC = new BaseData(data.ByteArray);

// App function to send the request to the processor.
string ARPC = sendARQCToProcessorForApproval(ARQC.ByteArray);

// Send authorization to device when not in QuickChip mode. IData ARPCTLV = new BaseData("");
ARPCTLV.StringValue = "FF7413DFDF250742363243413546FA067004” + ARPC;

if (transaction.QuickChip == false)
{
device.sendAuthorization(ARPCTLV);
}

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
 case EventType.TransactionResult:
 
 /* data[0]– Signature Required
 data[1..2] – Batch Data length
 data[3..n] – remainder contains the Batch Data TLV object
*/

// Parse the TLV from data[].
// Abstract Approval status from TLV tag “DFDF1A”.
// Abstract Signature Required status from TLV tag at data[0].
break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.PINData:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.Signature:

break;
```

{% endcode %}

{% code overflow="wrap" %}

```
case EventType.TransactionStatus:

/*
Transaction status enumeration is build from the TransactionStatusBuilder.
*/
TransactionStatus status = TransactionStatusBuilder.GetStatusCode(data.StringValue);

if (status == TransactionStatus.CardSwiped)
{
//
}
if (status == TransactionStatus.CardInserted)
{
//
}
if (status == TransactionStatus.TransactionApproved)
{
//
}

break;
```

{% endcode %}

### IDeviceControl Walk Through <a href="#b.3_idevicecontrol_walk_through" id="b.3_idevicecontrol_walk_through"></a>

The following walks through how to make use of IDeviceControl.

* IDevice à IDeviceControl.
* IDeviceControl à open().
* IDeviceControl à other functions.
* IDeviceControl à close().

**Example**

{% code overflow="wrap" %}

```
// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList(); 
IDevice device = deviceList[0];

// Establish a deviceControl from device.
IDeviceControl deviceControl = device.getDeviceControl();

// Open the device, then use the IDeviceControl functions. 
deviceControl.open();

. . .
// Close the device. deviceControl.close();
```

{% endcode %}

### ConnectionInfo Walk Through <a href="#b.4_connectioninfo_walk_through" id="b.4_connectioninfo_walk_through"></a>

The following walks through how to make use of ConnectionInfo.

* IDevice --> ConnectionInfo.
* ConnectionInfo --> getAddress()
* ConnectionInfo --> getConnectionType()
* ConnectionInfo --> getDeviceType() Example

{% code overflow="wrap" %}

```
// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList(); 
IDevice device = deviceList[0];

// Establish a ConnectionInfo from device.
ConnectionInfo connectionInfo = device.getConnectionInfo();

// Retrieve address, connectionType, and deviceType. 
string address = connectionInfo.getAddress();
ConnectionType connectionType = connectionInfo.getConnectionType(); 
DeviceType deviceType = connectionInfo.getDeviceType();
```

{% endcode %}

### IDeviceCapabilities Walk Through <a href="#b.5_idevicecapabilities_walk_through" id="b.5_idevicecapabilities_walk_through"></a>

The following walks through how to make use of IDeviceCapabilities.

·       IDevice à IDeviceCapabilities.

·       IDeviceCapabilities à BatteryBackedClock() to check if date/time should be set.

·       IDeviceCapabilities à PaymentMethods() to check card types supported.

·       IDeviceCapabilities à other functions.

{% code overflow="wrap" %}

```
// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList(); IDevice device = deviceList[0];

// Establish a ConnectionInfo from device.
ConnectionInfo connectionInfo = device.getConnectionInfo();

// Retrieve address, connectionType, and deviceType. 
string address = connectionInfo.getAddress();
ConnectionType connectionType = connectionInfo.getConnectionType(); 
DeviceType deviceType = connectionInfo.getDeviceType();
```

{% endcode %}

### IDeviceConfiguration Walk Through <a href="#b.6_ideviceconfiguration_walk_through" id="b.6_ideviceconfiguration_walk_through"></a>

The following walks through how to make use of IDeviceConfiguration.

* IDevice à getDeviceConfiguration().
* IDeviceConfiguration à updateFirmware().
* IDeviceConfiguration à getConfiguration().
* IDeviceConfiguration à setConfiguration().
* IDeviceConfiguration à other functions.

**Example**

{% code overflow="wrap" %}

```
// Establish a device from CoreAPI.
List<IDevice> deviceList = CoreAPI.getDeviceList();
 IDevice device = deviceList[0];
 
IDeviceConfiguration devConfig = device.getDeviceConfiguration();

IDeviceControl devControl = device.getDeviceControl(); devControl.open();
 
/* To handle events from some other class. ConfigCallBacks configCallBacks = new ConfigCallBacks();
*/

// Update firmware.
byte[] data = System.IO.File.ReadAllBytes(“filepath”);
int return = devConfig.updateFirmware(0x01, data, this);
 
/* Get configuration.
                Device-Driven Fallback OID = 1.2.1.1.1.1
                                contructed OID = E2 08 E1 06 E1 04 E1 02 C1 00
                Note: first digit of OID is ommited in the construction and instead is passed in the configType.
*/
byte configType = 0x01;
data = new byte[] {0xE2,0x08,0xE1,0x06,0xE1,0x04,0xE1,0x02,0xC1,0x00
};
byte[] response = devConfig.getConfigInfo(configType, data);
 
 
/* Set configuation.
Device-Driven Fallback OID is 1.2.1.1.1.1
Disabled contructed OID = E2 09 E1 07 E1 05 E1 03 C1 01 00
Enabled contructed OID = E2 09 E1 07 E1 05 E1 03 C1 01 01
Note: first digit of OID is ommited in the construction and instead is passed in the configType.

*/
data = new byte[]
{0xE2,0x09,0xE1,0x07,0xE1,0x05,0xE1,0x03,0xC1,0x01,0x00 };
```

{% endcode %}

### Handling Events <a href="#b.6.1_handling_events" id="b.6.1_handling_events"></a>

Application Main window may extent the IConfigurationCallback Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various events.

**Example**

{% code overflow="wrap" %}

```
// A class to handle configuration callback events.
public class ConfigCallbacks : MTUSDKNET.IConfigurationCallback
{
    public void OnProgress(int progress)
    {
        /* Handle progress.
        Progress is complete when progress = 100 */
    }
```

{% endcode %}

{% code overflow="wrap" %}

```
public void OnResult(StatusCode status, byte[] data)
{
    /* Handle result.
        A configuration process is complete when status = StatusCode.Success */
}
```

{% endcode %}

{% code overflow="wrap" %}

```
    public IResult OnCalculateMAC(byte macType, byte[] data)
    {
        IResult result = new Result(StatusCode.UNAVAILABLE); 
        byte[] macBytes = null;

        DeviceType deviceType = 
            device.getConnectionInfo().getDeviceType();

        switch (deviceType)
        {
            case DeviceType.MMS:
                macBytes = getDynaFlexMAC(macType, data); 
                break;
        }
        
        if (macBytes != null)
        {
            result = new Result(StatusCode.SUCCESS); 
            result.Data = new BaseData(macBytes);
        }

        return result;
    }
}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.magtek.com/sdks-and-tools/~/revisions/7gQMuwvu8JKvxaHJDCR8/universal-sdk-documentation/.net-windows/appendices/appendix-b-api-walk-through.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
