Payment Engine SDK Documentation

Payment Engine is a point of sale middleware solution that allows developers to work with a variety of payment terminals without the hassle of integrating and certifying each solution. The middleware is available as an iOS/Android mobile application library.

• Mobile Middleware
  • Android
  • iOS

ANDROID MIDDLEWARE

The USAePay Middleware library allows developers to process EMV, contactless and swiped transactions on the USAePay gateway. The library handles all communication between the hardware and gateway. This allows developers to create rich mobile payment applications without the hassle and expense of EMV certification.

The library supports Android 4.0+.

• Download the latest release: paymentengine-android-sdk-2.3.3.zip
• Getting Started

UEMiddleware Class	Description
UEMiddleware()	Constructor for middleware class.
clearCachedFiles()	Clears all locally cached files related to terminal config and software updates.
connect()	Establishes connection to device.
disconnect()	Disconnects from device.
doPerformTermUpdate()	Perform any outstanding terminal updates.
getAdvancedAPI()	Returns Advanced API Object to run Manually Keyed Transaction as Card Not Present.
getAvailableDevices()	Returns a list of available paired BT MP200 devices. Devices can be identified by the last 4 of the serial number.
getDeviceInfo()	Returns details about the device and its configuration.
getGatewayInfo()	Retrieves information about the gateway being used.
getMerchantCapabilities()	Retrieves information about merchant's capabilities.
getReceipt()	Makes API Call to get receipt from EMV Template.
getSoftware()	Returns middleware software version.
hardReset()	Performs a hard reset of the terminal (not currently supported by MP200).
isConnected()	Returns 'true' if device is connected, 'false' otherwise.
returnPartialAuthDecision()	Continues partial auth transactions when processing through onPromptForPartialAuth()(String partialAmount).
setConnectionType()	Sets connection type for MP200.
setSourceAndPin()	Sets the gateway source key, and pin. Must be set before the transaction can be sent.
setTerminalConfig()	Changes terminal preferences.
setTipAdjust()	Enables tip adjust.
startTransaction()	Starts a payment request.
updateDevice()

UEMiddleware Interface	Description
onAlertUser()	Called to alert the user to perform an action. This is generally implemented with an AlertDialog.
onBadCardRead()
onConnected()	Called when the middleware has connected to the device.
onDeviceInfoReceived()	Called when device info has been received.
onDisconnected()	Called when the middleware has disconnected from the device.
onError()	Called when there is a general error, if the transaction cannot proceed it will have been cancelled gracefully, no need to call cancel
onFileWriteComplete()
onFileWriteUpdate()
onGatewayInfoReceived()	Called when gateway info has been received.
onMerchantCapabilitiesReceived()	Called when merchant capability data has been received.
onProgressBarUpdateAvailable()	Called back when the progress bar has changed.
onProgessChanged()
onPromptForPartialAuth()	Called when a transaction is only partially approved. IMPORTANT: The implementor must create a dialog which gives the user the choice to accept or decline the partial authorization. When the result is received the implementor must then call returnPartialAuthDecision().
onReceiptReceived()	Called back when the receipt object returns from the API.
onSeePhoneNFC()	Called when the terminal is waiting for the customer to complete a step on their phone or mobile device.
onStatusChanged()	Called when there is an update to the transaction status.
onStatusMessage()
onTransactionCancelled()
onTransactionComplete()	Called when the transaction is complete.
onUpdateCheckResultsReceived()	Called back after checkIfUpdateNeeded() is called.
onWaitingForCardRemoval()	Called when the user should be prompted to remove the card.

Android Change Log

v2.3.3 - 7/12/2017

• Fixed issue where "capture" command was being sent on "cc:authonly"
• Added support for the flow where user removes card on an EMV transaction after authorization sent to gateway but before we reach the "Approved" screen on MP200
• Fixed getDeviceInfo(), callback onDeviceInfoReceived() is firing
• Fixed "Host Error" message that displayed on MP200 at the end of Contactless transactions

v2.3.2 - 1/23/2017

• Better performance on cancelUpdate() method when called during setTerminalConfig() update
• Improved screens on MP200 to indicate the payment methods accepted
• Fixed issue preventing Contactless transactions from calling the onTransactionComplete() delegate
• Allows user to cancel current transaction and pick up with a Manual Key transaction
• Stability improvements

v2.3.1 - 1/23/2017

• Support for the First Data Nashville and Tsys processing platforms

v2.2.1 - 8/11/16

• Removed the setSourceAndPin() and setConnectionType() methods. Sourcekey and pin are now set via the connect() method and can not be change after the device is already connected.
  
• Modified setTerminalConfig so that it needs to be called before connect(). onError(DEVICE_CONNECTED) will be called if attempt is made after connect()
• Added alternate setTerminalConfig with force parameter to force writing the new terminal config
• Added "adjust" command to startTransaction. Functions the same as capture but without moving the transaction into the batch.
• Removed onWaitingForCardRemoval() delegate. onTransactionComplete() is called when the transaction is complete, there is not an interim step that waits for the customer to remove their card. It can be left in the terminal.
• Removed onTransactionCancelled() delegate. onTransactionComplete() is called for all startTransaction() outcomes, including when a user cancels the transaction.
• Removed onAlertUser from documentation
• A MiddlewareException will be thrown if any method is called with a required parameter set to null
• Removed onBadCardRead() delegate, does not apply to the Castles MP200, terminal waits for customer to try again
• Removed updateDevice(), checkIfUpdateNeeded(), checkTermUpdateAvailable() and doPerformTermUpdate(): the update process is automatic and occurs during connect() so these methods are no longer relevant
• Removed unused delegates: onFileWriteComplete(), onFileWriteUpdate(),
• Removed onStatusMessage() delegate, replaced by onStatusChanged()
• Removed onTransactionCancelled() delegate, onTransactionComplete() is fired instead
• Removed getUserCapabilitiesOrInfo, replaced by getMerchantCapabilities() and getGatewayInfo()
• Added onMerchantCapabilitiesReceived() and onGatewayInfoReceived()
• Changed return on getDeviceDetails() to void, details are returned to onDeviceInfoReceived
• getDeviceInfo replaces getDeviceDetails() for consistency, calls the onDeviceInfoReceived() delegate
• connect() will thrown a MiddlewareException if the hostname parameter is not a valid hostname.
• Known Issues
  • When changing the enable_debit_msr preference using setTerminalConfig() followed by connect(), the device does not automatically reboot. The updated configuration is written to the terminal but the user must manually power off and on the device before it will take effect.
  • The hardRest() method is not supported with the MP200.
  • getDeviceDetails is not currently retrieving device details correctly.
  • getReceipt is not currently pulling receipts

v2.2.0 - 7/29/16

• Global Certification (7/20/16)
• Add setTerminalConfig method for changing terminal configuration
• Updated connect() method to perform automatic terminal updates
• Add clearCachedFiles() method to force terminal update
• Updated startTransaction() method to return all responses through the onTransactionComplete() delegate method
• Add additional connect() variants to allow overriding the gateway host, setting target in the startTransaction hash map is now deprecated
• Add additional startTransaction() variant that does not require sourcekey/pin to be passed in again
• New errors added to UE_ERROR:
  • INVALID_COMMAND - received when startTransaction is called with an unsupported command
  • TRANSACTION_ALREADY_IN_PROCESS - received when startTransaction is called and another startTranaction is still running
  • UPDATING - received when a startTranaction is called while the software is still updating software
• Deprecate middleware methods:
  • checkIfUpdateNeeded(), checkTermUpdateAvailable(), doPerformTermUpdate(), updateDevice() - Replaced by connect() method automated terminal update feature
  • setTipAdjust() - Replaced by setTerminalConfig() method
• Deprecated delegate methods:
  • onBadCardRead()
  • onFileWriteComplete()
  • onFileWriteUpdate()
  • onProgessChanged()
  • onStatusMessage()
  • onTransactionCancelled()
• Misc bug and memory leak fixes

Android Quick Start Guide

To use the middleware you will first need a Castles MP200 loaded with USAePay's Payment Engine software. For information on ordering the device, contact your merchant service provider.

The easiest way to get started with the middleware SDK is to download and build the demo application:

• You will need:
  • Android Studio 2.1+,
  • a supported Android device, and
  • a Castles MP200 with the latest terminal software.
• Download the latest demo application.
• Extract the zip and open the enclosed project "MP200_public_demo".
• Resolve any missing plugins and SDKs.

Add

• Add the following to your AndroidManifest.xml in order to grant permissions for Bluetooth.

add to AndroidManifest.xml

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.INTERNET" />

Edit

• Edit the file app/src/main/java/com/usaepaydemo/MainActivity.java and update following lines to include your source key and PIN. Also uncomment the host line if sandbox is being used.
  • Please Note: Source keys must have a PIN configured for the middleware to function.

edit MainActivity.java

private String sourceKey = "INSERT SOURCE KEY HERE";
private String pin = "INSERT PIN HERE";
//    private String host = "sandbox.usaepay.com";

Pair

• Pair the Terminal and Android device.

STEP 1:

On your supported Android device, go to Settings -> Device -> Wireless -> Bluetooth -> select the MP200 device.

STEP 2:

Press and hold the Bluetooth button on the MP200 until it requests a PIN, then select the MP200 in the Bluetooth menu of the Android device and enter the PIN on the MP200.

STEP 3

Wait until the Android device displays a green check mark and click "OK". On your phone/tablet you should see the MP200 listed in the "Paired Devices". Please Note: If the MP200 is going to be used with multiple phones/tablets, it must be unpaired from other devices before it can be paired a new phone/tablet.

• Build and run the demo app on your Android device.

Android SDK Usage Overview

Instantiation

First, instantiate the UEMiddleware class:

Instantiation - (Java)

private UEMiddleware ueMiddleware;
ueMiddleware = new UEMiddleware("MP200", parent, eventDelegate, logDelegate);

• The first parameter is the type of device that is being targeted. If multiple devices of the same type are connected, the first will be selected.
  Alternately, a list of connected devices can be retrieved and a specific device can be passed as the first parameter. See the constructor documentation for details.
• The second parameter is the parent activity. The middleware needs this to access bluetooth functionality, access files, etc.
• The third parameter is the call back delegate. This delegate will handle all callbacks from the middleware. It must implement the UEMiddlewareInterface. In the demo application, this is the TransactionHelper class. See the UEMiddlewareInterface documentation for a list of the available call back functions.
• The fourth parameter is the logging delegate. This delegate allows developers to track the internal state of the middleware. It must implement the OnLog interface.

Connecting to Device

The next step is to connect to the terminal.

Connection - (Java)

ueMiddleware.connect(mConnType, sourceKey, pin);
// or if sandbox is being used:
// ueMiddleware.connect(mConnType, sourceKey, pin, "sandbox.usaepay.com");

• The first parameter is the type of connection: use "BT" for bluetooth or "USB" for usb.
• The second parameter is the merchant's source key and the third parameter is the merchant's PIN. Please Note: Both are required. Source keys without PINs are NOT supported by the middleware.
• The fourth parameter is optional. It can be used to override the gateway host being connected to. It is normally used to switch to the sandbox system.

The connection process may take some time because the middleware is verifying the firmware version and the config of the payment terminal. When the update is complete and the device connected, the onConnected method on the callback delegate will be called.

If any problems are encountered the onError method will be called.

Starting a Transaction

Once a connection is established between the phone/tablet and the payment device, the next step is to start the transaction.

Start Transaction - (Java)

ueMiddleware.startTransaction(transInfo, sourceKey, pin, manualKey, promptTip);

• The first parameter is a HashMap that holds UEMConstants as keys and the corresponding transaction details as the values.
• The second and third parameters are the source key and PIN for the merchant.
• The fourth parameter is a boolean when set to true will trigger a manually-keyed transaction.
• The fifth parameter is a boolean when set to true will prompt the customer for a tip.

Once the transaction finishes processing, the onTransactionComplete method on the callback delegate will be called.

After a Transaction Completes

Once a transaction has completed, the onTransactionComplete method on the callback delegate will be called. At this point, the disconnect method needs to be called and UEMiddleware object must be re-instantiated.

Disconnect - (Java)

ueMiddleware.disconnect();

Tip Support

If merchants wish to support tip amounts, there are several options available:

Prompt for Tip in App

• The developer should prompt for tip in the UI of their application.
• startTransaction is called with the tip field present in the transInfo HashMap and the promptTip parameter set to false.
• The amount field should include the tip amount in the total.
• Works with all card types, regardless of supported CVMs.
• Works regardless of the terminal config.

Prompt for Tip on Terminal

• startTransaction is called with promptTip parameter set to true.
• Terminal will prompt customer to enter tip amount.
• Tip amount is added onto the original amount and passed in the transInfo HashMap in the amount field for authorization.
• Works with all card types, regardless of CMV support.
• Will not work with the Tip Adjust terminal config. Use the ALLCVM base config and make sure enable_tip_adjust parameter is set to false.

Adjust Tip Post Authorization

• startTransaction is called with amount field NOT including tip amount.
• After authorization, the tip amount is typically entered on paper receipt in conjunction with signature.
• startTransaction is called again with the amount field set to new total (which now includes the tip amount), the tip field set to the tip amount and the refNum field set to the transaction refnum received during the original authorization.
• PIN CVM must be disabled and will NOT work with cards that require PIN CVM.
• Will not work with the ALLCVM terminal config. Use the Tip Adjust base config and make sure enable_tip_adjust parameter is set to true.

Software Updates

The payment engine SDK will automatically push updates to the terminal as needed including firmware, terminal configs, display configs and CAPKs. This automatic update is initiated when the connect() method is used.

For automatic updates to be successful, the developer will need to maintain a current version of the payment engine SDK. In addition to checking the version of software on the terminal, the SDK also cross checks against the version of the SDK library. If a developer allows the SDK to get too far out of date, it may not be able to support newer devices due to version incompatibility. When this situation arises, the connect() method will result in an onError().

Classes

UEMiddleware Class

• UEMiddleware()
  
• clearCachedFiles()
  
• connect()
• disconnect()
• doPerformTermUpdate()
• getAdvancedAPI()
• getAvailableDevices()
• getDeviceInfo()
• getGatewayInfo()
• getMerchantCapabilities()
• getReceipt()
• getSoftware()
• hardReset()
• isConnected()
• returnPartialAuthDecision()
• setConnectionType()
• setSourceAndPin()
• setTerminalConfig()
• setTipAdjust()
• startTransaction()
• updateDevice()

UEMiddleware()

Constructor - (Java)

UEMiddleware(String devicename, Activity parent, UEMiddlewareInterface callback, OnLog logger)

Parameters

Type	Parameter	Description
String	devicename	Name of device, should be "MP200"
Activity	parent	The parent activity
UEMiddlewareInterface	callback	Object to handle middleware delegate methods, must implement the UEMiddlewareInterface
OnLog	logger	Object to handle logger delegate methods, must implement OnLog Interface

Exceptions

• MiddlewareException will be thrown if any of the parameters are passed with a null value.

clearCachedFiles()

clearCachedFiles() - (Java)

void clearCachedFiles()

This method will clear all terminal configuration and software update information that is stored locally on the Android device. This method can only be run before the device is connected. On the next connect(), the terminal configuration will be rewritten to the terminal and software updates will be checked. This method is only necessary in situations where the developer wants to force the config and update checks. It is not normally required, because the middleware will apply changes on a regular schedule.

Delegate Methods

Delegate Methods - (Java)

onError(UE_ERROR.DEVICE_CONNECTED)

The onError() delegate method will be called back if an attempt is made to clearCachedFiles while the device is already connected or in the process of connecting. To avoid this error, make sure to call clearCachedFiles after instantiation, but before connect().

connect()

connect() - (Java)

void connect(String connType, String sourceKey, String pin, String host)
// Use the above to connect to the first device found and use the specified gateway host.

void connect(String connType, String sourceKey, String pin)
// Use the above to connect to the first device found and use default gateway host "www.usaepay.com".

void connect(BluetoothDevice btDevice, String sourceKey, String pin, String host)
// Use the above to connect to a specific bluetooth device "btDevice" with the specified host.

void connect(BluetoothDevice btDevice, String sourceKey, String pin)
// Use the above to connect to a specific bluetooth device "btDevice" and default host to "www.usaepay.com".

This method establishes a connection between a phone/table and the payment device. There are a few overloads for the connect method that allow developers to override the default gateway host (www.usaepay.com) and use a specified gateway host (like the sandbox) instead. Developers can also choose a specific bluetooth device rather than the first device found.

Parameters

Type	Parameter	Description
String	connType	(Variant 1) Type of connection between phone/tablet and payment device (Ex: "BT" for Bluetooth, "USB" for USB )
BluetoothDevice	btDevice	(Variant 2) Bluetooth Device
String	sourceKey	Merchant's source key
String	pin	Merchant's PIN
String	host	(Optional) Host to connect to. This must be just a hostname, not a url. For example: "www.usaepay.com" or "sandbox.usaepay.com"

Exceptions

• MiddlewareException will be thrown if any of the parameters are passed in with a null value.
• MiddlewareException will be thrown if the hostname parameter is not a valid hostname.

Delegate Methods

The following delegates may be returned:

• onConnected() will be called when a connection is established between phone/tablet and payment device.
• onError(NO_BT_DEVICE) method will be called when no compatible bluetooth devices were detected. Double check that the MP200 has already been paired in the Android settings screen.
• onError(NO_DEVICES_FOUND) method will be called when a compatible device was not found. Double check the usb cable.
• onStatusChanged(message) method will be called with a message indicating the status of the connection.
• onDisconnected() method will be called if a Bluetooth device drops the connection while the connect process is running.

Retrieving Specific Bluetooth Device

getAvailableDevices() - (Java)

    ArrayList<BluetoothDevice> devices = ueMiddleware.getAvailableDevices();
    if(devices.size() == 0) throw new Exception("No devices found");
    ueMiddleware.connect(devices.get(0), sourceKey, pin, host);

A device list can be retrieved by calling the getAvailableDevices() method.

disconnect()

disconnect() - (Java)

void disconnect()

Disconnects the device. Needs to be called whenever a transaction completes.

Delegate Methods

The following delegates may be returned:

• onDisconnected() method will be called when payment device is disconnected from phone/tablet.
• onStatusChanged(message) method is called with a message indicating the status of the disconnection.

doPerformTermUpdate()

doPerformTermUpdate() - (Java)

void doPerformTermUpdate()

Perform any outstanding terminal updates.

getAdvancedAPI()

getAdvancedAPI() - (Java)

UEAdvancedAPI getAdvancedAPI()

Example - (Java)

try {
    UEAdvancedAPI api = ueMiddleware.getAdvancedAPI();
    JSONObject res = api.sendRESTRequest("https://www.usaepay.com/api/v2/info", "GET", sourceKey, pin, request[0]);
} catch(Exception e) {
    e.printStackTrace();
}

The UEAdvancedAPI is a wrapper to a rest client for accessing the gateway rest api.

Returns

Type	Description
UEAdvancedAPI	Returns an instance of the api client

Example: Running on Main Thread

Example: Running on Main Thread - (Java)

public class YourActivity extends AppCompatActivity {


        private class YourBtnListener implements Button.OnClickListener {
            @Override
            public void onClick(View v) {
                    JSONObject request = new JSONObject();
                    new RestTask().execute(request);
            }
        }

        private class RestTask extends AsyncTask<JSONObject, Integer, JSONObject> {
            protected JSONObject doInBackground(JSONObject... request) {

                // get api instance
                UEAdvancedAPI api = ueMiddleware.getAdvancedAPI();

                JSONObject res;
                try {
                    // perform rest request
                    res = api.sendRESTRequest("https://www.usaepay.com/api/v2/info", "GET", sourceKey, pin, request[0]);

                } catch(Exception e) {
                    res = new JSONObject();
                    try {
                        res.put("error", e.getLocalizedMessage());
                    }catch(Exception e2) {

                    }
                }
                return res;
            }


            protected void onPostExecute(JSONObject result) {
                // do something with the result
                Log.d(TAG, "Result: " + result.toString());
            }

        }
}

The api client is asynchronous and will throw a "NetworkOnMainThreadException" if you attempt to run it on the main UI thread. You will need to create an AsyncTask or something similar:

getAvailableDevices()

getAvailableDevices() - (Java)

ArrayList<BluetoothDevice> getAvailableDevices()

Example - (Java)

    ArrayList<BluetoothDevice> devices = ueMiddleware.getAvailableDevices();
    if(devices.size() == 0) throw new Exception("No devices found");
    ueMiddleware.connect(devices.get(0), sourceKey, pin, host);

When using the MP200, call this to get the list of available paired bluetooth MP200 devices. This list is filtered and only displays devices containing name "MP200". Devices can be identified by the last 4 of the serial number (located on the back of the MP200).

Returns

Type	Description
ArrayList<BluetoothDevice>	List of available devices

If no devices are found, an empty array list will be returned.

getDeviceInfo()

