You are currently viewing the documentation for version

Introduction

Welcome iOS Developers

The Handpoint SDK platform a.k.a headstart for iOS provides a simple application programming interface simplifying the development of your payment solutions considerably.

You as an mPOS application developer can get access to the various components for integrating with Handpoint Platform as well as sample source to get you started quickly.

The Handpoint SDK for iOS includes:

  • HeftSimulatorLibrary: A version of the library which simulates card reader behaviour
  • Docs: Integration manual for the Handpoint SDK
  • Heft Library:The library and it’s interface

On dev.handpoint.com you can find a quick start guide for XCode as well as getting started guides with a development kit or the simulator!

Please note that before submitting an app to the Apple App store a MFi hardware request has to be submitted to Apple to be able to use an external accessory. Please fill our this form before submitting your app to the App store and we will get back to you. If you have any questions, contact us for more details.

Overview

The 3 files that make up the API (provide access to the library) are HeftManager.h, HeftClient.h and HeftStatusReportPublic.h. The functionality includes discovering BT devices, connecting to a compatible device (card reader), performing financial transactions, receiving and responding to messages from the card reader as well as access to logs. The SDK comes also with a library configured to simulate a card reader - intended for early development of a user interface.


Supported functionality:

  • Discovery of remote BT devices.
  • Connect to remote BT device.
  • Physical connection to BluePad500 external accessory.
  • Executing financial transaction.
  • Reporting status of transactions.
  • Control and access to device logs.
  • Scan with BluePad500 devices.
  • Limited card reader simulation.

Quick look at the interface

HeftManager.h discovers BT devices and makes them accessible through the sharedManager method. Returns a HeftClient object for a specific BT device through the method clientForDevice. Provides the HeftDiscoveryDelegate protocol for handling messages during the discovery process.

HeftClient.h is the main interface and handles the communication between the mPos app and the card reader. The clientForDevice method of the HeftManager returns a HeftClient object. The HeftClient object also stores information about it's card reader device in the mpedInfo dictionary.

HeftStatusReportPublic.h provides the HeftStatusReportDelegate protocol which defines a number of methods for implementing in the mPos app. These methods are called by heft at appropriate times for reporting status and results of operations done by the HeftClient object.


Dependencies

The Heft library depends on the Security and ExternalAccessory frameworks included with the iOS SDK. These frameworks and the heft library, libheft.a need to be linked to your project for the Handpoint interface to work properly. Also the com.datecs.pinpad string needs to be added to the "Supported external accessory protocols" in the apps .plist file.


Special build settings

A part of the library is written in c++ therefor the -lc++ linker flag needs to be set. Add it under "Other Linker Flags" under the "Linking" section of your projects settings "Build Settings" tab.

Also, to prevent the warning: "file was built for archive which is not the architecture being linked (armv7s)". Then set Build Active Architecture only to YES.


version 2.6.0

Simulator

The Handpoint iOS SDK comes with an additional library which is configured to run in simulation mode, reducing the need for a card reader when developing the UI. The simulator has a limited functionality and should only be relied upon when prototyping the user interface.

The simulator library is located in the HeftSimulator folder. To use the simulator library just link it as you would do with a normal library and make sure there are no references to the Heft Library.

To switch from the simulator to the regular heft library just remove the references to the simulator library and link the Heft Library instead to your project

The behavior of the simulator is controlled by the passed amount of the simulated transaction operation. There are four different behaviors simulated: Declined transaction, Cancelled transaction, Signature Request and Approved transaction.


Usage

The following code would simulate a declined transaction as the amount is 1000.

[heftClient saleWithAmount:[1000] currency:@"GBP" cardholder:YES];

The table below shows the different options.

Amount Behaviour
1000 Declined transaction
2000 User cancelled
3000 Signature requested
Any other amount Approved transaction

Transactions

Sale

method Available since 2.2.2

saleWithAmount

A sale initiates a payment operation to the card reader.

Parameters

Parameter Type Validation Notes
amount NSInteger Required Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency NSString* Required 3 letter currency code in accordance to ISO4217
present BOOL Required YES if cardholder is present - NO otherwise
reference NSString* Optional string for customer reference
months BOOL Optional string for budget functionality


Events invoked

responseStatus
Invoked while during transaction with different statuses from card reader
responseError
Invoked to inform when an error response happens.
requestSignature
Invoked if card verification requires signature.
responseFinanceStatus
Invoked when the card reader finishes processing the transaction

Returns

Boolean
YES if operation starts successfully

Code example

//saleWithAmount:currency:cardholder:
//Initiates a sale transaction.
-(IBAction)doSale
{
	if(reference != nil) //checks if a reference number should be assigned to the transaction
	{
		if(months > 0) //checks if the budget functionality should also be used
		{
			[heftClient saleWithAmount:amount
									currency:selectedCurrency
									cardholder:isPresent
									reference:reference divideBy:months];
		}
		else
		{
			[heftClient saleWithAmount:amount
									currency:selectedCurrency
									cardholder:isPresent
									reference:reference];
		}
	}
	else //Just a simple transaction
	{
		[heftClient saleWithAmount:amount
									currency:selectedCurrency
									cardholder:isPresent];
	} 
}

Sale Reversal

method Available since 2.2.2

saleVoidWithAmount

Request a void operation on previous sale transaction, referred to by the parameter transaction. Parameters amount, currency and present must be the same as the in the sale to be voided. This operation reverts (if possible) a specific sale identified with a transaction id. Note that transactions can only be reversed within the same day as the transaction was made.

Parameters

Parameter Type Validation Notes
amount NSInteger Required Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency NSString* Required 3 letter currency code in accordance to ISO4217
present BOOL Required YES if cardholder is present - NO otherwise
transaction NSString* Required TransactionID of the sale transaction to be voided


