1 of 6

Appendices

Supplementary reference material for the MagTek Universal SDK, including the full status-code list, a step-by-step API walk-through, the EMV transaction flow, and integration guidance for mobile-wallet value-added services (Apple VAS and Google Wallet Smart Tap).

Appendix A - Status Codes

public enum StatusCode
{
    SUCCESS = 0,
    TIMEOUT = 1,
    ERROR = 2,
    UNAVAILABLE = 3
}

Enum

Description

SUCCESS

The operation completed successfully.

TIMEOUT

The operation timed out.

Appendix B - API Walk Through

CoreAPI Walk Trough

The following walks through how to create instances of devices.

CoreAPI.createDevice à IDevice
CoreAPI.getDeviceList à List
CoreAPI.createPPSCRA à MTPPSCRA

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 IDevice is established.

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

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.

Example

Application Main window may extent the

Static

Member

Value

Description

These constructors initialize a PersonalInfoEntry object.

Call startPersonalInfoEntry().
At OnEvent():TouchscreenPersonalInfoEntry, build the object.

Member

Description

Return Value:

Returns an instance of PersonalInfoEntry.

IEventSubscriber Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various event types.

Example

Various events are separately shown below

The following walks through how to make use of IDeviceControl.

IDevice --> IDeviceControl.· IDeviceControl à open().
IDeviceControl --> other functions.
IDeviceControl --> close().

Example

The following walks through how to make use of ConnectionInfo.

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

Example

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.

The following walks through how to make use of IDeviceConfiguration.

IDevice --> getDeviceConfiguration().
IDeviceConfiguration --> updateFirmware().
IDeviceConfiguration --> getConfiguration().
IDeviceConfiguration --> setConfiguration().

Example

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

Appendix C - EMV Transaction Flow

This section demonstrates transaction flow.

Flow Chart - QuickChip

Sample Code - QuickChip

The following breaks out the EMV flow chart into code. When enabling QuickChip mode, host does not send the ARPC to the device to complete the transaction. Events are shown separately and in the order received.

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(true); // QuickChip mode enabled.

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

public void OnEvent(EventType eventType, IData data)
{
    String message 
    switch (eventType);
        {
            case EventType.DisplayMessage:
                // Get the message.
                message = data.StringValue();
    }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.InputRequest:
            // Get the message.
            message = data.StringValue();

            // display/retrieve user selection.

            // set status and selection result.
            IData selectionData = new BaseData(new Byte[] {status, selection});
            device.sendSelection(selectionData);
    }
}

public void OnEvent(EventType eventType, IData data)
{
byte[] ARQC = null; 
switch (eventType);
    {
        case EventType.AuthorizationRequest:
            // Forward ARQC to processor.
            /* data[0..1] – ARQC length
                data[2..n] – remainder contains the ARQC TLV object */
    }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
        
            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 data[0].
        }
}

Flow Chart – Signature Capture

Sample Code – Signature Capture

The following breaks out the EMV flow chart into code. Events are shown separately and in the order received.

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(true);

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

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:

                // Get the message.
                message = data.StringValue();
    }
}