getDeviceInfo() - (Java)

void getDeviceInfo()

Retrieves information about the connected device. You must connect() to the device first. Once all details have been retrieved from the device, the onDeviceInfoReceived() delegate will be called.

Delegate Methods

The following delegates may be returned:

• onDeviceInfoReceived() will be called once all information has been retrieved from the device.
• onError(UE_ERROR.UPDATING) will be called if the device is currently busy. Wait for the onConnected() delegate before calling getDeviceInfo().

getGatewayInfo()

getGatewayInfo() - (Java)

void getGatewayInfo()

Retrieves information on the gateway environment. Calls the onGatewayInfoReceived() delegate when the data is available.

getMerchantCapabilities()

getMerchantCapabilities() - (Java)

void getMerchantCapabilities()

Get the processing capabilities of the merchant. Calls the onMerchantCapabilitiesReceived() delegate with the merchant capabilities.

getReceipt()

getReceipt() - (Java)

void getReceipt(String template, String refNum, String sourceKey, String pin, String returnType)

Example

public void onTransactionComplete(UEMTransactionResult transResults) {
    Log.d(TAG, "onTransactionComplete()");

    if (!transResults.hasError()) {

        ueMiddleware.getReceipt("PointOfSale",RefNum,"html");

    }
}

public void onReceiptReceived(String receipt) {
    Log.d(TAG, "onReceiptReceived()");
    Log.d(TAG, "Receipt: " + receipt);
}

Retrieve a receipt for transaction referenced by refNum field. Receipt template is selected using the template" parameter. The rendered receipt is returned as a String to the onReceiptReceived() delegate.

Parameters

Type	Param	Description
String	template	Name of template to pull. Use "PointOfSale" for an EMV compliant receipt template. Merchants can also create custom receipt templates in the merchant console.
String	refNum	Transaction reference number
String	returnType	Format of receipt template referenced. Possible values are: "html" or "text"

Exceptions

• MiddlewareException will be thrown if any of the parameters are passed in with a null value.

Delegates

• onReceiptReceived() will be called once the receipt is successfully retrieved from the gateway.
• onError() will be called if an error occurs, such as error connecting to the gateway. Other errors include:
• onError(RECEIPT_NOT_FOUND) will be called if the template did not match any of the named receipt templates available on the merchants account.
• onError(TRANSACTION_NOT_FOUND) will be called if the refNum did not match a transaction.
• onError(RECEIPT_FORMAT_NOT_FOUND) will be called if the receipt is either not available in the requested returnType or an invalid returnType was passed.

hardReset()

hardReset() - (Java)

void hardReset()

Aborts any running operations and causes the terminal to reboot. Please note: This method is not supported with the Castles MP200.

isConnected()

isConnected() - (Java)

boolean isConnected()

Returns true if phone/tablet is connected to payment device, and returns false otherwise.

returnPartialAuthDecision()

returnPartialAuthDecision() - (Java)

void returnPartialAuthDecision(boolean doAuth)

When asked for partial auth through the onPromptForPartialAuth(String String), use this command to continue the transaction.

Parameters

Type	Parameter	Description
boolean	doAuth	Set to true to proceed with the auth amount, and false to decline and discontinue the transaction.

setConnectionType()

setConnectionType() - (Java)

void setConnectionType(int connType)

Sets connection type for MP200.

Parameters

Type	Parameter	Description
int	connType	0 = BT (bluetooth), 1 = USB

setSourceAndPin()

setSourceAndPin() - (Java)

void setSourceAndPin(String sourceKey, String pin)

Sets the gateway source key, and pin. Must be set before the transaction can be sent.

Parameters

Type	Parameter	Description
String	sourceKey	Merchant's source key
String	pin	Merchant's pin

setTerminalConfig()

setTerminalConfig() - (Java)

public void setTerminalConfig(TerminalConfig config):

public void setTerminalConfig(TerminalConfig config, boolean force):

Examples - (Java)

// Use AllCVM base config  (Credit/Debit selection enabled)
TerminalConfig tc = TerminalConfig.getAllCVMConfig();
ueMiddleware.setTerminalConfig(tc);
ueMiddleware.connect(mConnType, sourceKey, pin, host);

// Use AllCVM base config and then disable Credit/Debit selection
TerminalConfig tc = TerminalConfig.getAllCVMConfig();
tc.setEnable_debit_msr(false);
ueMiddleware.setTerminalConfig(tc);
ueMiddleware.connect(mConnType, sourceKey, pin, host);

// Use TipAdjust base config
TerminalConfig tc = TerminalConfig.getTipAdjustConfig();
ueMiddleware.setTerminalConfig(tc);
ueMiddleware.connect(mConnType, sourceKey, pin, host);

The command sets the terminal configuration. This must be called prior to connect()

Please Note: The middleware will compare the requested terminal configuration against the merchant capabilities. It is possible that some features such as EMV, contactless and Tip Adjust are not available due to the merchant's platform config. If no terminal config is set, the middleware will use the last applied config (stored on terminal). If no config exists on the terminal the middleware will default to the max capabilities of the merchant.

There are two base configs:

ALLCVM

This terminal config enables all EVM cardholder verification methods including signature, PIN and NOCVM (for low ticket transactions). Tip amounts must be added prior to authorization and the amount can not be adjusted after authorization. This config can be retrieved with TerminalConfig.getAllCVMConfig() and contains the defaults:

• enable_emv = true;
• enable_debit_msr = true;
• enable_tip_adjust = false;
• enable_contactless = true;

Tip Adjust

Allows a tip amount to be added after authorization. This is achieved by disabling all CVMs other than signature. This config can be retrieved with TerminalConfig.getTipAdjustConfig() and contains the defaults:

• enable_emv = true;
• enable_debit_msr = false;
• enable_tip_adjust = true;
• enable_contactless = true;

Parameters

Type	Parameter	Description
%terminal_config%	config	The terminal config object describing desired features.
boolean	force	(optional) Forces an update to the terminal config. The middleware keeps track of the currently active terminal config and only writes a new one to the terminal if a change is detected. By setting force to "true", it will ignore the stored config and write the new config to the terminal. This can also be achieved by using the clearCachedFiles() method.

Exceptions

• MiddlewareException will be thrown if any of the parameters are passed in with a null value.

Delegate Methods

Delegate Methods - (Java)

onError(UE_ERROR.DEVICE_CONNECTED)

The onError() delegate method will be called back if an attempt is made to setTerminalConfig while the device is already connected or in the process of connecting. Make sure to call setTerminalConfig after instantiation but before connect().

setTipAdjust()

setTipAdjust() - (Java)

void setTipAdjust(boolean tipAdjust)

Enables tip adjust.

Parameters

Type	Parameter	Description
boolean	tipAdjust	Set to true to enable tip adjust in transaction, false otherwise

startTransaction() - Android

startTransaction() - (Java)

void startTransaction(HashMap<String, String> transInfo,
                                             boolean manualKey,
                                             boolean promptTip)

Starts a transaction request. The terminal will prompt the customer to swipe, tap or dip their card depending on the merchant's capabilities. If promptTip parameter is set to true then they customer will be asked for a tip amount. The customer is then prompted to confirm the amount. The transaction is sent to the gateway for processing. When the gateway response is received or an error occurs, the onTransactionComplete event will be triggered. If the customer hits the cancel button on the terminal, the onTransactionCancelled event will be triggered. Developers will need to implement these two methods on their delegate to properly handle the transaction flow.

Parameters

Type	Parameter	Description
HashMap	transInfo	HashMap that holds information about the transaction. See below.
boolean	manualKey	Set to true to trigger a manually-keyed transaction
boolean	promptTip	Set to true to prompt the customer for a tip

Exceptions

• MiddlewareException will be thrown if any of the parameters are passed in with a null value.

Supported Commands

cc:sale
- This command is the default processing command. The 'cc:sale' command runs a standard credit/debit card sale. It will charge the customers credit/debit card for the amount specified. This command requires that the amount field be populated. Once called, the terminal will collect the payment method from the customer and then send the transaction for processing. If the charge is successful, the transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

cc:authonly
- This command runs a credit/debit card authorization. This command requires that the amount field be populated. Once called, the terminal will collect the payment method from the customer and then send the transaction for processing. If approved, the funds will be held in the customers account. The funds will remain oh hold until either the transaction is captured and settled, or until the authorization code expires. The length of time before an authorization expires varies from bank to bank, but generally it is recommended that authorizations be captured within 24-48 hours. Merchants should consult their merchant service provider for information specific to their account. If a merchant does not capture the transaction, no funds will be received by the merchant.

capture
- This command moves 'cc:authonly' transactions into the batch for settlement. The original Transaction ID (refnum) must be passed in refNum field. Additionally, the amount of originally authorized may be adjusted by passing the amount field. The tolerances for the settle amount vary depending on the type of merchant account and the merchant service provider. The transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

adjust - This command allows you to make changes to an existing (unsettled) sale. The authorization amount can be increased (incremental authorization), decreased (partial reversal), or not changed. Additional data elements such as tax amount and PO number can also be added. The original Transaction ID (refnum) must be passed in refNum field. The tolerances for the settle amount vary depending on the type of Merchant Account and the merchant service provider. The adjust and capture commands function identically except that the adjust command does not place the transaction in the batch (see example below).

cc:credit
- This command performs an open credit (refund) to a card. It requires the amount field be populated. The terminal will then prompt the customer for the payment method, and then send the transaction to the gateway for processing.

void:release
- This command cancels a pending (sale, authonly, or credit) transaction. For credit card transactions, this command removes the transaction from the current batch. There is a limited amount of time that a void may be run. For credit cards, a transaction can no longer be voided once the batch has been closed. The void requires that the original Transaction ID number be passed in the refNum field. The terminal is not used, and the transaction is sent directly to the gateway.

transInfo Fields

The majority of these are optional, the only required field is "Amount".

Key	Description
command	Processing command, typically "cc:sale" or "cc:authonly". See above for more information.
amount	Total amount to authorize (including tax, shipping, etc). If promptTip parameter is set to "true", this amount will be added to the tip for the total authorization amount.
tax	Tax amount
nontaxable	Transaction is non taxable
tip	If the promptTip parameter is not set, the tip may be passed in this field. The third option is to use the Tip Adjust terminal config which allows for the tip to be added post authorization.
shipping	Shipping amount
duty	Duty charge (Required only for level 3)
discount	The amount of any discounts that were applied.
description	Transaction description
comments	Internal transaction notes (not included on customer receipt). Optional.
custid	Merchant assigned customer id.
invoice	Invoice number, only the first 11 characters are used.
orderid	Order identifier. This field can be used to reference the order to which this transaction corresponds. This field can contain up to 64 characters and should be used instead of invoice when orderid is longer that 10 digits.
ponum	Purchase Order number. Only required for corporate purchasing cards.
clerk	Indicates the clerk/person processing transaction, for reporting purposes. (optional)
tranterm	Indicates the terminal used to process transaction, for reporting purposes. (optional)
resttable	Indicates the restaurant table, for reporting purposes. (optional)
enablePartialAuth	Set to "true" to enable partial authorization.
refNum	Gateway assigned transaction id number. Necessary for commands that modify an existing transaction, such as "adjust" or "void:release".
timeout	Max number of seconds to wait for a response from the gateway. This does not limit how long the customer has to swipe their card.
target	deprecated set the gateway url. This is now done in the connect().

Address Fields:

Billing Key	Shipping Key	Description
billfname	shipfname	First Name
billlname	shiplname	Last Name
billcompany	shipcompany	Company Name
billstreet	shipstreet	Street Address
billstreet2	shipsreet2	Additional street information (if needed)
billcity	shipcity	City
billstate	shipstate	State
billzip	shipzip	Zip/Postal code
billcountry	shipcountry	Country
billphone	shipphone	Phone Number
email
fax
website

Line Item Details:

Replace * with the line number 1-99999.

Field	Max Length	Description
line*productrefnum	12	(optional) Gateway assigned product RefNum, used for inventory control.
line*sku	32	Product id, code or SKU
line*name	255	Item name or short description
line*description	64k	Long description
line*cost	00000000.00	Cost of item per unit of measure (before tax or discount)
line*qty	00000000.0000	Quantity
line*taxable	1	Y = Taxable, N = Non-taxable
line*taxrate	00.000	Tax rate for line (only required for level 3 processing).
line*taxamount	00000000.00	Amount of tax charge for line (if left blank will be calculated from taxrate)
line*um	12	Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used.
line*commoditycode	12	Commodity code (only required for level 3 processing). See http://www.unspsc.org/ for valid list of codes.
line*discountrate	000.000	Discount percentage for line (only required for level 3 processing).
line*discountamount	00000000.00	Discount amount for line (if left blank will be calculated from discountrate).

Delegate Methods

The following delegates may be returned:

• onTransactionComplete() method will be called for all errors, declines or approvals. It is called after all transaction operations have been completed.
• onPromptForPartialAuth() method will be called when a transaction is approved for less that the full amount requested. The developer must tell the middleware how they want to complete the transaction by calling the returnPartialAuthDecision() method.
• onSeePhoneNFC() method will be called during a contactless transaction if the customer needs to take an additional step on their phone (such as enter a password). The transaction will continue once the user takes this action, the developer does not need to do anything, and it is not required that this delegate do anything.
• onStatusChanged() is called when the transaction moves to the next step in the processing flow.
• onError() - is called when startTransaction is passed invalid parameters.
• onError(INVALID_COMMAND) is called when "command" in "transInfo" was not one of the supported commands.
• onError(REFNUM_REQUIRED) is called when "void:release" and "capture" commands are called and the "refnum" parameter was not included.

Example: Extracting the RefNum from onTransactionCompleted

The RefNum is needed if you are going to adjust or void the transaction.

Example: Extracting the RefNum from onTransactionCompleted - (Java)

public void onTransactionComplete(UEMTransactionResult transResults) {
    Log.d(TAG, "onTransactionComplete()");

    String RefNum = "NA";
    if(transResults.getGatewayTransactionResults().containsKey("UMrefNum")) RefNum = transResults.getGatewayTransactionResults().get("UMrefNum");
}

Example: Adjusting a Transaction

Example: Adjusting a Transaction - (Java)

HashMap<String,String> captureInfo = new HashMap<String,String>();
captureInfo.put("command", "adjust");
captureInfo.put("refNum", RefNum);
captureInfo.put("tip", "1.00");

BigDecimal totalAmount = new BigDecimal(transInfo.get("amount"));
totalAmount.add(new BigDecimal("1.00"));

captureInfo.put("amount", totalAmount.toString());
Log.d(TAG, " captureInfo: " + captureInfo.toString());


try {
    ueMiddleware.startTransaction(captureInfo,  false, false);
} catch (MiddlewareException e) {
    e.printStackTrace();
}

The following example can be used to add a tip to a transaction. Please note: This will only work on an EMV transaction if the Terminal Config has been set to tipadjust. RefNum is the value received during the authorization.

Example: Voiding a Transaction

Example: Voiding a Transaction - (Java)

HashMap<String,String> voidInfo = new HashMap<String,String>();
voidInfo.put("command", "void:release");
voidInfo.put("refNum", RefNum);
Log.d(TAG, " voidInfo: " + voidInfo.toString());

try {
    ueMiddleware.startTransaction(voidInfo,  false, false);
} catch (MiddlewareException e) {
    e.printStackTrace();
}

The following example demonstrates voiding a transaction and releasing the funds back to the cardholder. RefNum is the value received during the authorization.

updateDevice()

updateDevice() - (Java)

void updateDevice()

UEMTransactionResult

Type	Getter	Description
HashMap	getGatewayTransactionResults()	A HashMap containing the raw transaction response variables passed through from the gateway. (see below)
%CVMRESULT%	getCvmResult()	Indicates the card verification method used.
TreeMap	getReceiptData()	A TreeMap containing information required for generating a receipt (see below)
String	getTransResponseCode()
String	getDataSource()	The source of the payment (i.e. 'swipe','tap', 'dip').
String	getRawGatewayResponse()	The raw transaction response string passed through from the gateway.
HashMap	getTransData()	Transaction Data (see below)
boolean	hasError()	True if the transaction did not complete successfully
%UE_ERROR%	getError()
boolean	isSignatureRequired()	Indicates that a customer signature is required. This can either be handled by printing a signature line on the receipt or by capturing a signature digitally. The developer is responsible for submitting the signature image using the transaction adjust call.
HashMap	getICCData()	A HashMap containing the ICC Tags. These will be needed if manually generating a receipt.

Gateway Transactions Results

Result data from the gateway. Click here for more details. Not all variables will be returned depending on transaction type.

Key	Description
UMstatus	Status of the transaction. The possible values are: Approved, Partially Approved, Declined, Verification and Error.
UMauthCode	Authorization number.
UMauthAmount	Amount authorized. May be less than amount requested if UMenablePartialAuth=yes.
UMrefNum	Transaction reference number
UMbatch	Batch reference number. This will only be returned for sale and auth commands. Please Note: The batch number returned is for the batch that was open when the transaction was initiated. It is possible that the batch was closed while the transaction was processing. In this case, the transaction will get queued for the next batch to open.
UMremainingBalance	Returns the balance remaining on some prepaid and stored value cards.
UMavsResult	AVS result in readable format.
UMavsResultCode	AVS result code.
UMcvv2Result	CVV2 result in readable format.
UMcvv2ResultCode	CVV2 result code.
UMvpasResultCode	Verified by Visa (VPAS) or Mastercard SecureCode (UCAF) result code.
UMresult	Transaction result. Possible values are: A, P, D, E, or V (for Verification)
UMerror	Error description if UMstatus is Declined or Error.
UMerrorcode	A numerical error code.
UMisDuplicate	Indicates whether this transaction is a folded duplicate or not. 'Y' means that this transaction was flagged as duplicate and has already been processed. The details returned are from the original transaction. Send UMignoreDuplicate to override the duplicate folding.
UMconvertedAmount	Amount converted to merchant's currency, when using a multi-currency processor.
UMconvertedAmountCurrency	Merchant's currency, when using a multi-currency processor.
UMconversionRate	Conversion rate used to convert currency, when using a multi-currency processor.
UMcustnum	Customer reference number assigned by gateway. Returned only if UMaddcustomer=yes.
UMprocRefNum	Transaction Reference number provided by backend processor (platform), blank if not available.
UMcardLevelResult	Card Level Results (for Visa cards only), blank if no results provided.
UMcardRef	Card reference token. 16-19 digit alphanumeric string. It is returned with dashes but it is not required that these be stored.
UMcardType	The type of card that was submitted, i.e. Visa, MasterCard, Discover.
UMmaskedCardNum	The masked out card number including the last 4 digits.

Receipt Data

If you are generating a receipt manually, ALL of these values are required. We recommend developers utilize the getReceipt() method instead.

Key	Description
AID
AID Name
ATC
CVM_Results
Cryptogram
MID
TSN
authCode
command	The command that was run.
error	String describing error. In case of approval it may contain "Approved".
refNum	Unique gateway assigned transaction reference number.
responseCode	Response code, possible values are: A = Approved, D = Declined, E = error, P = partial approval.
transResult	Long text of transaction response (i.e. "Approved").
transDataSource	How was the card data read (ICC Chip).

Transaction Data

The data that was sent to the gateway for processing. See the field list on the startTransaction method() page.

TerminalConfig Object

Constructor - (Java)

public TerminalConfig(
      String device_name,
      boolean enable_emv,
      boolean enable_debit_msr,
      boolean enable_tip_adjust,
      boolean enable_contactless);

See the setTerminalConfig() method

Parameters

Type	Parameter	Description
String	device_name	Name of device, should be "MP200".
boolean	enable_emv	Enable EMV transactions. When set to "false", the terminal will ignore a card dip.
boolean	enable_debit_msr	Enable debit MSR transactions. (Tip adjust not allowed) Changing this value will require a terminal reboot.
boolean	enable_tip_adjust	Enable tip adjustable transactions. Transaction amount can be adjusted after authorization.
boolean	enable_contactless	Enable contactless. When set to "false", the terminal will ignore a contactless (tap) payment.

Interfaces

UEMiddlewareInterface

• onAlertUser()
• onBadCardRead()
• onConnected()
• onDeviceInfoReceived()
• onDisconnected()
• onError()
• onFileWriteComplete()
• onFileWriteUpdate()
• onGatewayInfoReceived()
• onMerchantCapabilitiesReceived()
• onProgressBarUpdateAvailable()
• onProgessChanged()
• onPromptForPartialAuth()
• onReceiptReceived()
• onSeePhoneNFC()
• onStatusChanged()
• onStatusMessage()
• onTransactionCancelled()
• onTransactionComplete()
• onUpdateCheckResultsReceived()
• onWaitingForCardRemoval()

onAlertUser()

onAlertUser() - (Java)

void onAlertUser(java.lang.String message)

Called to alert the user to perform an action. This is generally implemented with an AlertDialog.

onConnected()

onConnected() - (Java)

void onConnected()