Events invoked

responseStatus
Invoked while during transaction with different statuses from card reader
responseError
Invoked to inform when an error response happens.
responseFinanceStatus
Invoked when the card reader finishes processing the transaction

Returns

Boolean
YES if operation starts successfully

Code example

//saleVoidWithAmount:currency:cardholder:transaction:
//Initiates a void request on a previous sale transaction.
-(void)voidSaleWithId:(NSString*)transactionID
{
	[heftClient saleVoidWithAmount:amount
									currency:currency
									cardholder:isPresent
									transaction:transactionID;]
}

Refund

method Available since 2.2.2

refundWithAmount

A refund initiates a refund operation to the card reader. This operation moves funds from your account to the cardholders credit card.

Parameters

Parameter Type Validation Notes
amount NSInteger Required Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency NSString* Required 3 letter currency code in accordance to ISO4217
present BOOL Required YES if cardholder is present - NO otherwise
reference NSString* Optional string for customer reference


Events invoked

responseStatus
Invoked while during transaction with different statuses from card reader
responseError
Invoked to inform when an error response happens.
responseFinanceStatus
Invoked when the card reader finishes processing the transaction

Returns

Boolean
YES if operation starts successfully

Code example

//refundWithAmount:currency:cardholder:
//Initiates a refund transaction
-(IBAction)doRefund
{
	if(reference != nil)
	{
		[heftClient refundWithAmount:amount
									currency:selectedCurrency
									cardholder:isPresent
									reference:reference];
	}
	else
	{
		[heftClient refundWithAmount:amount
									currency:selectedCurrency
									cardholder:isPresent];
	}
}

Refund reversal

method Available since 2.2.2

refundVoidWithAmount

Request a void operation on previous refund transaction, referred to by the parameter transaction. Parameters amount, currency and present must be the same as the in the refund to be voided. This operation reverts (if possible) a specific refund identified with a transaction id. Note that transactions can only be reversed within the same day as the transaction was made.

Parameters

Parameter Type Validation Notes
amount NSInteger Required Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency NSString* Required 3 letter currency code in accordance to ISO4217
present BOOL Required YES if cardholder is present - NO otherwise
transaction NSString* Required TransactionID of the refund transaction to be voided


Events invoked

responseStatus
Invoked while during transaction with different statuses from card reader
responseError
Invoked to inform when an error response happens.
responseFinanceStatus
Invoked when the card reader finishes processing the transaction

Returns

Boolean
YES if the operation was successfully sent to device

Code example

//RefundVoidWithAmount:currency:cardholder:transaction:
//Initiates a void request on a previous refund transaction.
-(void)voidRefundWithId:(NSString*)transactionID
{
	[heftClient refundVoidWithAmount:amount
									currency:currency
									cardholder:isPresent
									transaction:transactionID;]
}

Accept signature

method Available since 2.2.2

acceptSignature

A requestSignature event is invoked during transaction when signature verification is needed (f.ex when payment is done with a magstripe card). The merchant is required to ask the cardholder for signature and approve (or disapprove) the signature. signatureRequired tells the card reader if the signature was approved by passing YES. To disapprove then NO is passed.

Parameters

Parameter Type Validation Notes
flag Boolean Required YES if signature is valid, NO otherwise


Events invoked

responseStatus
Invoked while during transaction with different statuses from card reader
responseError
Invoked to inform when an error response happens.
responseFinanceStatus
Invoked when the card reader finishes processing the transaction

Code example

//acceptSignature:
//Inform the card reader if signature is valid or not
-(IBAction)accept
{
	[heftClient acceptSignature:YES];
}
-(IBAction)decline
{
	[heftClient acceptSignature:NO];
}

Cancel operation

method Available since 2.2.2

cancel

This method attempts to cancel the current transaction on the card reader. Note that operations can only be cancelled before requests are sent to the gateway. There is a flag called cancelAllowed in the xml in the responseStatus event that can be used to check if the transaction is in a state that allows cancel.

Events invoked

responseStatus
Invoked while during transaction with different statuses from card reader
responseError
Invoked to inform when an error response happens.
responseFinanceStatus
Invoked when the card reader finishes processing the transaction
responseEnableScanner
Invoked when scanner is disabled

Code example

//cancel
//Cancels/stops the current financial operation or scanner operation. 
-(IBAction)cancel //Cancel button
{
	[heftClient cancel];
}

Device management

Shared Manager

method Available since 2.2.2

sharedManager

Provides access to the heftManager. The heft manager is used for discovering devices and creating a HeftClient with a connection to selected device.

Returns

HeftManager
The heftManager instance

Code example

//SharedManager
//Provides access to the heftManager

//Create an instance of the shared manager at set it's delegate
HeftManager* heftManager = [HeftManager sharedManager];
heftManager.delegate = self;

Client for device (NSData)

method Available since 2.2.2

clientForDevice

Creates a HeftClient object. If a connection is successful the HeftClient object is returned in the didConnect event. All transactions are done using the heftClient.

Parameters

Parameter Type Validation Notes
device NSInteger Required The device to connect to.
sharedSecret NSData* Required Shared secret only known by the merchant and Handpoint.
aDelegate BOOL Required The HeftStatusReportDelegate for the HeftClient to report to.


Events invoked

didConnect
Called when a connection to specified device was created.

Returns

Boolean
YES if operation starts successfully

Code example

//clientForDevice:sharedSecret:delegate:
//Creates a HeftClient object(connection to device)
uint8_t ss[32] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27, 0x28, 0x29, 0x30, 0x31, 0x32};
NSData* sharedSecret = [[NSData alloc] initWithBytes:ss length:sizeof(ss)]
-(void)connectToFirstCardReaderWith:(NSData*)sharedSecret;
{
	//Try to connect to first device in devices array
	[heftManager clientForDevice:[[heftManager devicesCopy] objectAtIndex:0] sharedSecret:sharedSecret delegate:self];
	//Client calls the didConnect delegate function if successful 
}