public void OnEvent(EventType eventType, IData data)
{
    byte[] ARQC = null; 
    switch (eventType);
        {
            case EventType.AuthorizationRequest:
                // #4a
                // Forward ARQC to processor.
                /* data[0..1] – ARQC length
                    data[2..n] – remainder contains the ARQC TLV object */
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:
                // Display approval message. 
                message = data.StringValue();

                // A data size of 0 is an instruction to clear the display. 
                if (data.StringValue().Length == 0)
                {
                    // Clear the UI display.
                }
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            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 data[0].
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String signature; 
    switch (eventType);
        {
            case EventType.Signature: 
                signature = data.StringValue();
        }
}

Flow Chart – With ARPC

Sample Code – With ARPC

The following breaks out the EMV flow chart into code. When disabling QuickChip mode, host must send the ARPC to the device to complete the transaction. Events are shown separately and in the order received.

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(false); //QuickChip mode disabled.

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

public void OnEvent(EventType eventType, IData data)
{
    string message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:

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

public void OnEvent(EventType eventType, IData data)
{
    string message; 
    switch (eventType);
        {
            case EventType.InputRequest:
                // Get the message.
                message = data.StringValue;

                // display/retrieve user selection.

                // set status and selection result.
                IData selectionData = new BaseData(new Byte[] {status, selection});
device.sendSelection(selectionData);
    }
}

public void OnEvent(EventType eventType, IData data)
{
    byte[] ARQC = null; 
    switch (eventType);
        {
            case EventType.AuthorizationRequest:
                // Forward the ARQC to the processor.
                /* data[0..1] – ARQC length
                data[2..n] – remainder contains the ARQC TLV object */

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

        }
}

After the ARPC is returned from the processor, it is constructed into a TLV container and then sent to the device. The ARPC for approved (00) is set in ASCII 3030.

The optional tags 91, 71, and 72 (Issuer Authentication Data, Issuer Script Template 1, and Issuer Script Template 2) are not included in this example.

See the construction of the ARPCTLV in the table below.

ARPC TLV object for sendAuthorization().

Tag

Len

Value / Description

Typ

Req

Default

The use case for an MSR fallback is when communication with the chip results in a terminated transaction and the TransactionStatus is reported as MSRFallback.

The host application will re-attempt the transaction. To invoke this use case, here are the following pre-requisites.

Pre-requisites:

Device already configured for Device-Driven Fallback = Disabled.
A card to cause the fallback. Example but not limited to a card with no applications programmed or a card with an application not configured on the device.

Scheme:

-->Host begins an initial transaction with PaymentMethod set to MSR+Chip+Contactless.
<--Device responds with fail and with status of MSRFallback.
-->Host displays a message to use magstripe.
-->Host starts a transaction with PaymentMethod set to MSR.

Begin initial transaction:

Continue with Fallback transaction:

Appendix D - Apple VAS

These instructions are for preparing Apple VAS (value-added service) transactions.

Merchant ID and URL Slots

Set the Apple VAS Merchant ID and URL property for each slot 1 to 6 using IDeviceControl --> setConfigInfo().

POS Capabilities

Set the POS capabilities property using IDeviceControl à setConfigInfo().

Start Transaction

Set the PaymentMethods to include PaymentMethod.AppleVAS.
Set AppleVASMode to: VASMode.Single, VASMode.Dual, or VASMode.VASOnly.
Set AppleVASProtocol to: VASProtocol.Full or VASProtocol.URL.

Data from an Apple VAS (9F27 and 9F2A) is returned in separate Apple VAS slot containers.
FE — var — VAS Data Container
- FF01

Appendix E - Google Wallet Smart Tap VAS

These instructions are for preparing Google Wallet Smart Tap VAS (value-added service) transactions.

Configure the mobile device for Google Wallet Smart Tap Pass.

Load the LTPK protection key (Long Term Private Key) into the MagTek device.
Upload a Public Key to the Google Pay & Wallet Console for the issuer account associate with the Google Wallet Pass.

Appendix B - API Walk Through

CoreAPI Walk Trough

The following walks through how to create instances of devices.

CoreAPI.createDevice à IDevice
CoreAPI.getDeviceList à List
CoreAPI.createPPSCRA à MTPPSCRA

Here, a single IDevice is established.

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

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.

Example

Application Main window may extent the

Static

Member

Value

Description

These constructors initialize a PersonalInfoEntry object.

Call startPersonalInfoEntry().
At OnEvent():TouchscreenPersonalInfoEntry, build the object.

Member

Description

Return Value:

Returns an instance of PersonalInfoEntry.

IEventSubscriber Delegates or can be extended by a separate class. This example uses a separate class and demonstrates how to parse for the various event types.

Example

Various events are separately shown below

The following walks through how to make use of IDeviceControl.

IDevice --> IDeviceControl.· IDeviceControl à open().
IDeviceControl --> other functions.
IDeviceControl --> close().

Example

The following walks through how to make use of ConnectionInfo.

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

Example

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.

The following walks through how to make use of IDeviceConfiguration.

IDevice --> getDeviceConfiguration().
IDeviceConfiguration --> updateFirmware().
IDeviceConfiguration --> getConfiguration().
IDeviceConfiguration --> setConfiguration().

Example

Appendix C - EMV Transaction Flow

This section demonstrates transaction flow.

Flow Chart - QuickChip

Sample Code - QuickChip

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(true); // QuickChip mode enabled.

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

public void OnEvent(EventType eventType, IData data)
{
    String message 
    switch (eventType);
        {
            case EventType.DisplayMessage:
                // Get the message.
                message = data.StringValue();
    }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.InputRequest:
            // Get the message.
            message = data.StringValue();

            // display/retrieve user selection.

            // set status and selection result.
            IData selectionData = new BaseData(new Byte[] {status, selection});
            device.sendSelection(selectionData);
    }
}

public void OnEvent(EventType eventType, IData data)
{
byte[] ARQC = null; 
switch (eventType);
    {
        case EventType.AuthorizationRequest:
            // Forward ARQC to processor.
            /* data[0..1] – ARQC length
                data[2..n] – remainder contains the ARQC TLV object */
    }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
        
            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 data[0].
        }
}

Flow Chart – Signature Capture

Sample Code – Signature Capture

The following breaks out the EMV flow chart into code. Events are shown separately and in the order received.

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(true);

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

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:

                // Get the message.
                message = data.StringValue();
    }
}