To connect to payment device call the connect() method. Once the connection to the payment terminal has completed successfully the onConnected() method will be fired. You can then proceed to startTransaction().

If the connection is not successful, the onError() method will be called.

onDeviceInfoReceived()

onDeviceInfoReceived() - (Java)

void onDeviceInfoReceived(java.util.HashMap<java.lang.String,java.lang.String> allParams)

Called in response to getDeviceInfo(). "allParams" contains a HashMap of key value pairs describing the connected hardware.

Device Info Hash Map

Key	Example	Description
serialNum	0003130000123456	Serial number of device
vendorID	0005	ID of device manufacturer
productID	MP200	Model of the device
hwVersion	FFFFFFFF	Hardware version
swVersion	16072141	Software version
batteryLevel	d	Current charge of the battery
deviceState		Current device state (should always be blank)
DUKPT	FFFF3D0100	KSN for debit encryption
DUKPT_MAC	FFFFFFFFFFF	MAC for debit encryption
DUKPT_DEFAULT	FF991C0000	KSN for e2e encryption
SRED	FFFF987654	KSN for e2e encryption (SRED)

onDisconnected()

onDisconnected() - (Java)

void onDisconnected()

Called when the middleware has disconnected from the device. See the disconnect() method.

onError()

onError() - (Java)

void onError(UE_ERROR error)

Called when there is a error. When processing a transaction you should rely on the result returned by onTransactionComplete. If the operation cannot proceed it will have been cancelled gracefully. No need to call cancel. Get text using UE_ERROR.text

UE_ERROR

Constant	Description
ALREADY_STARTED
BAD_SWIPE	MP200 received bad swipe, Transaction will be aborted, retry.
GATEWAY_401_UNAUTHORIZED
GATEWAY_CONNECTION_ERROR	The connection to the gateway failed.
GENERAL_EXCEPTION_CAUGHT	Exception from Exception class caught, stack trace printed, report this error.
HANDLED	These errors go out to the user.
INVALID_AMOUNT	The amount entered was invalid.
INVALID_MAG_STRIPE	The transaction was terminated because of a bad mag swipe, x3 retried.
INVALID_TERMINAL_CONFIG
INVALID_UPDATE_PARAMETER
LOW_BATTERY	Low battery, plug in the MP200.
MP200_COMMAND_TIMEOUT	Command to MP200 timed out, transaction will abort, retry.
NO_BT_DEVICE	No BT Device was found, check BT settings.
NO_DEVICES_FOUND
NO_ERROR
NOT_CONNECTED	The device is not in the connected state to execute this function.
NOT_ENOUGH_SPACE_FOR_UPDATE	Free up memory in the app cache directory.
TIMEOUT_GATEWAY	Timeout has occurred between gateway.
TRANSACTION_CANCEL_BUTTON	The transaction was cancelled by pressing the cancel button.
TRANSACTION_CARD_ERROR
TRANSACTION_CARD_REMOVED
TRANSACTION_INVALID_PIN	Transaction was terminated because of an invalid PIN.
TRANSACTION_REQUESTS_CHANGE_INTERFACE	This will also fire a delegate to change interface.
UNHANDLED_ERROR	Unhandled Error, please report this.
UNHANDLED_EXCEPTION
UNHANDLED_EXCEPTION_CAUGHT
UPDATE_COMPLETE
UPDATE_FAILED	An error occurred during the update process caused it to fail.
USB_CONNECTION_CLOSED	USB Connection has been closed, reconnect.
USER_INPUT_EXCEPTION

onProgressBarUpdateAvailable()

onProgressBarUpdateAvailable() - (Java)

void onProgressBarUpdateAvailable(java.lang.String title,
                                  java.lang.String message,
                                  float percent)

The middleware provides an optional hook for the developer to implement a progress bar for display during longer operations such as a terminal firmware update.

Parameters

Param	Description
title	The suggested title of the progress bar
message	The suggested message
percent	The percentage (decimal 0 < 1) of the progress. -1 means the dialog should be cancelled, and -2 means there is no percentage available

onPromptForPartialAuth()

onPromptForPartialAuth() - (Java)

void    onPromptForPartialAuth(java.lang.String amountAuthorized, HashMap<String,String>  tranResults)

Example - (Java)

Log.d(TAG, "onPromptForPartialAuth() transaction partially approved for "+ amountAuthorized + " RefNum: " + tranResults.get("UMrefNum"));

// Tell the middleware you want to keep the transaction (onTransactionComplete will then be called)
ueMiddleware.returnPartialAuthDecision(true);

// Tell the middleware that you do not want to keep the partially approved transaction.   It will be
// voided and the funds returned to the customer
//ueMiddleware.returnPartialAuthDecision(false);

Called when the transaction is partially authorized.

Please Note: By default, partial authorization is not enabled. You must pass in "enablePartialAuth" as "true" when calling startTransaction(). If not enabled, transactions where the full auth amount is not available will be declined with the error "Insufficient Funds".

Returns string containing the amount that was authorized. It is the developers responsibility to prompt the customer for another payment method for the remaining amount, or to void:release the transaction.

IMPORTANT: The implementor must create a dialog which gives the user the choice to accept or decline the partial authorization. When the result is received the implementor must then call returnPartialAuthDecision().

onReceiptReceived()

onReceiptReceived() - (Java)

void onReceiptReceived(java.lang.String receipt)

Called back when the receipt is returned from the API. See the getReceipt method

Returns either an HTML or text string with the rendered receipt, depending on the receipt format.

onSeePhoneNFC()

onSeePhoneNFC() - (Java)

void onSeePhoneNFC(java.util.HashMap<java.lang.String,java.lang.String> tagData)

onStatusChanged()

onStatusChanged() - (Java)

void onStatusChanged(java.lang.String message)

Called when the status of a transaction changes. This method is only meant to give a realtime status of the transaction in progress. onTransactionComplete should be used when writing transaction result logic.

Possible Values
Approved
Declined
Need Castles Update!
Authorizing issuer data with card
Need Castles Update!
Need Middleware Update!
Error: xxx
Connecting MP200 with xxx
Connected
Transaction is starting
Transaction started, please complete payment on the MP200 reader
Transaction cancel was sent to the MP200
Disconnected

onTransactionComplete()

onTransactionComplete() - (Java)

void onTransactionComplete(UEMTransactionResult transResults)

Called when the transaction processing has completed (either successfully or unsuccessfully). Passes a UEMTransactionResult object containing transaction result details.

onUpdateCheckResultsReceived()

onUpdateCheckResultsReceived() - (Java)

void onUpdateCheckResultsReceived(MIDDLEWARE_STATUS statusCheck)

Called back after checkIfUpdateNeeded() is called.

MIDDLEWARE_STATUS enum

Constant	Description
CASTLES_NEEDS_UPDATE	The device needs to be updated to match the current SDK version.
CHECKING
MIDDLEWARE_NEEDS_UPDATE	The software installed on the terminal is newer than the middleware library. Developer must update the middleware SDK before using the connected device.
NEEDS_UPDATE
OK	Castles MP200 device and middleware are both up to date.

onWaitingForCardRemoval()

onWaitingForCardRemoval() - (Java)

void onWaitingForCardRemoval()

Called when the user should be prompted to remove the card. The transaction will not proceed until the card is physically removed from the terminal.

OnLog interface

onLog()

onLog() - (Java)

void onLog(java.lang.String msg)

Contains logging information on what is happening behind the scenes in the Middleware. Useful for debugging.

onLogTrace()

onLogTrace() - (Java)

void    onLogTrace(java.lang.String msg)

Detailed debug logs. Useful when troubleshooting terminal issues during development.

iOS MIDDLEWARE

The PaymentEngine Middleware library allow developers to process EMV, contactless and swiped transactions on the USAePay gateway. The library handles all communication between the hardware and the gateway. This allows developers to create rich mobile payment applications without the hassle and expense of EMV certification.

The library supports iOS 11.0+.

• Download the latest release: paymentengine-ios-sdk-2.3.19

• Getting Started Guide

• See the Quick Start Examples in the right pane

Quick Start Example - (Objective-C)

// .h

PaymentEngineMiddlewareSettings *middlewareSetting;
PaymentEngineMiddleware *middleware;

// .m

 - (void)viewDidLoad
{
    [super viewDidLoad];

    middlewareSetting = [PaymentEngineMiddlewareSettings getInstance];
    middleware = [PaymentEngineMiddleware getInstance];

    /*
    * The mode can be either sandbox or production
    * If developer wants to test on our sandbox server, they will set the currentMode to sandbox
    * It's not case sensitive
    */
    middlewareSetting.currentMode = @"Production";
    middlewareSetting.sourceKey = @"Your Source Key Here";
    middlewareSetting.pinNum = @"Your Pin Here";

    middleware = [PaymentEngineMiddleware getInstance];
    [middleware setDevice:@"castle" :self];
}

-(void)startTransaction
{

NSMutableDictionary *transDict = [NSMutableDictionary new];
[transDict setObject:@"40.00" forKey:@"amount"];
[transDict setObject:@"10000" forKey:@"invoice"];
[transDict setObject:@"cc:sale" forKey:@"command"];

    [middleware startTransaction:transDict];
}
-(void)transactionComplete :(PaymentEngineTransactionResponse *)transResponse
{
    NSLog(@"Transaction Result: %@", transResponse.Result);
    NSLog(@"Transaction Status: %@", transResponse.Status);
    NSLog(@"Transaction Error: %@", transResponse.Error);
}

Quick Start Example - (Swift)

// .swift

let middlewareSetting = PaymentEngineMiddlewareSettings.getInstance()
let middleware = PaymentEngineMiddleware.getInstance()

override func viewDidLoad()
{
    super.viewDidLoad()

    /**
    * The mode can be either sandbox or production
    * If developer wants to test on our sandbox server, they will set the currentMode to sandbox
    * It's not case sensitive
    */
    middlewareSetting?.currentMode = "Production";
    middlewareSetting?.sourceKey = "Your Source Key Here"
    middlewareSetting?.pinNum = "Your Pin Here"

    middleware?.setDevice("castle", self)

}

func startTransaction()
{
    //Creates an empty dictionary objects to hold all the transaction info
    let transDict  = NSMutableDictionary()

    transDict.setObject("cc:sale", forKey: "command" as NSCopying)
    transDict.setObject("40.00", forKey: "amount" as NSCopying)
    transDict.setObject("10000", forKey: "invoice" as NSCopying)
    transDict.setObject("This is my first middleware transaction", forKey: "description" as NSCopying)

    //Use the stratTransaction method from the UsaepayMiddleware class to start the transaction.
    middleware?.startTransaction(transDict)

}

func transactionComplete(_ transResponse: PaymentEngineTransactionResponse!)
{

    print("status = \( (transResponse.status ?? "status is nil.")!)")
    print("result = \( (transResponse.result ?? "result is nil.")!)")
    print("error = \( (transResponse.error ?? "error is nil.")!)")

}

PaymentEngineMiddleware Class	This is the main class that contains all the middleware interfaces.
setDevice setDelegate	Set which device to connect to (iCMP or MP200).
connectBluetoothDevice	Manually connect to selected bluetooth device.
getConnectedDevices	Retrieve a list of connected bluetooth devices.
isDeviceOnline	Returns true if device is connected, false otherwise.
disconnectDevice	Disconnects from device.
connectDevice	Establishes connection to device.
getDeviceInfo	Retrieves details about the device (Deprecated in v2.3.5).
readDeviceInfo	Sends a command to the device to retrieve device information.
cancelTransaction	Manually cancels the transaction.
printText	Manually prints text from V3
startTransaction	Starts a payment request.
captureSignature	Captures a customer's signature for an existing transaction. %holdCaptureInfo% stores all the required info to capture the signature.
adjustTransaction	Adjust an existing transaction. %holdTransInfo% stores all the required info to adjust a transaction.
getReceipt	Makes API Call to get receipt from EMV Template.
getV3Receipt	Makes API Call to get V3 receipt from EMV Template.
goOnline	Takes the device to an online status (Not supported by MP200).
goOffline	Take the device to an offline status (Not supported by MP200).
getMerchantCapabilities	Get the merchant's capability from the gateway.
displayImg	Manually display image on the castle device.
setDeviceTimeout	Manually set the device timeout duration.
getDeviceTimeout	Manually get the device timeout duration.
retrieveQueuedTrans	Returns a list of PaymentEngineResultQueue objects
runQueuedTrans	Run a single or all queued offline transactions.
removeQueuedTrans	Remove a single or all queued offline transactions.
updateQueuedTrans	Updates an existing queued transaction.
registerDevice	Registering a new cloud device.
deleteCloudDevice	Delete a specific cloud device.
updateCloudDevice	Update a specific cloud device.
getCloudDeviceList	Get a list of cloud devices.
getCloudDeviceStatus	Get the status of the current connected devices.
getCloudPaymentStatus	Get the status of the current cloud payment transaction.
cancelCloudPaymentTransaction	Cancel current cloud transaction.

PaymentEngineAPICom Class	This is the main class that contains all the interfaces to communicate with the API.
captureSignature	Captures a customer's signature for an existing transaction. %signatureDict% stores all the required info to capture the signature.
startTransaction	Starts a payment request.

PaymentEngineMiddlewareSettings Class	This is the setting class, it's required at device initialization to set the transaction flow.
currentMode	Set which gateway environment to connect to, options are: Production(this is the default mode) or Sandbox.
isEMVEnable	Disable/enable EMV transactions.
isMSREnable	Disable/enable MSR transactions.
isContactlessEnable	Disable/enable Contactless transactions.
isTipEnable	Disable/enable tips on the Payment device (Not supported by MP200).
isManuallyKeyEnable	Disable/enable manually key on the Payment device
isTipAdjustEnable	Setting it to true will use our tip-adjust config.
isCashbackEnable	Disable/enable cashback on the device.
isDebitEnable	Disable/enable debit selection on the device.
enableDebugLog	Show/hide debugging logs.
sourceKey	Gateway source key (API Key).
pinNum	Set the PIN associated with the source key.

PaymentEngineMiddlewareSettings Class Merchant Capability	This is the setting class, these values gets returned from the gateway base on Merchant's Capability.
isEMVSupported	True if merchant supports EMV, false otherwise.
isTipAdjustSupported	True if merchant supports Tip-Adjust, false otherwise.
isDebitMSRSupported	True if merchant supports Debit MSR, false otherwise.
isContactlessSupported	True if merchant supports Contactless, false otherwise.
isQuickChipSupported	True if merchant supports Quickchip, false otherwise.

PaymentEngineReceiptInfo Class	Use this class to parse receipt info (Not supported by MP200).
invoiceNum	Use to display the invoice number on the receipt.
transResult	Status of the transaction. The possible values are: Approved, Partially Approved, Declined, Verification and Error.
refNum	Transaction reference number.
transError	Error description if UMstatus is Declined or Error.
authCode	Authorization number.
transAID	The application identifier.
transAIDName	Application's preferred name.
transCounter	Transaction counter number.
appCryptogram	Cryptogram returned by the ICC in response to the GENERATE AC command.
terminalSerialNum	The serial number of the terminal device.
maskedCardNum	The masked card number.
cardHolderName	The card holder name that appears on the card.
amount	Amount authorized. May be less than amount requested if UMenablePartialAuth=yes.
tipAmount	The tip amount.
taxAMount	The tax amount.
command	The command used to run the transaction.
transResponseCode	The value from tag 8A.
transDataSource	The transaction type such as contact, contactless or swipe
cvmResults	The CVM (card verification method) result of the transaction.
cardType	The card type that is used for the transaction (i.e. Amex, MasterCard, Visa, or Discover).
declinedArrayTags	Holds all the tags for declined transaction, if transaction is approved the array will be empty.

PaymentEngineTransactionResponse Class	Use this class to parse transaction response from our gateway
RefNum	Transaction reference number.
BatchRefNum	A unique batch reference number assigned by the gateway.
BatchNum	Batch sequence number.
Result	Result of the transaction. The possible values are: Approved, Partially Approved, Declined, Verification and Error.
ResultCode	Single character result code (A, D, or E).
AuthCode	Authorization number.
AvsResultCode	AVS Result Code (1-3 characters).
AvsResult	AVS result in readable format.
RemainBalance	Returns the balance remaining on some prepaid and stored value cards.
CardCodeResultCode	Card Code (CVV2) Verification Result Code (1 character).
CardCodeResult	The transaction type such as contact, contactless or swipe (only available in iCMP).
ErrorCode	Error Code (if transaction resulted in error). Click here to see a list of error codes.
Error	Text description of error code.
CustNum	System assigned customer number of stored customer record if one was used or created.
AcsUrl	ACS Url for Verified by Visa or Mastercard Secure Code.
Payload	Payload for Verified by Visa or Mastercard Secure Code.
VpasResultCode	Vpas Result Code.
isDuplicate	If true, a duplicate transaction was detected, folded, and the response data returned is from original transaction.
ConvertedAmount	Transaction amount converted to new currency.
ConvertedAmountCurrency	Currency code for new currency.
ConversionRate	Rate used to convert transaction amount.
Status	Status of the transaction. Possible values include: Declined, Error, Voided, Pending, Settled.
StatusCode	Single character code for transaction status.
authAmount	Amount that was authorized. Could be less than the amount requested if AllowPartialAuth was set to true.
cashbackAmount	Cashback amount that is requested by the customer.
iccData	The icc tag data returned from the gateway. The following are possible tags than can be returned: 8a, 91, 71, 72, 89.
isSignatureRequire	Use to determine if a signature is required or not.
receiptInfo	Returns EMV receipt info (not supported by MP 200).
procRefNum	Transaction reference number provided by backend processor (platform), blank if not available.
maskedCardNum	The masked card number
cardHolderName	The card holder name that appears on the card.
cardType	The card type such as (Master Card, American Express, Visa, Discover, JCB, Diners).
expirationDate	The expiration date of the card (MM/YY).
trackData	The track data value for giftcard
cvmResult	The CVM (card verification method) result of the transaction.
transactionType	The transaction type such as NFC, Swipe, Insert, fallback, or Manually
identifier	Returns offline transaction identifier. Empty if transaction is online
isOffline	Return true if transaction is offline, false otherwise
initWithXML	The returned xml string that we want to parse.

PaymentEngineResultQueue Class	Use this class to parse offline queued transaction response.
identifier	MD5 identifier for queued transaction
totalAmount	Total transaction amount includes tip, tax and discount
cardNum	Masked card number
dateTime	Date and time of the queued transaction
cardType	The card type of the card that is used (Visa, Master, Discover, Amex and etc.)
cardHolder	The card holder's full name if available

PaymentEngineAccessoryObject Class	Use this class to parse connected bluetooth devices.
deviceName	The name of the connected bluetooth device
serialNum	The serial number of connected bluetooth device
modelNum	The model number of connected bluetooth device
hardwareRevision	The hardware revision of connected bluetooth device
manufacturer	The manufacturer of connected bluetooth device

PaymentEngineCloudDeviceList Class	Use this class to parse cloud device info.
type	device
key	Device key
apikeyid	The id of API key (source key) associated with the device
terminal_type	Terminal type: "standalone"/"Direct" for payment engine cloud based terminal
status	Current device status
name	Developer assigned device name. Device name can contain letters, numbers, spaces, and dashes. All other characters will be filtered out
pairingCode	The code used to pair the cloud device.
deviceSetting	These settings change the behavior of the device
deviceTerminalInfo	Details of terminal
deviceTerminalConfig	The current terminal configuration of the device
deviceCapabilities	If terminal type is 'standalone', this is the pairing code required to pair the payment device with the payment engine.

PaymentEngineDeviceCapabilities Class	Use this class to parse cloud device terminal capability.
emv	Is emv enable
swipe	Is swipe enable
contactless	Is contactless enable
signature_capture	Is signature capture enable
notify_update	Notify the device to update
pin	Is pin enable
sleep_battery	Is sleep battery enable
sleep_powered	Is sleep power enable
standalone	Is standalone enable

PaymentEngineTerminalConfig Class	Use this class to parse cloud device terminal confg./
enable_emv	Enable emv
enable_debit_msr	Enables PIN debit for swiped transactions.
tip_adjust	Allows EMV transaction amounts to be adjusted after authorization (to add tip). Disables PIN authentication.
enable_contactless	Enable contactless

PaymentEngineDeviceSettings Class	The current cloud device settings
timeOut	Transaction timeout, how long to wait for transaction authorization to complete.
share_device	If set to true, this allows a device to be used by other merchants. If false, only the merchant associated with the apikeyid may send transactions to device.
notify_update	If true, device will be notified on all future updates
notify_update_next	If true, device will be notified only on the next update. After notification, this is automatically set back to false.
enable_standalone	Allows transactions to be initiated from terminal (if supported).
sleep_battery_device	This is the amount of inactive time (in minutes) before the device enters full sleep if it is running on battery. If in full sleep, you will need to turn the device on again before processing. Wifi and Bluetooth pairing should persist, even after full sleep. Set to '0' to never sleep.
sleep_battery_display	This is the amount of inactive time (in minutes) before the device enters display sleep if it is running on battery. If in display sleep, just send a transaction to the device or tap any button to wake the device. Set to '0' to never sleep.
sleep_powered_device	This is the amount of inactive time (in minutes) before the device enters full sleep if it is plugged into power. If in full sleep, you will need to turn the device on again before processing. Wifi and Bluetooth pairing should persist, even after full sleep. Set to '0' to never sleep.
sleep_powered_display	This is the amount of inactive time (in minutes) before the device enters display sleep if it is plugged into power. If in display sleep, just send a transaction to the device or tap any button to wake the device. Set to '0' to never sleep.