Client for device (NSString)

method Available since 1.3.1

clientForDevice

Creates a HeftClient object. If a connection is successful the HeftClient object is returned in the didConnect event. All transactions are done using the heftClient.

Parameters

Parameter Type Validation Notes
device NSInteger Required The device to connect to.
sharedSecret NSString* Required Shared secret only known by the merchant and Handpoint.
aDelegate BOOL Required The HeftStatusReportDelegate for the HeftClient to report to.


Events invoked

didConnect
Called when a connection to specified device was created.

Returns

Boolean
YES if operation starts successfully

Code example

//clientForDevice:sharedSecretString:delegate:
//Creates a HeftClient object(connection to device)
NSString* sharedSecret = @"0102030405060708091011121314151617181920212223242526272829303132";
-(void)connectToFirstCardReaderWith:(NSString*)sharedSecret;
{
	//Try to connect to first device in devices array
	[heftManager clientForDevice:[[heftManager devicesCopy] objectAtIndex:0] sharedSecretString:sharedSecret delegate:self];
	//Client calls the didConnect delegate function if successful 
}

Start Discovery

method Available since 2.2.2

startDiscovery

Displays a list of available accessory devices in a modal window.

Parameters

Parameter Type Validation Notes
fDiscoverAllDevices Boolean Required Boolean. NO if library should only discover supported devices, YES otherwise


Code example

//startDiscovery
//Starts the BT discovery process
-(void)startDiscovery:(BOOL)discoverAllDevices; 
{
	[heftManager startDiscovery:discoverAllDevices];
	//Start search activity indicator or other desired functions
}

Set log level

method Available since 2.2.2

logSetLevel

Sets the log level of the card reader. There are for levels of logging for the device: none, info, full, debug. Setting the log level means that relevant information concerning the application operation will be stored.

Parameters

Parameter Type Validation Notes
level eLogLevel Required eLogLevel available types: eLogNone, eLogInfo, eLogFull, eLogDebug


Returns

Boolean
This method always returns YES

Code example

//logSetLevel:
//Sets the log level of the card reader.
-(void)disableCardReaderLogs
{
	[heftClient logSetLevel:eLogNone];
}
-(void)enableCardReaderDebugLogs
{
	[heftClient logSetLevel:eLogDebug];
}

Fetch logs

method Available since 2.2.2

logGetInfo

Retrieves the logging info. Returns them in the responseLogInfo event.

Returns

Boolean
This method always returns YES

Code example

//logGetInfo
//Retrieves the logging info.
-(void)getLogsFromCardReader
{
	[heftClient logGetInfo];
}

Reset logs

method Available since 2.2.2

logReset

Clears the logging information stored so far.

Returns

Boolean
This method always returns YES

Code example

//logReset
//Clears the logging information stored so far
-(void)clearLogs
{
	[heftClient logReset];
}

Enable scanner

method Available since 1.3.1

enableScanner

Places the card reader in a scan mode. Only if the card reader supports it. To cancel/stop scan mode call the cancel method of the heft client.

Parameters

Parameter Type Validation Notes
multiScan Boolean Optional Yes [default] to activate multiScan mode - No to activate singleScan mode. Multi-scan mode allows the user to scan until scan operation is canceled or timeout occurs, single-scan mode is active until one scan has occurred then it disables the scan mode.
buttonMode Boolean Optional Yes [default] if buttonMode is on - No otherwise. If button mode is on then the operator needs to press the scan buttons to activate the scanner(during scan mode).
timeoutSeconds NSInteger Optional 0 [default] - card reader will determine when scanning should time out. x - the scanner will time out if x seconds of inactivity occur.


Events invoked

responseScannerEvent:
Called to inform that a scan has been performed, several calls can be expected. Several calls to this method happen after a scan action has been performed to inform about scan information operation. The info object contains scanCode, status and a dictionary (xml).

Code example

//enableScanner:multiScan:buttonMode:timeoutSeconds
//Places the card reader in a scan only mode. 
//To cancel/stop scan mode call cancel function.
-(IBAction)startScan 
{
	[heftClient enableScanner];
}
-(IBAction)startMultiScan
{
	[heftClient enableScannerWithMultiScan:YES];
}

Disable scanner

method Available since 1.3.1

disableScanner

Disables the scanner if possible

Events invoked

responseScannerDisabled:
Called to inform that a scan has been performed, several calls can be expected. Several calls to this method happen after a scan action has been performed to inform about scan information operation. The info object contains scanCode, status and a dictionary (xml).

Code example

//disableScanner
//Disable the scanner
	-(IBAction)disableScanner
{
[heftClient disableScanner];
}

financeInit

method Available since 2.2.2

financeInit

Initializes the card reader and updates config. This is used to manually update card reader software if available.

Events invoked

responseStatus
Invoked while during transaction with different statuses from card reader
responseError
Invoked to inform when an error response happens.
responseFinanceStatus
Invoked when the card reader finishes processing the transaction

Returns

Boolean
This method always returns YES

Code example

//financeInit
//Initializes the card reader and updates config.
-(IBAction)updateCardReader
{
	[heftClient financeInit];
}

Reset Devices

method Available since 2.2.2

resetDevices

Resets the devices array, clears all references to discovered devices

Code example

//resetDevices
//Resets the devices array, clears all references to discovered devices
-(void)clearDevices;
{
	[sharedManager resetDevices];
	//Array returned by devicesCopy should now be cleared
}

Get SDK version

method Available since 1.3.1

getSDKVersion

Returns the current SDK version number in string format

Code example