public void OnEvent(EventType eventType, IData data)
{
    byte[] ARQC = null; 
    switch (eventType);
        {
            case EventType.AuthorizationRequest:
                // #4a
                // Forward ARQC to processor.
                /* data[0..1] – ARQC length
                    data[2..n] – remainder contains the ARQC TLV object */
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:
                // Display approval message. 
                message = data.StringValue();

                // A data size of 0 is an instruction to clear the display. 
                if (data.StringValue().Length == 0)
                {
                    // Clear the UI display.
                }
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String message; 
    switch (eventType);
        {
            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 data[0].
        }
}

public void OnEvent(EventType eventType, IData data)
{
    String signature; 
    switch (eventType);
        {
            case EventType.Signature: 
                signature = data.StringValue();
        }
}

Flow Chart – With ARPC

Sample Code – With ARPC

// Assign parameters.
List<PaymentMethod> paymentMethod = new List<PaymentMethod>(); 
paymentMethod.Add(PaymentMethod.MSR); 
paymentMethod.Add(PaymentMethod.Contact); 
paymentMethod.Add(PaymentMethod.Contactless);

Transaction transaction = new Transaction(); 
transaction.setAmount(“1.00”); 
transaction.setCashBack(“0.00”); 
transaction.setEMVOnly(true); 
transaction.setPaymentMethods(paymentMethod); 
transaction.setQuickChip(false); //QuickChip mode disabled.

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

public void OnEvent(EventType eventType, IData data)
{
    string message; 
    switch (eventType);
        {
            case EventType.DisplayMessage:

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

public void OnEvent(EventType eventType, IData data)
{
    string message; 
    switch (eventType);
        {
            case EventType.InputRequest:
                // Get the message.
                message = data.StringValue;

                // display/retrieve user selection.

                // set status and selection result.
                IData selectionData = new BaseData(new Byte[] {status, selection});
device.sendSelection(selectionData);
    }
}

public void OnEvent(EventType eventType, IData data)
{
    byte[] ARQC = null; 
    switch (eventType);
        {
            case EventType.AuthorizationRequest:
                // Forward the ARQC to the processor.
                /* data[0..1] – ARQC length
                data[2..n] – remainder contains the ARQC TLV object */

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

        }
}

After the ARPC is returned from the processor, it is constructed into a TLV container and then sent to the device. The ARPC for approved (00) is set in ASCII 3030.

The optional tags 91, 71, and 72 (Issuer Authentication Data, Issuer Script Template 1, and Issuer Script Template 2) are not included in this example.

See the construction of the ARPCTLV in the table below.

ARPC TLV object for sendAuthorization().

Tag

Len

Value / Description

Typ

Req

Default

The use case for an MSR fallback is when communication with the chip results in a terminated transaction and the TransactionStatus is reported as MSRFallback.

The host application will re-attempt the transaction. To invoke this use case, here are the following pre-requisites.

Pre-requisites:

Device already configured for Device-Driven Fallback = Disabled.
A card to cause the fallback. Example but not limited to a card with no applications programmed or a card with an application not configured on the device.

Scheme:

-->Host begins an initial transaction with PaymentMethod set to MSR+Chip+Contactless.
<--Device responds with fail and with status of MSRFallback.
-->Host displays a message to use magstripe.
-->Host starts a transaction with PaymentMethod set to MSR.

Begin initial transaction:

Continue with Fallback transaction:

Appendices

Appendix A - Status Codes

Appendix B - API Walk Through

CoreAPI Walk Trough

Appendix C - EMV Transaction Flow

Flow Chart - QuickChip

Sample Code - QuickChip

Flow Chart – Signature Capture

Sample Code – Signature Capture

Flow Chart – With ARPC

Sample Code – With ARPC

Appendix D - Apple VAS

Merchant ID and URL Slots

POS Capabilities

Start Transaction

Appendix E - Google Wallet Smart Tap VAS

Appendix A - Status Codes

Appendix D - Apple VAS

Merchant ID and URL Slots

POS Capabilities

Start Transaction

Transaction Response

Appendix E - Google Wallet Smart Tap VAS

Mobile Device

Load Key

Collector ID Slots

POS Capabilities

Start Transaction

Transaction Response

Appendix B - API Walk Through

CoreAPI Walk Trough

Appendices

IDevice Walk Through

Handling Events

Static members

PersonalInfoEntry

IDeviceControl Walk Through

ConnectionInfo Walk Through

IDeviceCapabilities Walk Through

IDeviceConfiguration Walk Through

Handling Events

Appendices

In This Section

Need More Help

Appendix C - EMV Transaction Flow

Flow Chart - QuickChip

Sample Code - QuickChip

Flow Chart – Signature Capture

Sample Code – Signature Capture

Flow Chart – With ARPC

Sample Code – With ARPC

MSR Fallback Flow