PaymentEngineTerminalInfo Class	Retrieve the terminal info
make	Manufacturer
model	Device model
revision	Hardware version number
serial	Device serial number
key_pin	Device PIN encryption key. Only necessary if merchant will be processing transactions with a PIN.
key_pan	Device PAN encryption key.

PaymentEngineMiddlewareDelegate	Implement these delegate methods to receive callbacks from the middleware library.
transactionComplete :(PaymentEngineTransactionResponse *)transResponse	This is a call back for startTransaction method.
deviceConnected	Called when the connection to the device is established.
deviceDisconnected	Called when the connection to the device has dropped.
returnReceiptCompleted	Called when receipt is returned from the gateway. Callback for getReceipt method.
getV3ReceiptCompleted	Called when receipt is returned from the gateway. Callback for getV3Receipt method.
startUpdatingTerminal	Called when device starts to update terminal configs.
updateTerminalConfigComplete	Called when device finished updating all the terminal configs.
captureSignatureComplete	Called when capturing signature is completed. Callback for captureSignature method.
adjustTranstionComplete	Called when adjust transaction is completed. Callback for adjustTransaction method.
printCompleted	Called when printText is completed. Callback for printText method.
getMerchantCapabilitiesComplete	Called when merchant capability is returned from the gateway. Callback for getMerchantCapabilities method.
readDeviceInfoComplete	Called when we got information about the device. Callback for readDeviceInfo method.
getDeviceTimeoutCompleted	Called when got device's timeout duration. Callback for getDeviceTimeout method.
runQueuedTransCompleted	Called when run offline transaction is completed. Callback for runQueuedTrans method.
removeQueuedTransCompleted	Called when remove offline transaction is completed. Callback for removeQueuedTrans method.
updateQueuedTransCompleted	Called when update offline transaction is completed. Callback for updateQueuedTrans method.
registerDeviceCompleted	Called when when registering a cloud device is completed. Callback for registerDevice method.

PaymentEngineAPIDelegate	Implement these delegate methods to receive callbacks from PaymentEngineAPICom.
transactionComplete :(PaymentEngineTransactionResponse *)transResponse	This is a call back for startTransaction method.
captureSignatureComplete	Called when capturing signature is completed. Callback for captureSignature method.

iOS Change Log

v2.3.18 - 2020-10-07

• Added in Cloud API support
• Updated demo to include Cloud API examples
• Updated demo to swift 5.0

v2.3.17 - 2019-06-27

• Added in the ability to automatically cancel transaction if user kills app and MP200 is stuck in processing state when app is relaunch
• Updated deprecated methods
• Added in more error handling methods
• Updated demo to swift 4.0

v2.3.16 - 2019-02-27

• Added in the ability get a list of connected bluetooth devices
• Added in the ability to connect to a specific connected MP200/V3 device
• Added in new class PaymentEngineAccessoryObject to parse connected device info
• Added in the ability to print text using Vega 3 with printer support
• Added in the ability to obtain EMV Vega 3 receipt
• Added in more examples to demo app (Objective-c / Swift)

v2.3.15 - 2018-11-28

• Added in the ability to update queued transaction
• Added in identifier field in PaymentEngineTransactionResponse
• Added in more examples to demo app (Objective-c / Swift)

v2.3.14 - 2018-10-02

• Added in Store Forwarding
• Added in examples for store forwarding

v2.3.13 - 2018-08-27

• Added in examples on how to use PaymentEngineAPICom

v2.3.12 - 2018-07-25

• Added in setDeviceTimeout and getDeviceTimeout
• Added in new class PaymentEngineAPICom to communicate with our API

v2.3.11 - 2018-05-30

• Fixed cardholder name issue coming back as Null

v2.3.10 - 2018-05-17

• Added in the ability to Manually display image
• Added in the ability to scan barcode and print text with V3

v2.3.9 - 2018-04-13

• Added in new library to support tip adjust
• Modified both objective-c and swift demo app demonstrating the new startTransactionMethod and adjustTransaction method.

v2.3.8 - 2018-03-08

• Added in fixes for display image when voiding transaction

v2.3.7 - 2018-12-20

• Added in bitcode support that is required by xcode 9.0

v2.3.6 - 2017-07-07

• Returning fallback as one of the transactionType
• Added in more examples to demo apps

v2.3.5 - 2017-06-08

• Added in more examples to demo apps
• Enhanced the method on getting device info
• Added in more info returned from PaymentEngineTransactionResponse class

v2.3.4 - 2017-05-11

• Added in more examples to demo apps
• Added in manual key support
• Added in Debit Boolean value to enable/disable debit selection

v2.3.3 - 2017-04-10

• Added in more examples to demo apps
• Fixed Bridging issue for Swift
• Allow developer to disable/enable cash back

v2.3.2 - 2017-03-23

• Added in Swift demo app

v2.3.1 - 2017-01-23

• Support for First Data Nashville and Tsys processing platforms

iOS Quick Start Guide

Sourcekey and Pin - (Objective C)

    //For production processing comment this line out
    middlewareSettings.currentMode = @"sandbox";

    // Place your sourcekey and pin here before doing any transaction
    middlewareSettings.sourceKey = @"Your Source Key";
    middlewareSettings.pinNum = @"Your Pin";

To use the middleware you will need a Castles MP-200 device loaded with the payment engine software. See the MP200 Setup Guide.

The easiest way to get started with the middleware SDK is to download and build the demo application:

• Pair your Castles MP200 Terminal.
• Make sure you have the latest Xcode downloaded from Apple, a supported iOS device, and a Castles MP200 loaded with the latest terminal software.
• Download the latest demo application.
• Extract the zip and open the enclosed project "Demo App/PaymentEngineDemo".
• Make sure you add Apple's "ExternalAccessory.framework" into the project.
• Add the following to .plist file to be able to connect to the Castles MP200.
• Be sure to set the source key (apikey) and PIN. If you do not already have them, you can set a new api key up in your merchant console. For assistance contact integration support.

You are now ready to build and run the iOS demo app on your device.

iOS SDK Usage Overview

Set Up

Select your project under "Targets", then go to "Build Settings", and type "linker" in the search. Then go to "Other Linker Flags", and type in "-ObjC". This will include all the files in the library.

For iOS 11.0+, add the below requirement to your Info.plist

Instantiation

Instantiation - (Objective C)

//.h File

#import "PaymentEngineMiddlewareSettings.h"
#import "PaymentEngineMiddleware.h"

PaymentEngineMiddlewareSettings *middlewareSettings;
PaymentEngineMiddleware *middleware;

//.m File

#import "PaymentEngineTransactionResponse.h" // Needed for transactionComplete delegate method

middlewareSettings = [PaymentEngineMiddlewareSettings sharedManager];

middlewareSetting.currentMode = @"Production";
middlewareSetting.sourceKey = @"Your Source Key";
middlewareSetting.pinNum = @"Your Pin";

//The below setting values are optional, by default they are set to false
middlewareSetting.isTipEnable = true;
middlewareSetting.enableDebugLog = true;
middlewareSetting.allowEMVTransaction = true;

//---------------------End---------------------

/**
  * If the  MP200 is already paired to the ipad/iphone
  * This will automatically connects the app to the MP200
  */
middleware  = [PaymentEngineMiddleware getInstance];
[middleware setDevice:@"castle" :self];

Delegate methods - (Objective C)

/**
 * The below two callback methods get call base on the connectivity status of the MP200
 */
-(void)deviceConnected;
-(void)deviceDisconnected;

The first step is to instantiate PaymentEngineMiddlewareSettings and PaymentEngineMiddleware classes:

• PaymentEngineMiddlewareSettings - This class is where you setup all the settings that the library support such as, enable/disable EMV, enable/disable Tip, source key, etc. Please visit PaymentEngineMiddlewareSettings for more info.
  • setMode - Options are Sandbox and Production. Use "sandbox", for testing and development. Once the app is ready for production, change mode back to "production". The value is not case sensitive.
  • sourceKey and pinNum - Merchants can login to our console to grab those values.
• PaymentEngineMiddleware - This class contains all the methods to communicate with the castle device. Please visit PaymentEngineMiddleware for more info.
  • middleware setDevice - First parameter sets the name of the device the middleware will connect to, and the second parameter sets the middleware to self, allowing the current class to use the callback method from PaymentEngineMiddleware.

Starting a Transaction

Starting a Transaction - (Objective C)

   //Creates an empty dictionary objects to hold all the transaction info
    NSMutableDictionary *transDict = [NSMutableDictionary new];

/**
  * Sets the basic info that is needed to start a transaction
  */
   [transDict setObject:@"cc:sale" forKey:@"command"];
   [transDict setObject:@"40.00" forKey:@"amount"];
   [transDict setObject:@"10000" forKey:@"invoice"];
   [transDict setObject:@"This is my first middleware transaction" forKey:@"description"];

   //Use the startTransaction method from the PaymentEngineMiddleware class to start the transaction.
    [middleware startTransaction:transDict];

Once a connection is established between the iPhone/iPad and the payment device, the next step is to start the transaction.

After a Transaction Completes

After a Transaction Completes - (Objective C)

-(void)transactionComplete :(PaymentEngineTransactionResponse *)transResponse
{
        NSLog(@"Transaction Result: %@", transResponse.Result);
        NSLog(@"Transaction Status: %@", transResponse.Status);
        NSLog(@"Transaction Error: %@", transResponse.Error);
}

After a transaction finishes, the delegate method transactionComplete will be called.

Tip Support

If merchants wish to support tip amounts, there are several options available:

Prompt for tip in app

• The developer will prompt for tip in the UI of their application
• startTransaction is called with the tip field present in the transDict ( NSMutableDictionary ).
• Amount field should include the tip amount in the total.
• Works with all card types, regardless of supported CVMs.
• Will work regardless of the terminal config.

Prompt for tip on terminal

• promptTip parameter in PaymentEngineMiddlewareSettings should be set to be true.
• Terminal will prompt customer to enter tip amount.
• Tip amount is added onto the original amount and passed in the transDict ( NSMutableDictionary) for the total auth amount.
• Works with all card types, regardless of supported CVMs.
• Will not work with the Tip Adjust terminal config. Use the All CVM base config and make sure to enable_tip_adjust is set to false.

Adjust tip post authorization

• startTransaction is called with amount field NOT including tip amount.
• After authorization, tip is typically entered on paper receipt in conjunction with signature.
• startTransaction is called again with the amount field set to new total (which now includes the tip amount), the tip field set to the tip amount and the refNum field set to the transaction refnum received during the original authorization.
• PIN CVM must be disabled and will NOT work with cards that require PIN CVM.
• Terminal must be configured for Tip Adjust using setTerminalConfig method Use setTerminalConfig(TerminalConfig.getTipAdjustConfig());

Software Updates

The developer will need to maintain a current version of the payment engine SDK. In addition to checking the version of software on the terminal, the SDK also cross checks against the version of the SDK library. If a developer allows the SDK to get too far out of date, it may not be able to support newer devices due to version incompatibility.

Pairing Device - iOS

1. On the MP200 device press and hold the Bluetooth button until the device requests PIN
2. Go to iPhone/iPad Settings-->Bluetooth-->Enable Bluetooth-->Select the MP200 device
3. If you have multiple MP200 devices, find the last 4 digits of the S/N (serial number) on the back of the MP200. See below.
4. In our case, we would select MP200-1793 from the iPhone/iPad.
5. Once the device connects to the MP200, a PIN will pop up on the mobile device screen. See below.
6. Enter the pin into the MP200.
7. Wait until the MP200 displays a green check mark and "OK." On your phone/tablet you should see the MP200 is "Connected," as shown below. Note: If the Castles MP200 device is to be used with multiple phones/tablets then the MP200 device must be unpaired from any unused mobile devices.

Adjusting a Transaction

Adjusting a Transaction - (Objective C)

-(void)adjustTransaction :(NSString *)adjustAmntInput
{
     double adjustAmntValue = [adjustAmntInput double];

     NSMutableDictionary *transDict = [NSMutableDictionary new];
     [transDict setObject:@"cc:adjust" forKey:@"command"];
     [transDict setObject:@"Put transaction refNum here" forKey:@"refnum"];
     [transDict setObject:adjustAmntInput forKey:@"tip"];

      double totalTransAmount = [[transInfoDict objectForKey:@"amount" ] doubleValue];
      totalTransAmount +=  adjustAmntValue;

     NSString *totalTransAmntString = [NSString stringWithFormat:@"%@", totalTransAmount];

     [transDict setObject: totalTransAmntString forKey:@"amount"];

     [middleware startTransaction:transDict];
}

Voiding a Transaction

The following example demonstrates voiding a transaction and releasing the held funds back to the cardholder. The refNum is the value received during the original authorization.

Voiding a Transaction - (Objective C)

-(void)voidTransaction
{
     NSMutableDictionary *transDict = [NSMutableDictionary new];
     [transDict setObject:@"cc:void" forKey:@"command"];
     [transDict setObject:@"Put transaction refNum here" forKey:@"refnum"];

     [middleware startTransaction:transDict];
}

The following example can be used to add a tip to a transaction. Please note that this will only work on an EMV transaction if the Terminal Config has been set to tipadjust. RefNum is the value received during the original authorization.

Class

PaymentEngineMiddleware

• setDevice setDelegate - Set which device to connect to (iCMP or MP200).
• connectBluetoothDevice - Manually connect to selected bluetooth device.
  
• getConnectedDevices - Retrieve a list of connected bluetooth devices.
• isDeviceOnline - Returns true if device is connected, false otherwise.
• disconnectDevice - Disconnects from device.
• connectDevice - Establishes connection to device.
• getDeviceInfo - Retrieves details about the device (Deprecated in v2.3.5).
• readDeviceInfo - Sends a command to the device to retrieve device information.
  
• cancelTransaction - Manually cancels the transaction.
• printText - Manually prints text from V3
  
• startTransaction - Starts a payment request.
  
• captureSignature - Captures a customer's signature for an existing transaction. holdCaptureInfo stores all the required info to capture the signature.
• adjustTransaction - Adjust an existing transaction. holdTransInfo stores all the required info to adjust a transaction.
  
• getReceipt - Makes API Call to get receipt from EMV Template.
• getV3Receipt - Makes API Call to get V3 receipt from EMV Template.
• goOnline - Takes the device to an online status (Not supported by MP200).
• goOffline - Take the device to an offline status (Not supported by MP200).
• getMerchantCapabilities - Get the merchant's capability from the gateway.
• displayImg - Manually display image on the castle device.
• setDeviceTimeout - Manually set the device timeout duration.
• getDeviceTimeout - Manually get the device timeout duration.
  
• retrieveQueuedTrans - Returns a list of PaymentEngineResultQueue objects
  
• runQueuedTrans - Run a single or all queued offline transactions.
  
• removeQueuedTrans - Remove a single or all queued offline transactions.
• updateQueuedTrans - Updates an existing queued transaction.
• registerDevice - Call this method to register a new cloud device.
• deleteCloudDevice - Call this method to delete a specific cloud device.
• updateCloudDevice - Call this method to update a specific cloud device.
• getCloudDeviceList - Call this method to get a list of cloud devices.
• getCloudDeviceStatus - Call this method to get the status of the current connect device.
• getCloudPaymentStatus - Call this method to get the status of the current cloud payment transaction.
• cancelCloudPaymentTransaction - Call this method cancel cloud transaction.

setDevice

setDevice - (Objective C)

-(void)setDevice :(NSString *)deviceName :(id)setDelegate

Use this method to connect to a device. This method must be called before starting any transactions.

Parameters

Type	Parameter	Description
NSString	deviceName	Name of device, should be "MP200"
id	setDelegate	Sets delegate to self

Exceptions

• Exception will be thrown if any of the parameters are passed in with a null value.

Example

Example - (Objective C)

PaymentEngineMiddleware * middleware = [PaymentEngineMiddleware getInstance];
[middleware setDevice:@"castle" :self];

connectBluetoothDevice

connectBluetoothDevice - (Objective C)

-(void)connectBluetoothDevice :(NSString *)deviceName

Use this method to connect to a specific device.

Parameters

Type	Parameter	Description
NSString	deviceName	Name of connected bluetooth device, deviceName can be obtain from getConnectedDevices method

Exceptions

• Exception will be thrown if any of the parameters are passed in with a null value.

Example

Example - (Objective C)

-(void)connectBtDeviceEvent
{
    NSMutableArray *connectedDevices = [usaepayMiddlewareClass getConnectedDevices];

    if(connectedDevices > 0)
    {

        PaymentEngineAccessoryObject *accessoryObject = (PaymentEngineAccessoryObject *)[[usaepayMiddlewareClass getConnectedDevices] objectAtIndex:0];

        //Connects to first available bluetooth device
        [usaepayMiddlewareClass connectBluetoothDevice:accessoryObject.deviceName];
    }

}

getConnectedDevices

getConnectedDevices - (Objective C)

-(NSMutableArray *)getConnectedDevice

Returns a list of connected bluetooth devices.

isDeviceOnline

isDeviceOnline - (Objective C)

-(BOOL)isDeviceOnline

This method is used to determine if the device is connected. Returns true if device is connected, false otherwise.

disconnectDevice

disconnectDevice - (Objective C)

-(void)disconnectDevice

Use this method to disconnect iPhone/iPad from the terminal.

connectDevice

connectDevice - (Objective C)

-(void)connectDevice

Use this method to manually reconnect to the device if it is disconnected.

getDeviceInfo

getDeviceInfo - (Objective C)

-(NSDictionary *)getDeviceInfo

(Deprecated in v2.3.5)

This method returns a NSDictionary, which contains a list of info about the device.

Device Info NSDictionary

Key	Example	Description
serialNum	0003130000123456	Serial number of device
vendorID	0005	ID of device manufacturer
productID	MP200	Model of the device
hwVersion	FFFFFFFF	Hardware version
swVersion	16072141	Software version
batteryLevel	d	Current charge of the battery
deviceState		Current device state (should always be blank)
DUKPT	FFFF3D0100	KSN for debit encryption
DUKPT_MAC	FFFFFFFFFFF	MAC for debit encryption
DUKPT_DEFAULT	FF991C0000	KSN for e2e encryption
SRED	FFFF987654	KSN for e2e encryption (SRED)

readDeviceInfo

readDeviceInfo - (Objective C)

-(void)readDeviceInfo

This method sends a command to the device to retrieve a list of device information. A NSDicitonary is returned to readDeviceInfoComplete delegate.

cancelTransaction - iOS

cancelTransaction - (Objective C)

-(void)cancelTransaction

Use this method to cancel a transaction that is still in progress.

printText

printText - (Objective C)

-(void) printText: (NSString *)text

Use this method to start printing text from V3 with printer support.

Parameters

Type	Parameter	Description
NSString	text	The string that we want to print

Delegate Methods

Delegate Methods - (Objective C)

-(void)printCompleted:(NSString *)msg

• The following delegates may be returned:
  • printCompleted() method will be called for all errors. It is called after all printText operations have been completed.

startTransaction - iOS

startTransaction - (Objective C)

-(void)startTransaction :(NSMutableDictionary *)holdTransInfo

Used to start a transaction request. The terminal will prompt the customer to swipe, tap or dip their card depending on the merchant's capabilities. If the prompTip parameter is set to true, the customer will be asked for a tip amount. The customer is then prompted to confirm amount and the transaction is sent to the gateway for processing. When the gateway response is received or an error occurs, the transactionComplete delegate method will get call. If the customer hits the cancel button on the terminal, the transactionComplete delegate method will get call. Developers will need to implement these two methods to properly handle the transaction flow.

Parameters

Type	Parameter	Description
NSMutableDictionary	%holdTransInfo%	NSMutableDictionary that holds information about the transaction. See below.

Exceptions

• MiddlewareException will be thrown if any of the parameters are passed in with a null value.

Supported Commands

cc:sale This command is the default processing command. The 'cc:sale' command runs a standard credit/debit card sale. It will charge the customers credit/debit card for the amount specified. This command requires that the amount field be populated. Once called, the terminal will collect the payment method from the customer and then send the transaction for processing. If the charge is successful, the transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

cc:authonly