//getSDKVersion
//Log SDK version number
	NSLOG(@"SDK version: %@", [heftManager getSDKVersion];

Get SDK build number

method Available since 1.3.1

getSDKBuildNumber

Returns the current SDK build number in string format

Code example

//getSDKBuildNumber
//Log SDK build number
	NSLOG(@"SDK build: %@", [heftManager getSDKBuildNumber];

Events

didConnect

method Available since 2.2.2

didConnect

Called when a connection to the client has been established through the method clientForDevice.

Parameters

Parameter Type Validation Notes
client HeftClient Required The client object, used to perform transactions and communication to device.


Code example

//didConnect:
//Called when a connection to specified device was created.
-(void)didConnect:(id<HeftClient>)client 
{
	// connected successfully to a device
	// assign the client to our heftClient property
	heftClient = client;
}

didDiscoverFinished

method Available since 2.2.2

didDiscoverFinished

When the modal window from startDiscovery is closed then this event is called.

Code example

//didDiscoverFinished
// This function gets called when discovery is finished
- (void)didDiscoverFinished;
{
	NSLog(@"Discover finished");
	//Stop search activity indicator or other desired functions 
}

didFindAccessoryDevice

method Available since 2.2.2

didFindAccessoryDevice

Notifies that new accessory device was found. When a card reader is detected this delegate is called. You can take the newDevice object and create a new heft client for that particular device or store it in memory to connect to it later.

Parameters

Parameter Type Validation Notes
newDevice HeftRemoteDevice Required An object containing a reference to the accessory device


Code example

//didFindAccessoryDevice
//Delegate that notifies that new accessory device was found.
- (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice
{
	NSLog(@"Found new device");
	//Connect to device or store found device for later
} 

didLostAccessoryDevice

method Available since 2.2.2

didLostAccessoryDevice

Notifies that accessory device was disconnected.

Parameters

Parameter Type Validation Notes
oldDevice HeftRemoteDevice Required An object containing a reference to the accessory device


Code example

//didLostAccessoryDevice
//Delegate that notifies that accessory device was disconnected
- (void)didLostAccessoryDevice:(HeftRemoteDevice*)oldDevice
{
	NSLog(@"Device disconnected");
	//Remove device from devices array
	[heftManager.devicesCopy removeObject:oldDevice];
	//Do some cleanup after disconnecting if necessary 
	
} 

responseStatus

method Available since 2.2.2

responseStatus

Called to inform about the status of the transaction, several calls can be expected. Several calls to this method happen after a transaction is initiated from the HeftClient to inform about status of operation. The info object contains a string (status) and a dictionary (xml).

Parameters

Parameter Type Validation Notes
info ResponseInfo Required Includes status code, status text and detailed xml.


Code example

//responseStatus:
//Called to inform about the status of the transaction
-(void)esponseStatus:(id<ResponseInfo>)info
{
	NSLog(info.status);
	NSLog(info.xml.description);
}

responseFinanceStatus

method Available since 2.2.2

responseFinanceStatus

Notifies that transaction has completed.

Parameters

Parameter Type Validation Notes
info FinanceResponseInfo Required Information about current transaction status.


Code example

//responseFinanceStatus:
//Called at the end of transaction to inform about the result of the operation
-(void)responseFinanceStatus:(id<FinanceResponseInfo>)info
{
	NSLog(info.status);
	NSLog(info.customerReceipt);
	//print receipts
}

responseError

method Available since 2.2.2

responseError

Called to inform about the status of the transaction, several calls can be expected. Several calls to this method happen after a transaction is initiated from the HeftClient to inform about status of operation. The info object contains a string (status) and a dictionary (xml).

Parameters

Parameter Type Validation Notes
info ResponseInfo Required The info object contains a string (status) and a dictionary (xml).


Code example

//responseError:
//Called when to inform when an error response happens.
-(void)responseError:(id<ResponseInfo>)info
{
	NSLog(info.status);
	NSLog(info.xml.description);
}

requestSignature

method Available since 2.2.2

requestSignature

Is called if during a financial operation a signature from the customer is needed. The requestSignature delegate should be implemented to print out or display the receipt for the customer to sign and provide the merchant with the means to confirm the signature.

Parameters

Parameter Type Validation Notes
receipt NSString* Required The receipt is a html formatted string containing a receipt for the customer to sign


Code example

//requestSignature:
//Is called if a signature from the customer is needed.
-(void)requestSignature:(NSString*)receipt
{
	NSLog(receipt);
	//Display buttons to accept or decline customer signature
	UIAlertView* alert = [[UIAlertView alloc] initWithTitle:@"" message:@"sign?" delegate:self cancelButtonTitle:@"No" otherButtonTitles:@"Yes", nil];
	[alert show];
}

cancelSignature

method Available since 2.2.2

cancelSignature

Called if the signature request times out. If the card reader does not receive an approval for the signature within a certain timeframe (45 sec) it cancels the transaction and sends a notification to the app.

Code example

//cancelSignature
//Called if the signature request times out.
-(void)cancelSignature
{
	NSLog(@"Signature request timed out");
}

responseScannerEvent

method Available since 2.2.2

responseScannerEvent

Called to inform that a scan has been performed, several calls can be expected.

Parameters

Parameter Type Validation Notes
info ScannerEventResponseInfo Required The info object contains scanCode, status and a dictionary (xml).


Code example

//responseScannerEvent:
//Called to inform that a scan has been performed
-(void)responseScannerEvent:(id<ScannerEventResponseInfo>)info
{
	NSLog(info.scanCode); //barcode scanned
	NSLog(info.xml.description);
}

responseScannerDisabled

method Available since 1.3.1

responseScannerDisabled

Called to notify that the scanner has been disabled.

Parameters

Parameter Type Validation Notes
info ScannerDisabledResponseInfo Required The info object contains information about the scanner operation.


Code example

//responseScannerDisabled:
//Called to notify that the scanner has been disabled. 
-(void)responseScannerDisabled:(id<ScannerDisabledResponseInfo>)info
{
	NSLog(info.status);
}

responseLogInfo

method Available since 2.2.2

responseLogInfo

Called when logs have been downloaded from the card reader by using the logGetInfo method.

Parameters

Parameter Type Validation Notes
info LogInfo Required The info object has the string property log which holds the log info in text with carriage returns.


Code example

//responseLogInfo:
//Called when logs have been downloaded from the card reader by using the logGetInfo method.
-(void)responseLogInfo:(id<LogInfo>)info
{
	NSLog(info.log);
	//write to log file
}

Objects

HeftManager

object Available since 2.2.2

HeftManager

The HeftManager is used for discovering devices and to connect and create a HeftClient object for the appropriate device. The manager reports messages to HeftDiscoveryDelegate protocol during the discovery process. Starting the manager is usually the first thing that should be done after loading up an UIView that enables the user to search for and connect to BT devices. When starting the manager an object (usually the UIViewController itself) is passed as the HeftDiscoveryDelegate delegate to report to.

Properties

Property Type Accessor Description
devicesCopy NSMutableArray get Stored array which contains all found devices.
delegate NSObject<HeftDiscoveryDelegate> get Key for value in mpedInfo
version NSString get Current HeftManager version.

Methods

startDiscovery
- (void)startDiscovery:(BOOL)fDiscoverAllDevices;
resetDevices
- (void)resetDevices;
sharedManager
+ (HeftManager*)sharedManager;
clientForDevice
- (void)clientForDevice:(HeftRemoteDevice*)device sharedSecret:(NSData*)sharedSecret delegate:(NSObject<HeftStatusReportDelegate>*)aDelegate;

Code example

// Create a manager on view load
- (void)viewDidLoad{
	[super viewDidLoad];
	HeftManager* manager = [HeftManager sharedManager];
	manager.delegate = self;
	[manager resetDevices]; // Clean out device list
}

HeftClient

object Available since 2.2.2

HeftClient

High level interface for Headstart API. HeftClient handles the communication between the mPos app and the card reader. The HeftClient object also stores information about it's card reader device in the mpedInfo dictionary. Device Log operations are also implemented in HeftClient. To create a new HeftClient object the clientForDevice method is called from an instance of the HeftManager. Transaction and log requests (and the acceptSignature response) are done by calling HeftClient methods with the relevant input. The library reports the status of the requests by calling delegates of the HeftStatusReportDelegate protocol.

Properties

Property Type Accessor Description
mpedInfo NSDictionary get Dictionary with MPED info details, obtained by querying it from device on interface creation.
kSerialNumberInfoKey NSString constant get Key for value in mpedInfo
kPublicKeyVersionInfoKey NSString Constant get Key for value in mpedInfo
kEMVParamVersionInfoKey NSString Constant get Key for value in mpedInfo
kGeneralParamInfoKey NSString Constant get Key for value in mpedInfo
kManufacturerCodeInfoKey NSString Constant get Key for value in mpedInfo
kModelCodeInfoKey NSString Constant get Key for value in mpedInfo
kAppNameInfoKey NSString Constant get Key for value in mpedInfo
kAppVersionInfoKey NSString Constant get Key for value in mpedInfo
kXMLDetailsInfoKey NSString Constant get Key for value in mpedInfo

Methods

saleWithAmount
- (BOOL)saleWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present;
refundWithAmount
- (BOOL)refundWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present;
saleVoidWithAmount
- (BOOL)saleVoidWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present transaction:(NSString*)transaction;
refundVoidWithAmount
(BOOL)refundVoidWithAmount:(NSInteger)amount currency:(NSString*)currency cardholder:(BOOL)present transaction:(NSString*)transaction;
enableScanner
-(BOOL)enableScanner;
financeInit
- (BOOL)financeInit;
logSetLevel
- (BOOL)logSetLevel:(eLogLevel)level;
logReset
- (BOOL)logReset;
logGetInfo
- (BOOL)logGetInfo;
acceptSignature
- (void)acceptSignature:(BOOL)flag;

Code example

//clientForDevice:sharedSecret:delegate:
//Creates a HeftClient object(connection to device)
-(void)connectToFirstCardReaderWith:(NSData*)sharedSecret;
{
	//Try to connect to first device in devices array
	[heftManager clientForDevice:[[heftManager devicesCopy] objectAtIndex:0] sharedSecret:sharedSecret delegate:self];
	//Client calls the didConnect delegate function if successful 
}

//....

//didConnect:
//Called when a connection to specified device was created.
-(void)didConnect:(id<HeftClient>)client 
{
	// connected successfully to a device
	// assigne the client to our heftClient property
	heftClient = client;
}

// .....

// Do one sale later in code
[heftClient saleWithAmount:1000 currency:@"GBP" cardholder:YES];

HeftRemoteDevice

object Available since 2.2.2

HeftRemoteDevice

An object containing a reference to the accessory device which is passed to the HeftClient on creation.

Properties

Property Type Accessor Description
name NSString get Name of device
accessory EAAccessory get The EAAccessory object

HeftDiscoveryDelegate

object Available since 2.2.2

HeftDiscoveryDelegate

Notifications sent by the SDK on various events - new available device found, connection lost, connection found, etc

Methods

didDiscoverFinished
- (void)didDiscoverFinished;
didFindAccessoryDevice
- (void)didFindAccessoryDevice:(HeftRemoteDevice*)newDevice;
didLostAccessoryDevice
- (void)didLostAccessoryDevice:(HeftRemoteDevice*)oldDevice;

HeftStatusReportDelegate

object Available since 2.2.2

HeftStatusReportDelegate

Notifications sent by the SDK on various events - connected to device, request signature, response on error etc.

Methods

didConnect
- (void)didConnect:(id<HeftClient>)client;
responseStatus
- (void)responseStatus:(id<ResponseInfo>)info;
responseScannerEvent
- (void)responseScannerEvent:(id<ScannerEventResponseInfo>)info;
responseEnableScanner
- (void)responseEnableScanner:(id<EnableScannerResponseInfo>)info;
responseError
- (void)responseError:(id<ResponseInfo>)info;
responseFinanceStatus
- (void)responseFinanceStatus:(id<FinanceResponseInfo>)info;
responseLogInfo
- (void)responseLogInfo:(id<LogInfo>)info;
requestSignature
- (void)requestSignature:(NSString*)receipt;
cancelSignature
- (void)cancelSignature;

responseInfo

object Available since 2.2.2

responseInfo

A responseInfo object is passed to the responseStatus delegate. It contains information from the card reader about the status of the current transaction. There are two properties: status and xml. status is a string and xml is a dictionary. Usually status contains a message descriptive enough to know whats going on and is useful for displaying to user. The xml dictionary contains all elements of the XML formatted data passed from the card reader and has detailed information on the current state of the card reader.

Properties

Property Type Accessor Description
statusCode int get A numerical representation of the status.
status Status as NSString get Financial transaction status message.
xml XML as NSDictionary get Feedback with xml details about transaction from the card reader.

FinanceResponseInfo

object Available since 2.2.2

FinanceResponseInfo

A FinanceResponseInfo is passed to the responseFinanceStatus delegate at the end of transaction. It contains all necessary information needed about the relevant transaction. FinanceResponseInfo inherits from ResponseInfo so it includes the status string and xml dictionary in addition to authorisedAmount, transactionId and the html formatted string customerReceipt.

Properties

Property Type Accessor Description
statusCode int get A numerical representation of the status.
status Status as NSString get Financial transaction status message.
xml XML as NSDictionary get Feedback with xml details about transaction from the card reader.
authorisedAmount NSInteger get In the smallest unit for the given CurrencyCode - for the transaction. ISO 4217 defines number of digits in fractional part of currency for every currency code. Example 1000 in the case where CurrencyCode is "0826" (GBP) the amount would be 10.00 pounds or 1000 pense.
transactionId NSString get The id of current transaction.
customerReceipt NSString get Customer receipt of transaction from MPED in html format.
merchantReceipt NSString get Merchant receipt of transaction from MPED in html format.

ScannerEventResponseInfo

object Available since 2.2.2

ScannerEventResponseInfo

A ScannerEventResponseInfo is passed to the responseScannerEvent delegate during scanner mode when a scan is detected. It contains all necessary information needed about the relevant operation. ScannerEventResponseInfo inherits from ResponseInfo so it includes the status string and xml dictionary in addition to scanCode string.

Properties

Property Type Accessor Description
statusCode int get A numerical representation of the status.
status Status as NSString get Financial transaction status message.
xml XML as NSDictionary get Feedback with xml details about transaction from the card reader.
scanCode NSString get The code that was scanned.

ScannerDisabledResponseInfo

object Available since 1.3.1

ScannerDisabledResponseInfo

The info object contains information about the scanner operation.

Properties

Property Type Accessor Description
statusCode int get A numerical representation of the status.
status Status as NSString get Financial transaction status message.
xml XML as NSDictionary get Feedback with xml details about transaction from the card reader.

LogInfo

object Available since 2.2.2

LogInfo

A LogInfo object is passed to the responseLogInfo delegate when logs have been downloaded from the card reader.

Properties

Property Type Accessor Description
statusCode int get A numerical representation of the status.
status Status as NSString get Financial transaction status message.
xml XML as NSDictionary get Feedback with xml details about transaction from the card reader.
log NSString get String containing the logging information.

eLogLevel

enum Available since 2.2.2

eLogLevel

An enum describing the different levels of logging used in the hapi and used in the device.

Possible values

eLogNone eLogInfo eLogFull eLogDebug

Transaction Details

object Available since 2.2.2

XML as NSDictionary

The contents of the xml property depend on which type of operation the card reader is responding to. Listed below are all possible keys in the dictionary. Note that not all fields are included all the time.

Dictionary keys:

StatusMessage
A human readable description for the returned Status.
TransactionType
The type of transaction performed: UNDEFINED, SALE, VOID_SALE, REFUND, VOID_REFUND, CANCEL_SALE, CANCEL_REFUND
FinancialStatus
The result of the transaction: UNDEFINED, APPROVED, DECLINED, PROCESSED, FAILED, CANCELLED
RequestedAmount
The amount requested by the POS, as requested by the POS (i.e. no decimal point).
GratuityAmount
The gratuity amount entered by the cardholder, if any.
GratuityPercentage
The gratuity amount, as a percentage of the requested amount.
TotalAmount
The total of the gratuity and requested amount.
Currency
The currency code used for the transaction.
TransactionID
The transaction number used for this transaction, as maintained by the Eft Client.
EFTTransactionID
The EFT reference, given by the system, to make the transaction unique.
OriginalEFTTransactionID
The original EFT reference, given by the POS, as part of a VOID_SALE or a VOID_REFUND transaction.
EFTTimestamp
The date and time of the transaction, in ISO format (YYYYMMDDHHmmSS).
AuthorisationCode
The transaction authorization code, as given by the system.
CVM
The Cardholder Verfication Method: UNDEFINED, SIGNATURE, PIN, PIN_SIGNATURE, FAILED, NOT_REQUIRED
CardEntryType
The card data acquisition type: UNDEFINED, MSR, ICC, CNP
CardSchemeName
The card, reported, scheme name.
CardTypeId
The ID of the Card Type.
SerialNumber
The serial number of the PED.
BatteryStatus
A number, followed by the % sign, which indicates current charge level of the battery.
BatterymV
An integer, which represent the batter charge, in mV.
BatteryCharging
Indicates whether the battery is charging, or not. Values are true or false.
ExternalPower
Indicates whether the PED is connected to an external power source (e.g. a AC adapter). Values are true or false.
ApplicationName
The name of the application running on the PED.
ApplicationVersion
A version string of the form major.minor.build”(e.g. 1.2.118).
ErrorMessage
Description of the error, if any.
code
Scanned code from the device in scanning mode.
RecoveredTransaction
Indicates that the transaction result is a recovered transaction. The key is only included if value is true.

Status strings

valuelist Available since 2.2.2

Status as NSString

An NSString containing the status message - can be one of the following:

Possible values

Success
Invalid data
Processing error
Not allowed
Not initialized
Connect timeout
Connect error
Sending error
Receiveing error
No data available
Transaction not allowed
Unsupported currency
No host available
Card reader error
Card reading failed
Invalid card
Input timeout
User cancelled
Invalid signature
Waiting card
Card inserted
Application selection
Application confirmation
Amount validation
PIN input
Manual card input
Waiting card removal
Tip input
Shared secret invalid
Connecting
Sending
Receiving
Disconnecting
PIN entry completed
Merchant cancelled the transaction
Request invalid
Card cancelled the transaction
Blocked card
Request for authorisation timed out
Request for payment timed out
Response to authorisation request timed out
Response to payment request timed out
Please insert card in chip reader
Remove the card from the reader
This device does not have a scanner
Scanner is not supported
Scanner event

Process details

The following table contains result codes that can occur in the COMMAND response STATUS field (see section 1.3 above).

In addition the following table contains the text information presented in the <StatusMessage> field that is part of the <FinancialTransactionResponse> Xml response object.

All values are in hex in the following table.

Status ID Value <StatusMessage> Details
EFT_SUCCESS 0001 One of the following: "" (an empty string) "AUTH CODE #" "REFUND ACCEPTED" "REVERSAL ACCEPTED" Operation completed successfully. No further actions required.
EFT_INVALID_DATA 0002 "Invalid data" Invalid COMMAND request object, from the POS App, at the start of an operation. Please retry the operation. If the issue persists please contact technical support and provide card reader logs.
EFT_PROCESSING_ERROR 0003 "Processing error" An unexpected error occurred during processing. Please retry the operation. If the issue persists please contact technical support and provide card reader logs.
EFT_COMMAND_NOT_ALLOWED 0004 "Command not allowed" The card reader is currently busy processing another command. Please retry the operation once the current operation has completed.
EFT_NOT_INITIALISED 0005 "Device is not initialized" The current operation can’t be completed because there is a pending software update that must be applied before processing can continue. Please retry the operation after the card reader has restarted itself.
EFT_CONNECT_TIMEOUT 0006 "Connection time out detected" The back end connection timed out during an update. Please retry the operation. If the issue persists please contact technical support and provide card reader logs.
EFT_CONNECT_ERROR 0007 "Connection error" It was not possible to establish a connection to the back end system during an update operation. Please retry the operation. If the issue persists please contact technical support and provide card reader logs.
EFT_SENDING_ERROR 0008 "Send error" A failure was detected during communication with the back end system. If a SALE or a REFUND transaction was in progress when this occurred then you MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges. Note: You may be asked to provide the card reader logs. Once verified please retry the operation.
EFT_RECEIVING_ERROR 0009 "Receiving error" A failure was detected during communication with the back end system. If a SALE or a REFUND transaction was in progress when this occurred then you MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges. Note: You may be asked to provide the card reader logs. Once verified please retry the operation.
EFT_NO_DATA_AVAILABLE 000A "No data available" The POS App is trying to fetch the card reader log file but there is no data stored in the log file. If logs are required then please set the log level to an appropriate value and retry the operation.
EFT_TRANS_NOT_ALLOWED 000B "Transaction not allowed" <Currently not used>
EFT_UNSUPPORTED_CURRENCY 000C "Currency not supported" A currency has been selected that the card reader has not been configured for. Please select the correct currency and retry the operation. Alternatively, please contact technical support and ask for the specific currency to be supported.
EFT_NO_HOST_AVAILABLE 000D "No host configuration found" An update was initiated but the card reader could not find any host information for the back end system, even though it otherwise contains valid configuration. This is indicative of an invalid <hostBlock> block with in the <HostList> block in this device configuration, which was placed on the card reader during a previous update. Please contact technical support and provide card reader logs and ask for a replacement device. The card reader will be unable to update itself and must be replaced.
EFT_CARD_READER_ERROR 000E "Card reader error" Error detected in the chip reader or the magnetic stripe reader. Please retry the operation. If the issue persists please contact technical support and provide them with the card reader logs as well as asking for a replacement reader.
EFT_CARD_READING_FAILED 000F "Failed to read card data" The card reader could not read any data from the card. Please retry the operation. If the issue persists the card may be faulty, please try another card. If the issue still persists the card reader may require replacement, please contact technical support.
EFT_INVALID_CARD 0010 "INVALID CARD" The card reader detected invalid card data. Please retry the operation. If the issue persists the card may be faulty, please try another card. If the issue still persists the card reader may require replacement, please contact technical support.
EFT_INPUT_TIMEOUT 0011 "Timeout waiting for user input" The card reader timed out while waiting for a user action. No further actions required.
EFT_USER_CANCELLED 0012 "TRANSACTION VOID" "User cancelled the transaction" The current operation was cancelled by card holder. No further actions required.
EFT_SHARED_SECRET_INVALID 001D "Shared Secret invalid" The card reader believes that the POS App has an incorrect shared secret. No financial operations will be possible (e.g. SALE, REFUND). Please type the correct shared secret into the POS App or contact technical support for further assistance.
EFT_SHARED_SECRET_AUTH 001E "Authenticating POS" The card reader is about to challenge the POS App for a correct shared secret. No further actions are required.
  REPORT STATUS SPECIFIC
EFT_INVALID_SIGNATURE 0013 "TRANSACTION VOID" The merchant indicated that the signature provided by the card holder was invalid. No further actions are required.
EFT_WAITING_CARD 0014 "Waiting for card" The card reader is waiting for a card to be inserted into the chip reader or for a card to be swiped (only applies to card readers with external MSR). Insert or swipe a card to continue with the transaction.
EFT_CARD_INSERTED 0015 "Card detected" <Currently not used>
EFT_APPLICATION_SELECTION 0016 "Waiting for application selection" The card reader is waiting for the card holder to select a card application to be used for the transaction. The card holder must select an application for use (e.g. VISA, MASTERCARD, etc.) and should then press either the OK button to continue. Press the C/Cancel button to abort the transaction.
EFT_APPLICATION_CONFIRMATION 0017 "Waiting for application confirmation" The card reader is waiting for the card holder to confirm that the displayed card application should be used for the transaction. The card holder should press either the OK or the C/Cancel button.
EFT_AMOUNT_VALIDATION 0018 "Waiting for amount validation" The card reader is waiting for the card holder to confirm that the amount presented is correct. The card holder should press either the OK or the C/Cancel button.
EFT_PIN_INPUT 0019 "Waiting for PIN entry" The card reader is waiting for the card holder to enter his/her PIN. The card holder should enter his PIN and then press the OK button to continue. For PIN bypass press the OK button without entering any PIN digits (this will trigger signature fallback). Press the C/Cancel button to abort the transaction. Note: It is not possible to cancel this operation from the POS App.
EFT_MANUAL_CARD_INPUT 001A "Waiting for manual card data" <Currently not used>
EFT_WAITING_CARD_REMOVAL 001B "Waiting for card removal" A card was detected in the card reader at the start of a transaction, presumably left there from a previous transaction. Please remove the card and restart the operation.
EFT_TIP_INPUT 001C "Waiting for gratuity" The card reader is waiting for the card holder to enter/confirm tip/gratuity information.
EFT_WAITING_SIGNATURE 001F "Waiting for signature" The card reader is waiting for confirmation from the merchant that the card holder signature is valid. The merchant should press either the Accepted or Declined/Cancel in the POS App. Pressing Cancel or OK on the card reader will not have any effect.
EFT_WAITING_HOST_CONNECT 0020 "Connecting to host" The card reader is establishing a connection to the back end system. No further actions are required.
EFT_WAITING_HOST_SEND 0021 "Sending data to host" The card reader is sending data to the back end system. No further actions are required.
EFT_WAITING_HOST_RECEIVE 0022 "Waiting for data from host" The card reader is waiting for data from to the back end system. No further actions are required.
EFT_WAITING_HOST_DISCONNECT 0023 "Disconnecting from host" The card reader is disconnecting from the back end system. No further actions are required.
EFT_PIN_INPUT_COMPLETED 0024 "PIN entry completed" PIN entry has been completed. No further actions required.
EFT_POS_CANCELLED 0025 "TRANSACTION VOID" The current operation was cancelled by merchant. No further actions required.
EFT_REQUEST_INVALID 0026 "Request invalid" Card not allowed with this transaction type.
EFT_CARD_CANCELLED 0027 "TRANSACTION VOID" The chip on the card cancelled the transaction. No further actions required.
EFT_CARD_BLOCKED 0028 "CARD BLOCKED" The card used in the transaction is blocked. Please retry the transaction with a non-blocked card.
EFT_REQUEST_AUTH_TIMEOUT 0029 "Request for authorisation timed out" Indicates that the card reader detected a communication failure between itself and the back end system during the authorization phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support. Note: You may be asked to provide the card reader logs.
EFT_REQUEST_PAYMENT_TIMEOUT 002A "Request for payment timed out" Indicates that the card reader detected a communication failure between itself and the back end system during the payments phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support. Note: You may be asked to provide the card reader logs.
EFT_RESPONSE_AUTH_TIMEOUT 002B "Response to authorisation request timed out" Indicates that the card reader detected a communication failure between itself and the back end system during the authorization phase. Please make sure the phone/pc has an internet connection and then retry the operation. If the problem persists then please contact technical support. Note: You may be asked to provide the card reader logs.
EFT_RESPONSE_PAYMENT_TIMEOUT 002C "Response to payment request timed out" Indicates that the card reader detected a communication failure between itself and the back end system during the payments phase. You MUST contact technical support and verify whether the transaction went through or not. If you fail to do so then you may be liable for any costs incurred due to any double charges.   Note: You may be asked to provide the card reader logs. Once you have verified that the transaction did not go through then please make sure the phone/pc has an internet connection and then retry the operation.
EFT_ICC_CARD_SWIPED 002D "Please insert card in chip reader" <Currently not used>
EFT_REMOVE_CARD 002E "Remove the card from the reader" <Currently not used>
EFT_SCANNER_IS_NOT_SUPPORTED 002F "This device does not have a scanner" Bar-code scanner hardware is not present on this card reader. No further actions are required.
EFT_SCANNER_EVENT 0030 "" Bar-code data was just read with the bar-code scanner and returned to the POS App. No further actions are required.
EFT_BATTERY_TOO_LOW 0031 "Operation cancelled, the battery is too low. Please charge." An operation was started, but the battery charge level is too low to complete the operation. Please recharge the card reader.
EFT_ACCOUNT_TYPE_SELECTION 0032 "Waiting for account type selection" The card reader is waiting for the card holder to choose an account type for the transaction (i.e. default, credit, cheque/debit or savings).