This command runs a credit/debit card authorization. This command requires that the amount field be populated. Once called, the terminal will collect the payment method from the customer and then send the transaction for processing. If approved, the funds will be held in the customers account. The funds will remain oh hold until either the transaction is captured and settled, or until the authorization code expires. The length of time before an authorization expires varies from bank to bank, but generally it is recommended that authorizations be captured within 24-48 hours. Merchants should consult their merchant service provider for information specific to their account. If a merchant does not capture the transaction, no funds will be received by the merchant.

cc:capture

This command moves cc:authonly transactions into the batch for settlement. The original Transaction ID (refnum) must be passed in refNum field. Additionally, the amount of originally authorized may be adjusted by passing the amount field. The tolerances for the settle amount vary depending on the type of merchant account and the merchant service provider. The transaction will be placed in the merchants currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

cc:adjust

This command allows you to make changes to an existing (unsettled) sale. The authorization amount can be increased (incremental authorization), decreased (partial reversal), or not changed. Additional data elements such as tax amount and PO number can also be added. The original Transaction ID (refnum) must be passed in refNum field. The tolerances for the settle amount vary depending on the type of Merchant Account and the merchant service provider. The adjust and capture commands function identically except that the adjust command does not place the transaction in the batch.

cc:credit

This command performs an open credit (refund) to a card. It requires the amount field be populated. The terminal will then prompt the customer for the payment method, and then send the transaction to the gateway for processing.

void:release

This command cancels a pending (sale, authonly, or credit) transaction. For credit card transactions, this command removes the transaction from the current batch. There is a limited amount of time that a void may be run. For credit cards, a transaction can no longer be voided once the batch has been closed. The void requires that the original Transaction ID number be passed in the refNum field. The terminal is not used, and the transaction is sent directly to the gateway.

giftcard:relay

This command is for giftcard processing, it will return the raw data from our gateway.

holdTransInfo Fields

The majority of these are optional. The only required fields are amount and command.

Key	Description
command	Processing command, typically "cc:sale" or "cc:authonly", see above.
amount	Total amount to authorize (including tax, shipping, etc). If prompTip parameter is set to "true", this amount will be added to the tip for the total authorization amount.
tax	Tax amount
nontaxable	Transaction is non taxable
tip	If the prompTip parameter is not set, the tip may be passed in this field. The third option is to use the Tip Adjust terminal config which allows for the tip to be added post authorization.
shipping	Shipping amount
duty	Duty charge (Required only for level 3)
discount	The amount of any discounts that were applied.
description	Transaction Description
comments	Internal transaction notes (not included on customer receipt). Optional.
custid	Merchant assigned customer id.
invoice	Invoice number, only first 11 characters are used
orderid	Order identifier. This field can be used to reference the order to which this transaction corresponds. This field can contain up to 64 characters and should be used instead of invoice when orderid is longer that 10 digits.
ponum	Purchase Order number. Only required for corporate purchasing cards.
clerk	Indicates the clerk/person processing transaction, for reporting purposes. (optional)
tranterm	Indiactes the terminal used to process transaction, for reporting purposes. (optional)
resttable	Indicates the restaurant table, for reporting purposes. (optional)
enablePartialAuth	Set to "true" to enable partial authorization.
refNum	Gateway assigned transaction id number. Necessary for commands that modify an existing transaction, such as "cc:adjust" or "void:release".
timeout	Max number of seconds to wait for a response from the gateway. This does not limit how long the customer has to swipe their card.
cashback	The total amount for cashback (optional).
enableOffline	Set to "true" to start offline transaction when there is no internet connectivity (Note: This will check for internet connectivity each time a transaction is processed) (optional).
forceOffline	Set to "true" to force the transaction to process offline without checking internet connectivity (optional).

Address Fields:

Billing Key	Shipping Key	Description
billfname	shipfname	First Name
billlname	shiplname	Last Name
billcompany	shipcompany	Company Name
billstreet	shipstreet	Street Address
billstreet2	shipsreet2	Additional street information (if needed)
billcity	shipcity	City
billstate	shipstate	State
billzip	shipzip	Zip/Postal code
billcountry	shipcountry	Country
billphone	shipphone	Phone Number
email
fax
website

Line Item Details:

Replace * with the line number 1-99999.

Field	Max Length	Description
line*productrefnum	12	(optional) Gateway assigned product RefNum, used for inventory control.
line*sku	32	Product id, code or SKU
line*name	255	Item name or short description
line*description	64k	Long description
line*cost	00000000.00	Cost of item per unit of measure (before tax or discount)
line*qty	00000000.0000	Quantity
line*taxable	1	Y = Taxable, N = Non-taxable
line*taxrate	00.000	Tax rate for line (only required for level 3 processing).
line*taxamount	00000000.00	Amount of tax charge for line (if left blank will be calculated from taxrate)
line*um	12	Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used.
line*commoditycode	12	Commodity code (only required for level 3 processing). See http://www.unspsc.org/ for valid list of codes.
line*discountrate	000.000	Discount percentage for line (only required for level 3 processing).
line*discountamount	00000000.00	Discount amount for line (if left blank will be calculated from discountrate).

captureSignature

captureSignature - (Objective C)

-(void)captureSignature:(NSMutableDictionary *)holdCaptureInfo

Parameters

Type	Parameter	Description
NSMutableDictionary	%holdCaptureInfo%	NSMutableDictionary that holds all the necessary information to capture the signature. See below.

Delegate Methods

Delegate Methods - (Objective C)

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse

• The following delegates may be returned:
  • captureSignatureComplete() method will be called for all errors, declines or approvals. It is called after all captureSignature operations have been completed.

Example

Example - (Objective C)

/**
* Use this method to capture customer signature after transaction is completed
*/
-(void)startCaptureSigEvent
{

UIImage *signatureImg = [UIImage imageNamed:@"signatureImg.png"];
NSData *imgData = UIImageJPEGRepresentation(signatureImg, 0.5f);
NSString *imgBase64 = [imgData base64EncodedStringWithOptions:0];

NSMutableDictionary *transDict = [NSMutableDictionary new];

[transDict setObject:imgBase64 forKey:@"signature"];
[transDict setObject:@"1296965885" forKey:@"refNum"];
[transDict setObject:@"12.01" forKey:@"amount"];
[transDict setObject:@"capture" forKey:@"command"];

[PaymentEngineMiddlewareClass captureSignature:transDict];
}

adjustTransaction

adjustTransaction - (Objective C)

-(void)adjustTransaction:(NSMutableDictionary *)holdTransInfo

Parameters

Type	Parameter	Description
NSMutableDictionary	%holdTransInfo%	NSMutableDictionary that holds all the necessary information to adjust the transaction. See below.

Delegate Methods

Delegate Methods - (Objective C)

-(void)adjustTranstionComplete :(PaymentEngineTransactionResponse *)transResponse

• The following delegates may be returned:
  • adjustTranstionComplete() method will be called for all errors, declines or approvals. It is called after all adjustTransaction operations have been completed.

Example

Example - (Objective C)

/**
* Use this method to capture customer signature after transaction is completed
*/
-(void)adjustTransEvent
{

NSMutableDictionary *transDict = [NSMutableDictionary new];

/*
* Reference number of the the transaction that we want to adjust
* Below is a test reference number
*/
[transDict setObject:@"1919214943" forKey:@"refNum"];

//total amount including tip
[transDict setObject:@"50" forKey:@"amount"];
[transDict setObject:@"10" forKey:@"tip"];
[transDict setObject:@"adjust" forKey:@"command"];

[middleware adjustTransaction:transDict];
}

getReceipt - iOS

getReceipt - (Objective C)

-(void)getReceipt :(NSDictionary *)receiptDict

Retrieve receipt for transaction referenced by refNum. Receipt template is selected using the template parameter. The rendered receipt is returned as a string to the returnReceiptCompleted delegate.

Parameters

Type	Param	Description
NSDictionary	receiptDict	Dictionary of information needed to retrieve the receipt.

Delegate Methods

Delegate Methods - (Objective C)

-(void)returnReceiptCompleted :(NSString *)receiptValue

• receiptValue - An html string value that contains all the receipt information.

Example

Example - (Objective C)

-(void)delegateGetReceiptEvent
{

NSMutableDictionary *receiptDict = [NSMutableDictionary new];

[receiptDict setObject:@"964096669" forKey:@"refnum"];

[middleware getReceipt:receiptDict];
}

//Call back method
-(void)returnReceiptCompleted :(NSString *)receiptValue
{
NSLog(@"Receipt value: %@", receiptValue);

}

getV3Receipt

getV3Receipt - (Objective C)

-(void)getV3Receipt :(NSString *) transKey

Retrieve receipt for transaction referenced by transaction key. V3 Receipt template is selected using the template parameter. The rendered receipt is returned as a string to the getV3ReceiptCompleted delegate.

Parameters

Type	Param	Description
NSString	transKey	Transaction key of the transaction

Delegate Methods

Delegate Methods - (Objective C)

-(void)returnReceiptCompleted :(NSString *)receiptValue

• receiptValue - An html string value that contains all the receipt information.

Example

Example - (Objective C)

-(void)delegateGetReceiptEvent
{

NSMutableDictionary *receiptDict = [NSMutableDictionary new];

[receiptDict setObject:@"964096669" forKey:@"refnum"];

[middleware getReceipt:receiptDict];
}

//Call back method
-(void)returnReceiptCompleted :(NSString *)receiptValue
{
NSLog(@"Receipt value: %@", receiptValue);

}

goOnline

goOnline - (Objective C)

-(void)goOnline

This is only available for the iCMP device. This method will manually make the iCMP device go online.

goOffline

goOffline - (Objective C)

-(void)goOffline

This is only available for the iCMP device. This method will manually make the iCMP device go offline.

getMerchantCapabilities - iOS

getMerchantCapabilities - (Objective C)

-(void)getMerchantCapabilities :(BOOL)autoUpdateConfigs

Parameters

Type	Parameter	Description
BOOL	autoUpdateConfigs	Boolean value that determine if we want to automatically updates the terminal configs in the device

Delegate Methods

Delegate Methods - (Objective C)

-(void)getMerchantCapabilitiesComplete: (NSDictionary *)merchantCapDict

• The following delegates may be returned:
  • getMerchantCapabilitiesComplete delegate method will be called for all errors. It is called after getMerchantCapabilities operations have been completed.

Example

Example - (Objective C)

/**
* Use this method to get the merchant capability from the gateway
*/
-(void)getMerchantCapEvent
{
    /**
    * Setting the value to false so we don't automatically updates the terminal
    */
    [usaepayMiddlewareClass getMerchantCapabilities:false];

}

displayImg

displayImg - (Objective C)

-(void)displayImg :(DisplayImageType )imgType timeOut:(int)second

Parameters

Type	Parameter	Description
enum	imgType	A list of image enum used to determine which image to display on the castle device.
int	timeOut	Sets when the image display times out, the duration is in seconds.

A list of all the enums, this can be found in PaymentEngineMiddlewareSettings Class

enums - (Objective C)

typedef enum
{
    IdleImage = 0,
    ProcessingImage = 1,
    TransApprovedImage = 2,
    TransDeclinedImage = 3,
    TransErrorImage = 4,
    SwipeCardImage = 5

} DisplayImageType;

Example

Example - (Objective C)

/**
* This method will manually display an image on the castle device
*/
-(void)displayImgEvent
{
    /**
    * Display the swipe card image, set the timout to 4 seconds
    */
    [usaepayMiddlewareClass displayImg:SwipeCardImage timeOut:4];

}

setDeviceTimeout

setDeviceTimeout - (Objective C)

-(void)setDeviceTimeout :(int)second

Parameters

Type	Parameter	Description
int	second	Timeout duration in seconds

Example

Example - (Objective C)

/**
* This method will manually display an image on the castle device
*/
-(void)setTimeoutEvent
{
    /**
    * Set the timeout duration to 11 seconds
    */
    [usaepayMiddlewareClass setDeviceTimeout:11];
}

getDeviceTimeout

getDeviceTimeout - (Objective C)

-(void)getDeviceTimeout

Delegate Methods

Delegate Methods - (Objective C)

-(void)getDeviceTimeoutCompleted :(int) seconds

• The following delegates may be returned:
  • getDeviceTimeoutCompleted delegate method will be called after getDeviceTimeout operations have been completed.

Example

Example - (Objective C)

/**
* Use this method to get the device timeout duration in seconds
*/
-(void)getDeviceTimeoutEvent
{
    [usaepayMiddlewareClass getDeviceTimeout];
}

-(void)getDeviceTimeoutCompleted :(int) seconds
{
    NSLog(@"timeout in seconds: %i", seconds);
}

retrieveQueuedTrans

retrieveQueuedTrans - (Objective C)

-(NSMutableArray *)retrieveQueuedTrans

Returns a list of offline queued transactions.

Example

Example - (Objective C)

/**
* Use this method to get all the offline queued transactions
*/
-(void)retrieveOfflineQueueTrans
{
    NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    [dateFormatter setDateFormat:@"yyMMdd"];

    /**
        Make sure there are queued transaction
        If there are queued transaction, retrieve all of them from the list
    */
    if([usaepayMiddlewareClass retrieveQueuedTrans].count > 0)
    {
        for(int i = 0; i < [usaepayMiddlewareClass retrieveQueuedTrans].count; i++)
        {
            PaymentEngineResultQueue *resultQueue = (PaymentEngineResultQueue *)[[usaepayMiddlewareClass retrieveQueuedTrans] objectAtIndex:i];

            NSLog(@"identifier: %@", resultQueue.identifier);
            NSLog(@"request total amount: %f", resultQueue.totalAmount);
            NSLog(@"card num: %@", resultQueue.cardNum);
            NSLog(@"date: %@", [dateFormatter stringFromDate:resultQueue.dateTime]);
        }

    }
}

runQueuedTrans

runQueuedTrans - (Objective C)

 -(void)runQueuedTrans: (NSString *)identifier

Process a single offline queued transaction. If identifier is empty, it will process all offline queued transactions.

Parameters

Type	Parameter	Description
NSString	identifier	A unique identifier for a queued transaction. If identifier is empty, it will process all offline queued transaction

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void)runQueuedTransCompleted :(PaymentEngineTransactionResponse *)transResponse

• The following optional delegates may be called:
  • runQueuedTransCompleted delegate method will be called after runQueuedTrans operations have been completed.

Example

Example - (Objective C)

/**
  * Use this method process offline queued transaction
*/
-(void)runOfflineQueueTrans
{

    /*
        If an identifier is passed in, it will run the queued transaction for that specific identifier
        else it will run all the queued transactions
    */
    [usaepayMiddlewareClass runQueuedTrans:@""];
}

removeQueuedTrans

removeQueuedTrans - (Objective C)

 -(void)removeQueuedTrans: (NSString *)identifier

Remove a single offline queued transaction. If identifier is empty, it will remove all offline queued transactions.

Parameters

Type	Parameter	Description
NSString	identifier	A unique identifier for a queued transaction. If identifier is empty, it will remove all offline queued transaction

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void)removeQueuedTransCompleted :(NSString *)status message:(NSString *)msg

• The following optional delegates may be called:
  • removeQueuedTransCompleted delegate method will be called after removeQueuedTrans operations have been completed.

Example

Example - (Objective C)

/**
  * Use this method process offline queued transaction
*/
-(void)removeOfflineQueueTrans
{

    /*
        If an identifier is passed in, it will remove the queued transaction for that specific identifier
        else it will remove all the queued transactions
    */
    [usaepayMiddlewareClass removeQueuedTrans:@""];
}

updateQueuedTrans

updateQueuedTrans - (Objective C)

-(void)updateQueuedTrans :(NSMutableDictionary *)transInfo :(NSString *)identifier

Update an existing queued transaction

Parameters

Type	Parameter	Description
NSMutableDictionary	transInfo	Contains all the transaction info that needs to be updated. ( tip, billfname, billlname, billphone, or email )
NSString	identifier	A unique identifier for a queued transaction. This is require to locate the queued transaction

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void)updateQueuedTransCompleted:(NSString *)status message:(NSString *)msg

• The following optional delegates may be called:
  • updateQueuedTransCompleted delegate method will be called after updateQueuedTrans operations have been completed.

Example

Example 1 - (Objective C)

-(void)updateQueuedTransEvent
{

    NSMutableDictionary *updateQueuedDict = [[NSMutableDictionary alloc]init];
    [updateQueuedDict setObject:@"8" forKey:@"tip"];
    [updateQueuedDict setObject:@"first name" forKey:@"billfname"];
    [updateQueuedDict setObject:@"last name" forKey:@"billlname"];
    [updateQueuedDict setObject:@"2136528232" forKey:@"billphone"];
    [updateQueuedDict setObject:@"update@usaepay.com" forKey:@"email"];


    if([usaepayMiddlewareClass retrieveQueuedTrans].count > 0)
    {
        PaymentEngineResultQueue *resultQueue = (PaymentEngineResultQueue *)[[usaepayMiddlewareClass retrieveQueuedTrans] objectAtIndex:0];

        NSLog(@"identifier: %@", resultQueue.identifier);
        NSLog(@"request total amount: %f", resultQueue.totalAmount);
        NSLog(@"card num: %@", resultQueue.cardNum);

        [usaepayMiddlewareClass updateQueuedTrans:updateQueuedDict :resultQueue.identifier];

    }
}

Example 2 - (Objective C)

/*
* Use this method to get all the offline queued transactions
*/
-(void)retrieveOfflineQueueTrans
{
    NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    [dateFormatter setDateFormat:@"yyMMdd"];

    /**
        Make sure there are queued transaction
        If there are queued transaction, retrieve all of them from the list
    */
    if([usaepayMiddlewareClass retrieveQueuedTrans].count > 0)
    {
        for(int i = 0; i < [usaepayMiddlewareClass retrieveQueuedTrans].count; i++)
        {
            PaymentEngineResultQueue *resultQueue = (PaymentEngineResultQueue *)[[usaepayMiddlewareClass retrieveQueuedTrans] objectAtIndex:i];

            NSLog(@"identifier: %@", resultQueue.identifier);
            NSLog(@"request total amount: %f", resultQueue.totalAmount);
            NSLog(@"card num: %@", resultQueue.cardNum);
            NSLog(@"date: %@", [dateFormatter stringFromDate:resultQueue.dateTime]);
        }

    }
}

registerDevice

registerDevice - (Objective C)

-(void) registerDevice :(NSString *)deviceName deviceType:(NSString *)type

Registering a new cloud device

Parameters

Type	Parameter	Description
NSString	deviceName	The name of the cloud device to be registered
NSString	type	The type of registered device, currently we support Standalone or Direct

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void) registerDeviceCompleted :(NSString *)status pairCode:(NSString *)code errorMsg:(NSString *)msg

• The following optional delegates may be called:
  • registerDeviceCompleted delegate method will be called after registerDevice operations have been completed.

Example

Example 1 - (Objective C)

-(void)delegateCreateCloudDeviceEvent
{
    [usaepayMiddlewareClass registerDevice:@"PaymentEngine Device" deviceType:@"standalone"];    
}

- (void) registerDeviceCompleted :(NSString *)status errorMsg:(NSString *)msg deviceInfo :(NSDictionary *)infoDict
{
    NSLog(@"register device complete status: %@", status);
    NSLog(@"register device error msg: %@", msg);
    NSLog(@"register device info dict: %@", infoDict);
}

deleteCloudDevice

deleteCloudDevice - (Objective C)

-(void) deleteCloudDevice :(NSString *)deviceKey

Delete a specific cloud device

Parameters

Type	Parameter	Description
NSString	deviceKey	The device key of the the cloud device we want to delete

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void) deleteCloudDeviceCompleted :(NSDictionary *)dict

• The following optional delegates may be called:
  • deleteCloudDeviceCompleted delegate method will be called after deleteCloudDevice operations have been completed.

Example

Example 1 - (Objective C)

-(void)delegateDeleteCloudDeviceEvent
{
    [usaepayMiddlewareClass deleteCloudDevice:@"Your_Cloud_Device_Key"];//The device key of the cloud device to delete
}

-(void) deleteCloudDeviceCompleted :(NSDictionary *)dict
{
    NSLog(@"delete cloud device completed: %@", dict);
}

updateCloudDevice

updateCloudDevice - (Objective C)

-(void) updateCloudDevice :(NSString *)deviceKey deviceName:(NSString *)name terminalConfigDict :(NSDictionary *)configDict settingDict :(NSDictionary *)settingDict

Update a specific cloud device

Parameters

Type	Parameter	Description
NSString	deviceKey	The device key of the the cloud device we want to update
NSString	name	The name of the device, ( Optional: can be nil or empty )
NSString	configDict	The terminal config for the cloud device, ( Optional: can be nil or empty )
NSString	settingDict	The setting for the cloud device, ( Optional: can be nil or empty )

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void) updateCloudDeviceCompleted :(NSDictionary *)dict

• The following optional delegates may be called:
  • updateCloudDeviceCompleted delegate method will be called after updateCloudDevice operations have been completed.

Example

Example 1 - (Objective C)

-(void)delegateUpdateCloudDeviceEvent
{
    NSDictionary *terminalConfigDict = [NSDictionary dictionaryWithObjectsAndKeys:@"0", @"enable_emv", @"0", @"enable_contactless", @"1", @"enable_debit_msr", @"0", @"tip_adjust", nil];

    NSDictionary *deviceSettingDict = [NSDictionary dictionaryWithObjectsAndKeys: @"0", @"share_device", @"0", @"notify_update", @"0", @"enable_standalone", nil];

    [usaepayMiddlewareClass updateCloudDevice:@"Your_Device_Key" deviceName:@"Name_To_Change" terminalConfigDict:terminalConfigDict settingDict:deviceSettingDict];
}

-(void) updateCloudDeviceCompleted :(NSDictionary *)dict
{
    NSLog(@"update cloud device completed: %@", dict);
}

getCloudDeviceList

getCloudDeviceList - (Objective C)

-(void) getCloudDeviceList

Get status a specific cloud device

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void)getCloudDeviceListCompleted :(NSDictionary *)deviceListDict

• The following optional delegates may be called:
  • getCloudDeviceListCompleted delegate method will be called after getCloudDeviceList operations have been completed.

Example

Example 1 - (Objective C)

-(void)delegateGetCloudListEvent
{
  [usaepayMiddlewareClass getCloudDeviceList];
}

-(void)getCloudDeviceListCompleted :(NSDictionary *)deviceListDict
{
    NSLog(@"get cloud device list completed: %@", dict);
}

getCloudDeviceStatus

getCloudDeviceStatus - (Objective C)

-(void) getCloudDeviceStatus :(NSString *)deviceKey

Get status a specific cloud device

Parameters

Type	Parameter	Description
NSString	deviceKey	The device key of the the cloud device we want to get status of

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void) getCloudDeviceStatusCompleted :(NSDictionary *)dict

• The following optional delegates may be called:
  • getCloudDeviceStatusCompleted delegate method will be called after getCloudDeviceStatus operations have been completed.

Example

Example 1 - (Objective C)

-(void)delegateGetCloudStatusEvent
{
  [usaepayMiddlewareClass getCloudDeviceStatus:@"Your_Cloud_Device_Key"];//The device key of the cloud device
}

-(void) getCloudDeviceStatusCompleted :(NSDictionary *)dict
{
    NSLog(@"get cloud status completed: %@", dict);
}

getCloudPaymentStatus

getCloudPaymentStatus - (Objective C)

-(void) getCloudPaymentStatus :(NSString *)requestKey

Get the status of the current cloud payment transaction

Parameters

Type	Parameter	Description
NSString	requestKey	The current transaction request key, obtained from startTransaction

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void) getCloudPaymentStatusCompleted :(NSDictionary *)dict

• The following optional delegates may be called:
  • getCloudPaymentStatusCompleted delegate method will be called after getCloudPaymentStatus operations have been completed.

Example

Example 1 - (Objective C)

-(void)getCloudPaymentStatusEvent
{
  [usaepayMiddlewareClass getCloudPaymentStatus:@"Your_Request_Key"];//The transaction request key
}

-(void) getCloudPaymentStatusCompleted :(NSDictionary *)dict
{
    NSLog(@"get payment status completed: %@", dict);
}

cancelCloudPaymentTransaction

getCloudPaymentStatus - (Objective C)

-(void) cancelCloudPaymentTransaction :(NSString *)requestKey

Cancel the current cloud payment transaction

Parameters

Type	Parameter	Description
NSString	requestKey	The current transaction request key, obtained from startTransaction

Optional Delegate Method

Optional Delegate Method - (Objective C)

-(void) cancelCloudPaymentTransCompleted :(NSDictionary *)dict

• The following optional delegates may be called:
  • cancelCloudPaymentTransCompleted delegate method will be called after cancelCloudPaymentTransaction operations have been completed.

Example

Example 1 - (Objective C)

-(void)cancelCloudTransEvent
{
  [usaepayMiddlewareClass cancelCloudPaymentTransaction:@"Your_Request_Key"];//The transaction request key
}

-(void) cancelCloudPaymentTransCompleted :(NSDictionary *)dict
{
    NSLog(@"get payment status completed: %@", dict);
}

PaymentEngineAPICom

• captureSignature - Captures a customer's signature for an existing transaction. signatureDict stores all the required info to capture the signature.
• startTransaction - Starts a payment request.

captureSignature - APICom

captureSignature - (Objective C)

-(void)captureSignature:(NSMutableDictionary *)signatureDict

Parameters

Type	Parameter	Description
NSMutableDictionary	%signatureDict%	NSMutableDictionary that holds all the necessary information to capture the signature. See below.

Delegate Methods

Delegate Methods - (Objective C)

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse

• The following delegates may be returned:
  • captureSignatureComplete() method will be called for all errors, declines or approvals. It is called after all captureSignature operations have been completed.

Example

Example - (Objective C)

/**
* Use this method to capture customer signature after transaction is completed
*/
-(void)startCaptureSigEvent
{
    PaymentEngineAPICom *apiCom = [PaymentEngineAPICom getInstance];
    apiCom.delegate = self;

    UIImage *signatureImg = [UIImage imageNamed:@"signatureImg.png"];
    NSData *imgData = UIImageJPEGRepresentation(signatureImg, 0.5f);
    NSString *imgBase64 = [imgData base64EncodedStringWithOptions:0];

    NSMutableDictionary *transDict = [NSMutableDictionary new];

    [transDict setObject:imgBase64 forKey:@"signature"];
    [transDict setObject:@"1296965885" forKey:@"refNum"];
    [transDict setObject:@"12.01" forKey:@"amount"];
    [transDict setObject:@"capture" forKey:@"command"];

    [apiCom captureSignature:transDict];
}

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse
{

    NSLog(@"trans resposne: %@", transResponse.Result);
    NSLog(@"trans response status: %@", transResponse.Status);
    NSLog(@"trans response error: %@", transResponse.Error);

}

startTransaction - APICom

startTransaction - (Objective C)

-(void)startTransaction :(NSMutableDictionary *)holdTransInfo

Used to start a transaction request. holdTransInfo parameter holds all the necessary info to process a transaction. When the gateway response is received or an error occurs, the transactionComplete delegate method will get call. Developers will need to implement these two methods to properly handle the transaction flow.

Parameters

Type	Parameter	Description
NSMutableDictionary	%holdTransInfo%	NSMutableDictionary that holds information about the transaction. See below.

Exceptions - APIComException will be thrown if any of the parameters are passed in with a null value.

Supported Commands

cc:sale

This command is the default processing command. The 'cc:sale' command runs a standard credit/debit card sale. It will charge the customers credit/debit card for the amount specified. This command requires that the amount field be populated. Once called, the terminal will collect the payment method from the customer and then send the transaction for processing. If the charge is successful, the transaction will be placed in the merchant's currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

cc:authonly

This command runs a credit/debit card authorization. This command requires that the amount field be populated. Once called, the terminal will collect the payment method from the customer and then send the transaction for processing. If approved, the funds will be held in the customers account. The funds will remain oh hold until either the transaction is captured and settled, or until the authorization code expires. The length of time before an authorization expires varies from bank to bank, but generally it is recommended that authorizations be captured within 24-48 hours. Merchants should consult their merchant service provider for information specific to their account. If a merchant does not capture the transaction, no funds will be received by the merchant.

cc:capture

This command moves 'cc:authonly' transactions into the batch for settlement. The original Transaction ID (refnum) must be passed in refNum field. Additionally, the amount of originally authorized may be adjusted by passing the amount field. The tolerances for the settle amount vary depending on the type of merchant account and the merchant service provider. The transaction will be placed in the merchants currently open batch for settlement. As long as the merchant has their batch set to autoclose, no further action is required to capture these funds.

cc:adjust

This command allows you to make changes to an existing (unsettled) sale. The authorization amount can be increased (incremental authorization), decreased (partial reversal), or not changed. Additional data elements such as tax amount and PO number can also be added. The original Transaction ID (refnum) must be passed in refNum field. The tolerances for the settle amount vary depending on the type of Merchant Account and the merchant service provider. The adjust and capture commands function identically except that the adjust command does not place the transaction in the batch.

cc:credit

This command performs an open credit (refund) to a card. It requires the amount field be populated. The terminal will then prompt the customer for the payment method, and then send the transaction to the gateway for processing.

void:release

This command cancels a pending (sale, authonly, or credit) transaction. For credit card transactions, this command removes the transaction from the current batch. There is a limited amount of time that a void may be run. For credit cards, a transaction can no longer be voided once the batch has been closed. The void requires that the original Transaction ID number be passed in the refNum field. The terminal is not used, and the transaction is sent directly to the gateway.

holdTransInfo Fields

The majority of these are optional. The only required fields are amount and command.

Key	Description
command	Processing command, typically "cc:sale" or "cc:authonly", see above.
amount	Total amount to authorize (including tax, shipping, etc). If promptTip parameter is set to "true", this amount will be added to the tip for the total authorization amount.
tax	Tax amount
nontaxable	Transaction is non taxable
tip	If the promptTip parameter is not set, the tip may be passed in this field. The third option is to use the Tip Adjust terminal config which allows for the tip to be added post authorization.
shipping	Shipping amount
duty	Duty charge (Required only for level 3)
discount	The amount of any discounts that were applied.
description	Transaction Description
comments	Internal transaction notes (not included on customer receipt). Optional.
custid	Merchant assigned customer id.
invoice	Invoice number, only first 11 characters are used
orderid	Order identifier. This field can be used to reference the order to which this transaction corresponds. This field can contain up to 64 characters and should be used instead of invoice when orderid is longer that 10 digits.
ponum	Purchase Order number. Only required for corporate purchasing cards.
clerk	Indicates the clerk/person processing transaction, for reporting purposes. (optional)
tranterm	Indicates the terminal used to process transaction, for reporting purposes. (optional)
resttable	Indicates the restaurant table, for reporting purposes. (optional)
enablePartialAuth	Set to "true" to enable partial authorization.
refnum	Gateway assigned transaction id number. Necessary for commands that modify an existing transaction, such as "cc:adjust" or "void:release".
timeout	Max number of seconds to wait for a response from the gateway. This does not limit how long the customer has to swipe their card.
cashback	The total amount for cashback (optional).

Address Fields:

Billing Key	Shipping Key	Description
billfname	shipfname	First Name
billlname	shiplname	Last Name
billcompany	shipcompany	Company Name
billstreet	shipstreet	Street Address
billstreet2	shipsreet2	Additional street information (if needed)
billcity	shipcity	City
billstate	shipstate	State
billzip	shipzip	Zip/Postal code
billcountry	shipcountry	Country
billphone	shipphone	Phone Number
email
fax
website

Line Item Details:

Replace * with the line number 1-99999.

Field	Max Length	Description
line*productrefnum	12	(optional) Gateway assigned product RefNum, used for inventory control.
line*sku	32	Product id, code or SKU
line*name	255	Item name or short description
line*description	64k	Long description
line*cost	00000000.00	Cost of item per unit of measure (before tax or discount)
line*qty	00000000.0000	Quantity
line*taxable	1	Y = Taxable, N = Non-taxable
line*taxrate	00.000	Tax rate for line (only required for level 3 processing).
line*taxamount	00000000.00	Amount of tax charge for line (if left blank will be calculated from taxrate)
line*um	12	Unit of measure. If left blank or an invalid code is sent, EA (Each) will be used.
line*commoditycode	12	Commodity code (only required for level 3 processing). See http://www.unspsc.org/ for valid list of codes.
line*discountrate	000.000	Discount percentage for line (only required for level 3 processing).
line*discountamount	00000000.00	Discount amount for line (if left blank will be calculated from discountrate).

PaymentEngineCloudDeviceList

type

type - (Objective C)

@property (nonatomic, retain) NSString *type

Device Type.

key

key - (Objective C)

@property (nonatomic, retain) NSString *key

Device key.

apikeyid

apikeyid - (Objective C)

@property (nonatomic, retain) NSString *apikeyid

The id of API key (source key) associated with the device.

terminal_type

terminal_type - (Objective C)

@property (nonatomic, retain) NSString *terminal_type

Terminal type: "standalone"/"Direct" for payment engine cloud based terminal.

status

status - (Objective C)

@property (nonatomic, retain) NSString *status

Current device status

name

name - (Objective C)

@property (nonatomic, retain) NSString *name

Developer assigned device name. Device name can contain letters, numbers, spaces, and dashes. All other characters will be filtered out.

pairingCode

pairingCode - (Objective C)

@property (nonatomic, retain) NSString *pairingCode

The code used to pair the cloud device.

PaymentEngineDeviceSettings

PaymentEngineDeviceSettings - (Objective C)

@property (nonatomic, retain) PaymentEngineDeviceSettings *deviceSetting

These settings change the behavior of the device.

PaymentEngineTerminalInfo

PaymentEngineTerminalInfo - (Objective C)

@property (nonatomic, retain) PaymentEngineTerminalInfo *deviceTerminalInfo

Details of terminal

PaymentEngineTerminalConfig

PaymentEngineTerminalConfig - (Objective C)

@property (nonatomic, retain) PaymentEngineTerminalConfig *deviceTerminalConfig

The current terminal configuration of the device.

PaymentEngineDeviceCapabilities

PaymentEngineDeviceCapabilities - (Objective C)

@property (nonatomic, retain) PaymentEngineDeviceCapabilities *deviceCapabilities

If terminal type is 'standalone', this is the pairing code required to pair the payment device with the payment engine.

PaymentEngineDeviceCapabilities

emv

emv - (Objective C)

@property (nonatomic) BOOL emv

Return true if EMV is enable.

swipe

swipe - (Objective C)

@property (nonatomic) BOOL swipe

Return true if swipe is enable

contactless

contactless - (Objective C)

@property (nonatomic) BOOL contactless

Return true if contactless is enable.

signature_capture

signature_capture - (Objective C)

@property (nonatomic) BOOL signature_capture

Return true if signature capture is enable.

printer

printer - (Objective C)

@property (nonatomic) BOOL printer

Return true if printer is enable.

notify_update

notify_update - (Objective C)

@property (nonatomic) BOOL notify_update

Return true if notify update is enable.

pin

pin - (Objective C)

@property (nonatomic) BOOL pin

Return true if pin is enable.

sleep_battery

sleep_battery - (Objective C)

@property (nonatomic) BOOL sleep_battery

Return true if sleep battery is enable.

sleep_powered

sleep_powered - (Objective C)

@property (nonatomic) BOOL sleep_powered

Return true if sleep power enable.

standalone

standalone - (Objective C)

@property (nonatomic) BOOL standalone

Return true if standalone is enable.

PaymentEngineTerminalConfig

enable_emv

enable_emv - (Objective C)

@property (nonatomic) BOOL enable_emv

Enable emv.

enable_debit_msr

enable_debit_msr - (Objective C)

@property (nonatomic) BOOL enable_debit_msr

Enables PIN debit for swiped transactions.

tip_adjust

tip_adjust - (Objective C)

@property (nonatomic) BOOL tip_adjust

Allows EMV transaction amounts to be adjusted after authorization (to add tip). Disables PIN authentication.

enable_contactless

enable_contactless - (Objective C)

@property (nonatomic) BOOL enable_contactless

Enable contactless.

PaymentEngineTerminalInfo

make

make - (Objective C)

@property (nonatomic, retain) NSString *make

Manufacturer.

model

model - (Objective C)

@property (nonatomic, retain) NSString *model

Device model .

revision

revision - (Objective C)

@property (nonatomic, retain) NSString *revision

Hardware version number.

serial

serial - (Objective C)

@property (nonatomic, retain) NSString *serial

Device serial number.

key_pin

key_pin - (Objective C)

@property (nonatomic, retain) NSString *key_pin

Device PIN encryption key. Only necessary if merchant will be processing transactions with a PIN..

key_pan

key_pan - (Objective C)

@property (nonatomic, retain) NSString *key_pan

Device PAN encryption key.

UsaepayMiddlewareSettings

This class is used to configure the middleware. These settings must be set prior to connecting the device.

currentMode

currentMode - (Objective C)

@property(nonatomic, retain) NSString *currentMode

• (Optional)

Use to set the mode (Production or Sandbox) during device initialization. The default mode is Production.

isEMVEnable

isEMVEnable - (Objective C)

@property(nonatomic) BOOL isEMVEnable

• (Optional)

Use to disable/enable EMV transactions. The merchant account must also be configured for EMV processing. Please contact customer support to verify the merchant account is set up correctly.

isMSREnable

isMSREnable - (Objective C)

@property(nonatomic) BOOL isMSREnable

• (Optional)

Use to disable/enable MSR transactions.

isContactlessEnable

isContactlessEnable - (Objective C)

@property(nonatomic) BOOL isContactlessEnable

• (Optional)

Use to disable/enable Contactless transactions.

isTipEnable

isTipEnable - (Objective C)

@property(nonatomic) BOOL isTipEnable

• (Optional)

Use to disable/enable tips on the device (Not supported by MP200).

isManuallyKeyEnable

isManuallyKeyEnable - (Objective C)

@property(nonatomic) BOOL isManuallyKeyEnable

• (Optional)

Use to disable/enable manually key on the payment device.

isTipAdjustEnable

isTipAdjustEnable - (Objective C)

@property(nonatomic) BOOL isTipAdjustEnable

• (Optional)

Use to disable/enable support for Tip-Adjust on the terminal.

isCashbackEnable

isCashbackEnable - (Objective C)

@property(nonatomic) BOOL isCashbackEnable

• (Optional)

Use to disable/enable Cashback on the terminal.

isDebitEnable

isDebitEnable - (Objective C)

@property(nonatomic) BOOL isDebitEnable

• (Optional)

Use to disable/enable debit selection on the terminal.

enableDebugLog

enableDebugLog - (Objective C)

@property(nonatomic) BOOL enableDebugLog

• (Optional)

Use to show/hide debugging logs.

sourceKey

sourceKey - (Objective C)

@property(nonatomic, retain) NSString *sourceKey

• (Required)

Use to set the source key. This is required at device initialization.

pinNum

pinNum - (Objective C)

@property(nonatomic, retain) NSString *pinNum

• (Required)

Use to set the pin associated with the source key. This is required at device initialization.

UsaepayMiddlewareSettings Merchant Capability

These settings get returned from the gateway base on Merchant's Capability.

isEMVSupported

isEMVSupported - (Objective C)

@property(nonatomic) BOOL isEMVSupported

True if merchant supports EMV, false otherwise

isTipAdjustSupported

isTipAdjustSupported - (Objective C)

@property(nonatomic) BOOL isTipAdjustSupported

True if merchant supports Tip-Adjust, false otherwise

isDebitMSRSupported

isDebitMSRSupproted - (Objective C)

@property(nonatomic) BOOL isDebitMSRSupproted

True if merchant supports Debit MSR, false otherwise

isContactlessSupported

isContactlessSupported - (Objective C)

@property(nonatomic) BOOL isContactlessSupported

True if merchant supports Contactless, false otherwise

isQuickChipSupported

isQuickChipSupported - (Objective C)

@property(nonatomic) BOOL isQuickChipSupported

True if merchant supports Quickchip, false otherwise

PaymentEngineReceiptInfo

• invoiceNum - Use to display the invoice number on the receipt.
• transResult - Status of the transaction. The possible values are: Approved, Partially Approved, Declined, Verification and Error.
• refNum - Transaction reference number.
• transError - Error description if UMstatus is Declined or Error.
• authCode - Authorization number.
• transAID - The application identifier.
• transAIDName - Application's preferred name.
• transCounter - Transaction counter number.
• appCryptogram - Cryptogram returned by the ICC in response to the GENERATE AC command.
• terminalSerialNum - The serial number of the terminal device.
• maskedCardNum - The masked card number.
• cardHolderName - The card holder name that appears on the card.
• amount - Amount authorized. May be less than amount requested if UMenablePartialAuth=yes.
• tipAmount - The tip amount.
• taxAMount - The tax amount.
• command - The command used to run the transaction.
• transResponseCode - The value from tag 8A.
• transDataSource - The transaction type such as contact, contactless or swipe
• cvmResults - The CVM (card verification method) result of the transaction.
• cardType - The card type that is used for the transaction (i.e. Amex, MasterCard, Visa, or Discover).
• declinedArrayTags - Holds all the tags for declined transaction, if transaction is approved the array will be empty.

invoiceNum

invoiceNum - (Objective C)

@property(nonatomic, retain) NSString *invoiceNum

Returns the invoice number of a receipt.

transResult

transResult - (Objective C)

@property(nonatomic, retain) NSString *transResult

The transaction result, possible values are: Approved, Partially Approved, Declined, Verification and Error.

refNum

refNum - (Objective C)

@property(nonatomic, retain) NSString *refNum

The gateway assigned transaction reference number.

transError

transError - (Objective C)

@property(nonatomic, retain) NSString *transError

Error description if UMstatus is Declined or Error.

authCode

authCode - (Objective C)

@property(nonatomic, retain) NSString *authCode

Authorization number.

transAID

transAID - (Objective C)

@property(nonatomic, retain) NSString *transAID

The application identifier.

transAIDName

transAIDName - (Objective C)

@property(nonatomic, retain) NSString *transAIDName

The application preferred name.

transCounter

transCounter - (Objective C)

@property(nonatomic) int transCounter

The transaction counter number.

appCryptogram

appCryptogram - (Objective C)

@property(nonatomic, retain) NSString *appCryptogram

The calculated cryptogram.

terminalSerialNum

terminalSerialNum - (Objective C)

@property(nonatomic, retain) NSString *terminalSerialNum

The serial number of the terminal device.

maskedCardNum

maskedCardNum - (Objective C)

@property(nonatomic, retain) NSString *maskedCardNum

The masked card number.

cardHolderName - ReceiptInfo

cardHolderName - (Objective C)

@property(nonatomic, retain) NSString *cardHolderName

The card holder name that appears on the card.

amount

amount - (Objective C)

@property(nonatomic, retain) NSString *amount

Amount authorized including shipping, tips, and discounts. Could be less than amount requested if UMenablePartialAuth=yes.

tipAmount

tipAmount - (Objective C)

@property(nonatomic, retain) NSString *tipAmount

The tip amount.

taxAMount

taxAMount - (Objective C)

@property(nonatomic, retain) NSString *taxAMount

The tax amount.

command

command - (Objective C)

@property(nonatomic, retain) NSString *command

The command used to run the transaction.

transResponseCode

transResponseCode - (Objective C)

@property(nonatomic, retain) NSString *transResponseCode

The value from tag 8A.

transDataSource

transDataSource - (Objective C)

@property(nonatomic, retain) NSString *transDataSource

The transaction type, such as contact, contactless or swipe.

cvmResults

cvmResults - (Objective C)

@property(nonatomic) ReturnTransactionType cvmResults

The CVM (card verification method) result of the transaction.

cardType - ReceiptInfo

cardType - (Objective C)

@property(nonatomic, retain) NSString *cardType

The card type that is used for the transaction (i.e. Amex, MasterCard, Visa, or Discover).

declinedArrayTags

declinedArrayTags - (Objective C)

@property(nonatomic,retain) NSArray *declinedArrayTags

Holds all the tags for declined transaction. If transaction is approved, the array will be empty.

PaymentEngineTransactionResponse

• RefNum - Transaction reference number.
  
• BatchRefNum - A unique batch reference number assigned by the gateway.
  
• BatchNum - Batch sequence number.
  
• Result - Result of the transaction. The possible values are: Approved, Partially Approved, Declined, Verification and Error.
  
• ResultCode - Single character result code (A, D, or E).
  
• AuthCode - Authorization number.
  
• AvsResultCode - AVS Result Code (1-3 characters).
  
• AvsResult - AVS result in readable format.
  
• RemainBalance - Returns the balance remaining on some prepaid and stored value cards.
  
• CardCodeResultCode - Card Code (CVV2) Verification Result Code (1 character).
  
• CardCodeResult - The transaction type such as contact, contactless or swipe (only available in iCMP).
  
• ErrorCode - Error Code (if transaction resulted in error). Click here to see a list of error codes.
• Error - Text description of error code.
  
• CustNum - System assigned customer number of stored customer record if one was used or created.
  
• AcsUrl - ACS Url for Verified by Visa or Mastercard Secure Code.
  
• Payload - Payload for Verified by Visa or Mastercard Secure Code.
  
• VpasResultCode - Vpas Result Code.
  
• isDuplicate - If true, a duplicate transaction was detected, folded, and the response data returned is from original transaction.
  
• ConvertedAmount - Transaction amount converted to new currency.
  
• ConvertedAmountCurrency - Currency code for new currency.
  
• ConversionRate - Rate used to convert transaction amount.
  
• Status - Status of the transaction. Possible values include: Declined, Error, Voided, Pending, Settled.
  
• StatusCode - Single character code for transaction status.
  
• authAmount - Amount that was authorized. Could be less than the amount requested if AllowPartialAuth was set to true.
  
• cashbackAmount - Cashback amount that is requested by the customer.
  
• iccData - The icc tag data returned from the gateway. The following are possible tags than can be returned: 8a, 91, 71, 72, 89.
  
• isSignatureRequire - Use to determine if a signature is required or not.
  
• receiptInfo - Returns EMV receipt info (not supported by MP 200).
  
• procRefNum - Transaction reference number provided by backend processor (platform), blank if not available.
  
• maskedCardNum - The masked card number
  
• cardHolderName - The card holder name that appears on the card.
  
• cardType - The card type such as (Master Card, American Express, Visa, Discover, JCB, Diners).
  
• expirationDate - The expiration date of the card (MM/YY).
  
• trackData - The track data value for giftcard
  
• cvmResult - The CVM (card verification method) result of the transaction.
  
• transactionType - The transaction type such as NFC, Swipe, Insert, fallback, or Manually
  
• identifier - Returns offline transaction identifier. Empty if transaction is online
  
• isOffline - Return true if transaction is offline, false otherwise
  
• initWithXML - The returned xml string that we want to parse.
  

RefNum

RefNum - (Objective C)

@property (nonatomic, readwrite) NSString *RefNum

Returns gateway assigned transaction reference number.

BatchRefNum

BatchRefNum - (Objective C)

@property (readwrite, nonatomic) int BatchRefNum

Returns a unique batch reference number assigned by the gateway.

BatchNum

BatchNum - (Objective C)

@property (readwrite, nonatomic) int BatchNum

Returns batch sequence number.

Result

Result - (Objective C)

@property (nonatomic, retain) NSString *Result

Returns the result of the transaction. Possible values are: Approved, Partially Approved, Declined, Verification and Error.

ResultCode

ResultCode - (Objective C)

@property (nonatomic, retain) NSString *ResultCode

Returns single character result code (A, D, or E).

AuthCode

AuthCode - (Objective C)

@property (nonatomic, retain) NSString *AuthCode

Returns authorization number.

AvsResultCode

AvsResultCode - (Objective C)

@property (nonatomic, retain) NSString *AvsResultCode

Returns AVS Result Code (1-3 characters).

AvsResult

AvsResult - (Objective C)

@property (nonatomic, retain) NSString *AvsResult

Returns a text description of AVS Result.

RemainBalance

RemainBalance - (Objective C)

@property (nonatomic, retain) NSString *RemainBalance

Returns the balance remaining on some prepaid and stored value cards.

CardCodeResultCode

CardCodeResultCode - (Objective C)

@property (nonatomic, retain) NSString *CardCodeResultCode

Returns Card Code (CVV2) Verification Result Code (1 character).

CardCodeResult

CardCodeResult - (Objective C)

@property (nonatomic, retain) NSString *CardCodeResult

Returns a text description of Card Code Result.

ErrorCode

ErrorCode - (Objective C)

@property (nonatomic, retain) NSString *ErrorCode

Returns Error Code (if the transaction resulted in error).

Error

Error - (Objective C)

@property (nonatomic, retain) NSString *Error

Returns text description of Error Code (if the transaction resulted in error).

CustNum

CustNum - (Objective C)

@property (readwrite, nonatomic) int CustNum

Returns the system assigned customer number. Only applies to customers that have customer records created in the customer database.

AcsUrl

AcsUrl - (Objective C)

@property (nonatomic, retain) NSString *AcsUrl

Returns ACS Url for Verified by Visa or Mastercard Secure Code.

Payload

Payload - (Objective C)

@property (nonatomic, retain) NSString *Payload

Returns Payload for Verified by Visa or Mastercard Secure Code.

VpasResultCode

VpasResultCode - (Objective C)

@property (nonatomic, retain) NSString *VpasResultCode

Returns Vpas Result Code.

isDuplicate

isDuplicate - (Objective C)

@property (readwrite, nonatomic) BOOL isDuplicate

Returns a boolean value that is used to determine if the transaction is duplicated.

ConvertedAmount

ConvertedAmount - (Objective C)

@property (readwrite, retain) PaymentEngineCurrencyAmount *ConvertedAmount

Returns transaction amount converted to new currency.

ConvertedAmountCurrency

ConvertedAmountCurrency - (Objective C)

@property (nonatomic, retain) NSString *ConvertedAmountCurrency

Returns the currency code for new currency.

ConversionRate

ConversionRate - (Objective C)

@property (readwrite, retain) UsaepayCurrencyAmount *ConversionRate

Returns the rate used to convert transaction amount.

Status

Status - (Objective C)

@property (nonatomic, retain) NSString *Status

Returns status of the transaction. Possible values include: Declined, Error, Voided, Pending, Settled.

StatusCode

StatusCode - (Objective C)

@property (nonatomic, retain) NSString *StatusCode

Returns single character code for transaction status.

authAmount

authAmount - (Objective C)

@property (readwrite, retain) NSString *authAmount

Returns amount that was authorized. Could be less than the original amount requested if AllowPartialAuth was set to true.

cashbackAmount

cashbackAmount - (Objective C)

@property (readwrite, retain) NSString *cashbackAmount

Returns amount that was requested by the customer.

iccData

iccData - (Objective C)

@property (nonatomic, retain) NSString *iccData

Returns the icc tag data returned from the gateway. The following are possible tags than can be returned: 8a, 91, 71, 72, 89.

isSignatureRequire

isSignatureRequire - (Objective C)

@property (nonatomic) BOOL isSignatureRequire

Returns boolean value used to determine if a signature is required or not.

receiptInfo

receiptInfo - (Objective C)

@property (nonatomic, retain) PaymentEngineReceiptInfo *receiptInfo

Returns EMV receipt info (not supported by MP 200).

procRefNum

procRefNum - (Objective C)

@property (nonatomic, retain) NSString *procRefNum

Returns transaction reference number provided by backend processor (platform), blank if not available.

maskedCardNum

maskedCardNum - (Objective C)

@property(nonatomic, retain) NSString *maskedCardNum

Returns the masked card number.

cardHolderName - TransactionResponse

cardHolderName - (Objective C)

@property(nonatomic, retain) NSString *cardHolderName

Returns the card holder name that appears on the card.

cardType - TransactionResponse

cardType - (Objective C)

@property(nonatomic, retain) NSString *cardType

Returns the card type (Master Card, American Express, Visa, Discover, JCB, Diners)

expirationDate

expirationDate - (Objective C)

@property(nonatomic, retain) NSString *expirationDate

Returns the expiration date of the card (MM/YY)

trackData

trackData - (Objective C)

@property(nonatomic, retain) NSString *trackData

Returns the track data value for giftcard

cvmResult

cvmResult - (Objective C)

@property(nonatomic)  ReturnTransactionType cvmResult

Returns the cvm result ( PIN_ONLINE, PIN_OFFLINE_ENCR, PIN_OFFLINE_PLAIN, PIN_OFFLINE_AND_SIGNATURE, SIGNATURE_REQ, FAIL_CVM, NO_CVM_REQ, NO_CVM_AVAIL, PLAIN_AND_SIGNATURE)

transactionType

transactionType - (Objective C)

@property(nonatomic, retain) NSString *transactionType

Returns the transaction type (nfc, swipe, insert, fallback, manually)

identifier - TransactionResponse

identifier - (Objective C)

@property(nonatomic, retain) NSString *identifier

Returns a unique offline transaction identifier. Empty if transaction is online

isOffline

isOffline - (Objective C)

@property(nonatomic) Boolean isOffline

Return true if transaction is offline, false otherwise

initWithXML

initWithXML - (Objective C)

-(id) initWithXML:(NSString *)string

The returned xml string that we want to parse.

PaymentEngineResultQueue

identifier - ResultQueue

identifier - (Objective C)

@property(nonatomic, retain) NSString *identifier

Returns MD5 identifier for queued transaction.

totalAmount

totalAmount - (Objective C)

@property(nonatomic) double totalAmount

Returns queued transaction total amount including tip, tax, and discount.

cardNum

cardNum - (Objective C)

@property(nonatomic, retain) NSString *cardNum

Returns the masked card number.

dateTime

dateTime - (Objective C)

@property(nonatomic, retain) NSDate *dateTime

Returns the date and time of the queued transaction

cardType - ResultQueue

cardType - (Objective C)

@property(nonatomic, retain) NSString *cardType

Returns the card type of the card that is used (Visa, Master, Discover, Amex and etc.)

cardHolder - ResultQueue

cardHolder - (Objective C)

@property(nonatomic, retain) NSString *cardHolder

Returns the full name of the card holder.

PaymentEngineAccessoryObject

deviceName

deviceName - (Objective C)

@property(nonatomic, retain) NSString *deviceName;

Returns the name of the connected bluetooth device.

serialNum

serialNum - (Objective C)

@property(nonatomic, retain) NSString *serialNum

Returns the serial number of connected bluetooth device.

modelNum

modelNum - (Objective C)

@property(nonatomic, retain) NSString *modelNum

Returns the model number of connected bluetooth device.

hardwareRevision

hardwareRevision - (Objective C)

@property(nonatomic, retain) NSString *hardwareRevision

Returns the hardware revision of connected bluetooth device

manufacturer

manufacturer - (Objective C)

@property(nonatomic, retain) NSString *manufacturer

Returns the manufacturer of connected bluetooth device

Delegate

PaymentEngineMiddlewareDelegate

• transactionComplete :(PaymentEngineTransactionResponse *)transResponse - This is a call back for startTransaction method.
• deviceConnected - Called when the connection to the device is established.
• deviceDisconnected - Called when the connection to the device has dropped.
• returnReceiptCompleted - Called when receipt is returned from the gateway. Callback for getReceipt method.
• getV3ReceiptCompleted - Called when receipt is returned from the gateway. Callback for getV3Receipt method.
• startUpdatingTerminal - Called when device starts to update terminal configs.
• updateTerminalConfigComplete - Called when device finished updating all the terminal configs.
• captureSignatureComplete - Called when capturing signature is completed. Callback for captureSignature method.
• adjustTranstionComplete - Called when adjust transaction is completed. Callback for adjustTransaction method.
• printCompleted - Called when printText is completed. Callback for printText method.
• getMerchantCapabilitiesComplete - Called when merchant capability is returned from the gateway. Callback for getMerchantCapabilities method. |
• readDeviceInfoComplete - Called when we got information about the device. Callback for readDeviceInfo method.
• getDeviceTimeoutCompleted - Called when got device's timeout duration. Callback for getDeviceTimeout method.
• runQueuedTransCompleted - Called when run offline transaction is completed. Callback for runQueuedTrans method.
• removeQueuedTransCompleted - Called when remove offline transaction is completed. Callback for removeQueuedTrans method.
• updateQueuedTransCompleted - Called when update offline transaction is completed. Callback for updateQueuedTrans method.
• registerDeviceCompleted - Called once device is finished registering. Callback for registerDevice method.
• deleteCloudDeviceCompleted - Delegate method for deleting cloud device. Callback for deleteCloudDevice method.
• updateCloudDeviceCompleted - Delegate method for updating cloud device. Callback for updateCloudDevice method.
• getCloudDeviceStatusCompleted - Delegate method for getting cloud device status. Callback for getCloudDeviceStatus method.
• getCloudDeviceListCompleted - Delegate method for getting a list of cloud devices. Callback for getCloudDeviceList method.
• getCloudPaymentStatusCompleted - Delegate method for getting current cloud payment status. Callback for getCloudPaymentStatus method.
• cloudTransactionCompleted - Delegate method for current cloud transaction, it will return all the info for current cloud transaction such as request key, which it will be used to cancel a pending transaction. Callback for startTransaction method.
• cancelCloudPaymentTransCompleted - Delegate method for cancel current cloud transaction. Callback for cancelCloudPaymentTransaction method.

transactionComplete - MiddlewareDelegate

transactionComplete - (Objective C)

-(void)transactionComplete :(PaymentEngineTransactionResponse *)transResponse;

This method is called when a transaction has completed processing: it will be called for all errors, declines or approvals. This is a required delegate method. The delegate method needs to be implemented when user starts a transaction using the middleware. See PaymentEngineTransactionResponse for a complete list fields that get returned.

Example: Extracting the RefNum from transactionComplete

Example: Extracting the RefNum from transactionComplete - (Objective C)

-(void)transactionComplete :(PaymentEngineTransactionResponse *)transResponse
{
     NSLog(@"refNum: %@", transResponse.RefNum);
}

The RefNum is needed if you are going to adjust/void the transaction.

captureSignatureComplete -MiddlewareDelegate

captureSignatureComplete - (Objective C)

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse

This delegate method needs to be implemented when the captureSignature method is used to capture a signature. Read PaymentEngineTransactionResponse for a complete list of returned fields.

Example

Example - (Objective C)

-(void)captureSignaureMethod
{
    PaymentEngineMiddleware  *middleware = [PaymentEngineMiddleware getInstance];
    middleware.delegate = self;
    [middleware setDevice:@"castle" :self];

    UIImage *signatureImg = [UIImage imageNamed:@"signatureImg.png"];
    NSData *imgData = UIImageJPEGRepresentation(signatureImg, 0.5f);
    NSString *imgBase64 = [imgData base64EncodedStringWithOptions:0];

    NSMutableDictionary *transDict = [NSMutableDictionary new];

    [transDict setObject:imgBase64 forKey:@"signature"];

    //Reference number of the transaction that we want to capture the signature
    [transDict setObject:@"1296965885" forKey:@"refNum"];

   //The amount of the transaction that we want to capture the signature
    [transDict setObject:@"12.01" forKey:@"amount"];
    [transDict setObject:@"capture" forKey:@"command"];

    [middleware captureSignature:transDict];
}

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse
{
    NSLog(@"signature captured:%@ ", transResponse.Status);
    NSLog(@"signature error reason: %@", transResponse.Error);

}

adjustTranstionComplete

adjustTranstionComplete - (Objective C)

-(void)adjustTranstionComplete :(PaymentEngineTransactionResponse *)transResponse

This delegate method needs to be implemented when the adjustTransaction method is used to adjust a transaction. Read PaymentEngineTransactionResponse for a complete list of returned fields.

Example

Example - (Objective C)

-(void)adjustTransMethod
{
NSMutableDictionary *transDict = [NSMutableDictionary new];

/**
* Reference number of the the transaction that we want to adjust
* Below is a test reference number
*/
[transDict setObject:@"1919214943" forKey:@"refNum"];

//total amount including tip
[transDict setObject:@"50" forKey:@"amount"];
[transDict setObject:@"10" forKey:@"tip"];
[transDict setObject:@"adjust" forKey:@"command"];

[middleware adjustTransaction:transDict];
}

-(void)adjustTranstionComplete :(PaymentEngineTransactionResponse *)transResponse
{
NSLog(@"transaction adjusted status:%@ ", transResponse.Status);
NSLog(@"transaction adjusted error: %@", transResponse.Error);

}

printCompleted

printCompleted - (Objective C)

-(void)printCompleted:(NSString *)msg

This method is called after all printText operations have been completed

deviceConnected

deviceConnected - (Objective C)

-(void)deviceConnected

This method is called when a connection to the payment terminal is established. It's an optional delegate method.

deviceDisconnected

deviceDisconnected - (Objective C)

-(void)deviceDisconnected

This method is called when a connection to the payment terminal is lost. It's an optional delegate method.

startUpdatingTerminal

startUpdatingTerminal - (Objective C)

-(void)startUpdatingTerminal

This method is called when the terminal is updating. It's an optional delegate method.

updateTerminalConfigComplete

updateTerminalConfigComplete - (Objective C)

-(void)updateTerminalConfigComplete

This method is called when all the terminal files has been updated. It's an optional delegate method.

readDeviceInfoComplete

readDeviceInfoComplete - (Objective C)

-(void) readDeviceInfoComplete :(NSDictionary *)deviceInfoDict

This delegate method needs to be implemented when the readDeviceInfo method is used to retrieve device information.

returnReceiptCompleted

returnReceiptCompleted - (Objective C)

-(void)returnReceiptCompleted :(NSString *)receiptValue

This delegate method needs to be implemented when the getReceipt method is used to retrieve receipt information.

Example

Example - (Objective C)

-(void)getReceiptEventMethod
{

    PaymentEngineMiddleware  *middleware = [PaymentEngineMiddleware getInstance];
    middleware.delegate = self;
    [middleware setDevice:@"castle" :self];

    NSMutableDictionary *receiptDict = [NSMutableDictionary new];

    // The reference number of the EMV transaction we want to get the receipt of
    [receiptDict setObject:@"964096669" forKey:@"refnum"];

    [middleware getReceipt:receiptDict];
}

-(void)returnReceiptCompleted :(NSString *)receiptValue
{
    NSLog(@"Receipt value: %@", receiptValue);

}

getV3ReceiptCompleted

getV3ReceiptCompleted - (Objective C)

-(void)getV3ReceiptCompleted :(NSString *)receiptValue

This delegate method needs to be implemented when the getV3Receipt method is used to retrieve receipt information.

Example

Example - (Objective C)

-(void)getReceiptEventMethod
{

    PaymentEngineMiddleware  *middleware = [PaymentEngineMiddleware getInstance];
    middleware.delegate = self;
    [middleware setDevice:@"castle" :self];

    [middleware getV3Receipt:@"964096669"];
}

-(void)getV3ReceiptCompleted :(NSString *)receiptValue
{
    NSLog(@"Receipt value: %@", receiptValue);

}

getMerchantCapabilitiesComplete

getMerchantCapabilitiesComplete - (Objective C)

-(void)getMerchantCapabilitiesComplete: (NSDictionary *)merchantCapDict

This delegate method needs to be implemented when the getMerchantCapEvent method is used to retrieve merchant capability information.

Example

Example - (Objective C)

/**
* Use this method to get the merchant capability from the gateway
*/
-(void)getMerchantCapEvent
{
    /**
     * Setting the value to false so we don't automatically updates the terminal
     */
    [usaepayMiddlewareClass getMerchantCapabilities:false];

}

-(void)getMerchantCapabilitiesComplete: (NSDictionary *)merchantCapDict
{
    NSLog(@"get merchant capability dict completed: %@", merchantCapDict);
}

merchantCapDict Values

Values doesn't always get returned, make sure to check if value is nil or empty.

Key	Type	Description
contactless	int	If 1 is returned, merchant supports contactless, otherwise merchant doesn't support it
debit	int	If 1 is returned, merchant supports debit, otherwise merchant doesn't support it
quickchip	int	If 1 is returned, merchant supports quickchip, otherwise merchant doesn't support it
tip_adjust	int	If 1 is returned, merchant supports tip_adjust, otherwise merchant doesn't support it

getDeviceTimeoutCompleted

getDeviceTimeoutCompleted - (Objective C)

-(void)getDeviceTimeoutCompleted :(int) seconds

This delegate method needs to be implemented when the getDeviceTimeout method is used to retrieve device timeout duration.

Example

Example - (Objective C)

/**
* Use this method to get the device timeout duration in seconds
*/
-(void)getDeviceTimeoutEvent
{
    [usaepayMiddlewareClass getDeviceTimeout];
}

-(void)getDeviceTimeoutCompleted :(int) seconds
{
    NSLog(@"timeout in seconds: %i", seconds);
}

runQueuedTransCompleted

runQueuedTransCompleted - (Objective C)

-(void)runQueuedTransCompleted :(PaymentEngineTransactionResponse *)transResponse

This delegate method is optional when runQueuedTrans method is used to process an offline queued transaction. See PaymentEngineTransactionResponse for a complete list fields that get returned.

Example

Example - (Objective C)

/**
* Use this method process offline queued transaction
*/
-(void)runOfflineQueueTrans
{

    /*
        If an identifier is passed in, it will run the queued transaction for that specific identifier
        else it will run all the queued transactions
    */
    [usaepayMiddlewareClass runQueuedTrans:@""];
}

-(void)runQueuedTransCompleted :(PaymentEngineTransactionResponse *)transResponse
{
    NSLog(@"run queue trans completed: %@", transResponse.Status);
    NSLog(@"run queue trans completed message: %@", transResponse.Error);
}

removeQueuedTransCompleted

removeQueuedTransCompleted - (Objective C)

-(void)removeQueuedTransCompleted :(NSString *)status message:(NSString *)msg

This delegate method is optional when removeQueuedTrans method is used to remove an offline queued transaction.

Example

Example - (Objective C)

/**
* Use this method process offline queued transaction
*/
-(void)removeOfflineQueueTrans
{

    /*
        If an identifier is passed in, it will remove the queued transaction for that specific identifier
        else it will remove all the queued transacitons
    */
    [usaepayMiddlewareClass removeQueuedTrans:@""];
}

-(void)removeQueuedTransCompleted :(NSString *)status message:(NSString *)msg
{
    NSLog(@"remove queue trans completed: %@", status);
    NSLog(@"remove queue trans completed message: %@", msg);
}

updateQueuedTransCompleted

updateQueuedTransCompleted - (Objective C)

-(void)updateQueuedTransCompleted:(NSString *)status message:(NSString *)msg

This delegate method is optional when updateQueuedTrans method is used to update an existing queued transaction.

Example

Example - (Objective C)

-(void)updateQueuedTransEvent
{

    NSMutableDictionary *updateQueuedDict = [[NSMutableDictionary alloc]init];
    [updateQueuedDict setObject:@"8" forKey:@"tip"];
    [updateQueuedDict setObject:@"first name" forKey:@"billfname"];
    [updateQueuedDict setObject:@"last name" forKey:@"billlname"];
    [updateQueuedDict setObject:@"2136528232" forKey:@"billphone"];
    [updateQueuedDict setObject:@"update@usaepay.com" forKey:@"email"];


    if([usaepayMiddlewareClass retrieveQueuedTrans].count > 0)
    {
        PaymentEngineResultQueue *resultQueue = (PaymentEngineResultQueue *)[[usaepayMiddlewareClass retrieveQueuedTrans] objectAtIndex:0];

        NSLog(@"identifier: %@", resultQueue.identifier);
        NSLog(@"request total amount: %f", resultQueue.totalAmount);
        NSLog(@"card num: %@", resultQueue.cardNum);

        [usaepayMiddlewareClass updateQueuedTrans:updateQueuedDict :resultQueue.identifier];

    }
}

-(void)updateQueuedTransCompleted:(NSString *)status message:(NSString *)msg
{
    NSLog(@"update queue trans completed: %@", status);
    NSLog(@"update queue trans completed message: %@", msg);
}

    /*
        If an identifier is passed in, it will run the queued transaction for that specific identifier
        else it will run all the queued transacitons
    */
    [usaepayMiddlewareClass runQueuedTrans:@""];
}

-(void)runQueuedTransCompleted :(PaymentEngineTransactionResponse *)transResponse
{
    NSLog(@"run queue trans completed: %@", transResponse.Status);
    NSLog(@"run queue trans completed message: %@", transResponse.Error);
}

removeQueuedTransCompleted

removeQueuedTransCompleted - (Objective C)

-(void)removeQueuedTransCompleted :(NSString *)status message:(NSString *)msg

This delegate method is optional when the removeQueuedTrans method is used to remove an offline queued transaction.

Example

Example - (Objective C)

/**
* Use this method process offline queued transaction
*/
-(void)removeOfflineQueueTrans
{

    /*
        If an identifier is passed in, it will remove the queued transaction for that specific identifier
        else it will remove all the queued transactions
    */
    [usaepayMiddlewareClass removeQueuedTrans:@""];
}

-(void)removeQueuedTransCompleted :(NSString *)status message:(NSString *)msg
{
    NSLog(@"remove queue trans completed: %@", status);
    NSLog(@"remove queue trans completed message: %@", msg);
}

registerDeviceCompleted

registerDeviceCompleted - (Objective C)

- (void) registerDeviceCompleted :(NSString *)status errorMsg:(NSString *)msg deviceInfo :(NSDictionary *)infoDict

This delegate method is optional when the registerDevice method is used to register cloud device.

deleteCloudDeviceCompleted

deleteCloudDeviceCompleted - (Objective C)

-(void) deleteCloudDeviceCompleted :(NSDictionary *)dict

This delegate method is optional when the deleteCloudDevice method is used to delete cloud device.

updateCloudDeviceCompleted

updateCloudDeviceCompleted - (Objective C)

-(void) updateCloudDeviceCompleted :(NSDictionary *)dict

This delegate method is optional when the updateCloudDevice method is used to update cloud device.

getCloudDeviceListCompleted

getCloudDeviceListCompleted - (Objective C)

-(void)getCloudDeviceListCompleted :(NSDictionary *)deviceListDict

This delegate method is optional when the getCloudDeviceList method is used to get a list of cloud devices.

getCloudDeviceStatusCompleted

getCloudDeviceStatusCompleted - (Objective C)

-(void) getCloudDeviceStatusCompleted :(NSDictionary *)dict

This delegate method is optional when the getCloudDeviceStatus method is used to get status of a specific cloud device.

getCloudPaymentStatusCompleted

getCloudPaymentStatusCompleted - (Objective C)

-(void) getCloudPaymentStatusCompleted :(NSDictionary *)dict

This delegate method is optional when the getCloudPaymentStatus method is used to get current cloud payment status .

startCloudTransactionCompleted

startCloudTransactionCompleted - (Objective C)

-(void) startCloudTransactionCompleted :(NSDictionary *)dic

This delegate method is optional when the startTransaction method is used to start a cloud transaction.

cancelCloudPaymentTransCompleted

cancelCloudPaymentTransCompleted - (Objective C)

-(void) cancelCloudPaymentTransCompleted :(NSDictionary *)dict

This delegate method is optional when the cancelCloudPaymentTransaction method is used to cancel a cloud transaction.

PaymentEngineAPIDelegate

• transactionComplete :(PaymentEngineTransactionResponse *)transResponse - This is a call back for startTransaction method.
• captureSignatureComplete - Called when capturing signature is completed. Callback for captureSignature method.

transactionComplete - APIDelegate

transactionComplete - (Objective C)

-(void)transactionComplete :(PaymentEngineTransactionResponse *)transResponse;

This method is called when a transaction has completed processing: it will be called for all errors, declines or approvals. This is a required delegate method. The delegate method needs to be implemented when user starts a transaction using the middleware. See PaymentEngineTransactionResponse for a complete list fields that get returned.

Example: Extracting the RefNum from transactionComplete

Example: Extracting the RefNum from transactionComplete - (Objective C)

-(void)transactionComplete :(PaymentEngineTransactionResponse *)transResponse
{
     NSLog(@"refNum: %@", transResponse.RefNum);
}

The RefNum is needed if you are going to adjust/void the transaction.

captureSignatureComplete - APIDelegate

captureSignatureComplete - (Objective C)

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse   

This delegate method needs to be implemented when the captureSignature method is used to capture a signature. Read PaymentEngineTransactionResponse for a complete list of returned fields.

Example

Example - (Objective C)

-(void)captureSignaureMethod
{
    PaymentEngineAPICom *apiCom = [PaymentEngineAPICom getInstance];
    apiCom.delegate = self;

    UIImage *signatureImg = [UIImage imageNamed:@"signatureImg.png"];
    NSData *imgData = UIImageJPEGRepresentation(signatureImg, 0.5f);
    NSString *imgBase64 = [imgData base64EncodedStringWithOptions:0];

    NSMutableDictionary *transDict = [NSMutableDictionary new];

    [transDict setObject:imgBase64 forKey:@"signature"];
    [transDict setObject:@"1296965885" forKey:@"refNum"];
    [transDict setObject:@"12.01" forKey:@"amount"];
    [transDict setObject:@"capture" forKey:@"command"];

    [apiCom captureSignature:transDict];
}

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse
{
    NSLog(@"signature captured:%@ ", transResponse.Status);
    NSLog(@"signature error reason: %@", transResponse.Error);

}

%settings%

Parameter Name	Type	Description
timeout		Transaction timeout, how long to wait for transaction authorization to complete.
enable_standalone		Allows transactions to be initiated from terminal (if supported).
share_device		If true, this allows the payment device to be used by other merchants. If false, only the merchant associated with the apikeyid may send transactions to device.
notify_update		If true, device will be notified on all future updates
notify_update_next		If true, device will be notified only on the next update. After notification, this is automatically set back to false.
sleep_battery_device		This is the amount of inactive time (in minutes) before the device enters full sleep if it is running on battery. If in full sleep, you will need to turn the device on again before processing. Wifi and Bluetooth pairing should persist, even after full sleep. Set to '0' to never sleep.
sleep_battery_display		This is the amount of inactive time (in minutes) before the device enters display sleep if it is running on battery. If in display sleep, just send a transaction to the device or tap any button to wake the device. Set to '0' to never sleep.
sleep_powered_device		This is the amount of inactive time (in minutes) before the device enters full sleep if it is plugged into power. If in full sleep, you will need to turn the device on again before processing. Wifi and Bluetooth pairing should persist, even after full sleep. Set to '0' to never sleep.
sleep_powered_display		This is the amount of inactive time (in minutes) before the device enters display sleep if it is plugged into power. If in display sleep, just send a transaction to the device or tap any button to wake the device. Set to '0' to never sleep.

%terminal_config%

Parameter Name	Type	Description
device_name	String	Name of device, should be "MP200".
enable_emv	boolean	Enables EMV processing.
enable_debit_msr	boolean	Enables PIN debit for swiped transactions.
enable_tip_adjust	boolean	Allows EMV transaction amounts to be adjusted after authorization (to add tip). Disables PIN authentication.
enable_contactless	boolean	Enables NFC reader.

%terminal_info%

Parameter Name	Type	Description
make		Manufacturer
model		Device model
revision		Hardware version number
serial		Device serial number
key_pin		Device PIN encryption key. Only necessary if merchant will be processing transactions with a PIN.
key_pan		Device PAN encryption key.

%CVMRESULT%

Constant	Description
FAIL_CVM	Indicates the CMV failed.
NO_CVM_REQ	Indicates the CVM is not required.
PIN_OFFLINE_ENCR	Indicates the PIN was verified offline and encrypted.
PIN_OFFLINE_PLAIN	Indicates the PIN was verified offline in plaintext.
PIN_ONLINE	Indicates the PIN was verified online.
SIGNATURE_REQ	Indicates that a signature is required.

%UE_ERROR%

Constant	Description
ALREADY_STARTED
BAD_SWIPE	MP200 received bad swipe. Transaction will be aborted, retry.
GATEWAY_401_UNAUTHORIZED
GATEWAY_CONNECTION_ERROR	The connection to the gateway failed.
GENERAL_EXCEPTION_CAUGHT	Exception from Exception class caught, stack trace printed, report this error.
HANDLED	These errors go out to the user.
INVALID_AMOUNT	The amount entered was invalid.
INVALID_MAG_STRIPE	The transaction was terminated because a bad mag swipe was retried 3 times.
INVALID_TERMINAL_CONFIG
INVALID_UPDATE_PARAMETER
LOW_BATTERY	Low battery, plug in the MP200.
MP200_COMMAND_TIMEOUT	Command to MP200 timed out, transaction will abort, retry.
NO_BT_DEVICE	No BT(bluetooth) device was found, check BT settings.
NO_DEVICES_FOUND
NO_ERROR
NOT_CONNECTED	The device is not in the connected state to execute this function.
NOT_ENOUGH_SPACE_FOR_UPDATE	Free up memory in the app cache directory.
TIMEOUT_GATEWAY	Timeout has occurred between gateway.
TRANSACTION_CANCEL_BUTTON	The transaction was cancelled by pressing the cancel button.
TRANSACTION_CARD_ERROR
TRANSACTION_CARD_REMOVED
TRANSACTION_INVALID_PIN	Transaction was terminated because of an invalid PIN.
TRANSACTION_REQUESTS_CHANGE_INTERFACE	This will also fire a delegate to change interface.
UNHANDLED_ERROR	Unhandled Error, please report this.
UNHANDLED_EXCEPTION
UNHANDLED_EXCEPTION_CAUGHT
UPDATE_COMPLETE
UPDATE_FAILED	An error occurred during the update process causing it to fail.
USB_CONNECTION_CLOSED	USB Connection has been closed, reconnect.
USER_INPUT_EXCEPTION

%holdTransInfo%

Key	Description
command	Processing command, in this case it will be "adjust".
amount	Total amount of the transaction including tips
tip	The amount to tip
refNum	The refNum of the transaction for which you are adjusting.

%holdCaptureInfo%

Key	Description
command	Processing command, in this case it will be "capture".
amount	Total amount of the transaction for which you are capturing the signature.
refNum	The refNum of the transaction for which you are capturing the signature.
signature	The base64Encoded string of the image.

%signatureDict%

Key	Description
command	Processing command, in this case it will be "capture".
amount	Total amount of the transaction for which you are capturing the signature.
refNum	The refNum of the transaction for which you are capturing the signature.
signature	The base64Encoded string of the image.

%custom_flow%

Parameter	Description
%custom_flow%(comma delimited string)	Allows you to customize the order in which each payment screen is displayed on the device.

%custom_flow%

Parameter	Description
payment	Payment taking screen (must come before result).
amount	Optional confirmation of amount (must come before result).
result	Displays the transaction result.
signature	Signature capture (must come after result).
signature_required	Signature capture. If the signature is cancelled, then the transaction will be cancelled (must come after result).

%Address%

Parameter	Type	Description
FirstName	String
LastName	String
Company	String
Street	String
Street2	String
City	String
State	String
PostalCode	String
Country	String
Phone	String
Fax	String

%AmountDetail%

Parameter	Type	Description
Tax	String	Total tax amount
NonTaxable	String	Set to "Y" to indicate that the transaction is non-taxable.
Cash	String	For debit, amount of cashback
Tip	String	Tip amount, only set if choosing not to prompt for tip on terminal
Discount	String	Amount of order level discount
Shipping	String	Shipping charges
Duty	String	Duty charges (for level 3 processing)
EnablePartialAuth	bool	Include this parameter to authorize partial funds when the full amount is not available. For example, if the total is $10 and the customer only has $5 in their account, $5 will be authorized. If not included in request, partial authorization defaults to disabled.

%TransactionRequest%

Parameter	Type	Description
DeviceKey	String	Unique identifier for the terminal that the transaction will be sent to.
Command	String	Payment command to run. Supported commands are: cc:sale, cc:authonly and cc:refund
Amount	String	Amount to process payment for. This should be the final amount (unless choosing to allow terminal to prompt for tip and cashback).
AmountDetail	AmountDetail Class	Detailed breakdown of the above total Amount.
PoNum	String	Purchase order number, only required for corporate cards.
Invoice	String	Invoice number, only first 10 digits are sent to platform
OrderID	String	Order identifier, alpha numeric
Description	String	Transaction description (visible to customer on receipt)
Comments	String	Internal transaction comments (visible only to merchant)
RestaurantTable	String	Table number
Clerk	String	Clerk/Cashier name
BillingAddress	address	Billing address information
ShippingAddress	address	Shipping address information
CustomerEmail	String	Customer email address
CustomerID	String	Customer ID
ClientIP	String	IP address of customer, useful if request is initiated from a server.
GeoLocation	String	Latitude and longitude to record for transaction. Example: "40.7142700,-74.0059700"
LineItems	LineItem[]	Array of line item details
ManualKey	Boolean	Set to true to have the terminal prompt for manual card number entry instead of swipe/dip
PromptTip	Boolean	Set to true to have the terminal prompt the customer for a tip amount.
PromptCashBack	Boolean	Set to true to have the terminal prompt the customer for cash back.
PromptSignature	Boolean	Set to false to prevent the terminal from capturing the customer signature. If the terminal supports signature capture, it will be on by default.
CustomFlow	String	Optional string that controls the sequence of screens presented to the customer during payment. Leave blank to use the default flow. Example: "amount,payment,result"
SaveCard	Boolean	Set to true to save the payment data to the customer record
Timeout	Integer	Set the transaction timeout
BlockOffline	Boolean	Set to true to have the request refused if the device is currently offline

%TransactionResult%

Parameter	Type	Description
TransactionKey	String	Unique identifier for transaction. Can be used to perform actions such as refund and void on a transaction.
RefNum	String	Numeric sequential transaction reference number. Can be used with older gateway APIs.
AuthAmount	String	Authroized amount returned from processor.
AuthCode	String	AuthCode returned from processor.
ProcRefNum	String	Processor generated transaction reference number (if available).
Result	String	Result of transaction: Approved, Declined, Error or Partial Approval.
ResultCode	String	Result code of transaction: A, D, E or P
IsDuplicate	String	"Y" indicates that a duplicate transaction was detected, the transaction was folded, and the details from the original transaction was returned.
Error	String	Error message if transaction was a decline or error
ErrorCode	String	Gateway error code
ProcRefNum	String	Backend processor reference number (if available)
AVS	AvsResult	Result of address verification (if manually keyed)
CVC	CvcResult	Result of card code verification (if manually keyed)
CreditCard	CreditCard	Information about the credit card used
Token	String	Reuasable token to charge payment data in a new request

%TerminalConfig%

Parameter	Type	Description
EnableEMV	bool	Enable the smart card slot for EMV processing
EnableDebitMSR	bool	Enable swiped PIN debit transactions
EnableContactless	bool	Enable the contactless reader for NFC transactions
TipAdjustAfterAuth	bool	Allow addition of tip after initial authorization. Disables PIN CVM and No CVM.

%DeviceDetails%

Parameter	Type	Description
Make	String	Device manufacturer
Model	String	Model name of terminal
Revision	String	Firmware version
Serial	String	Serial number

%DeviceSettings%

Parameter	Type	Description
Timeout	int	Sets transaction timeout in seconds.
EnableStandalone	bool	Allows transactions to be initiated by terminal.
ShareDevice	bool	Allows terminal to be used by any API key including those belonging to other merchants.