PaymentEngineMiddleware Class

cancelTransaction

-(void)cancelTransaction

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

printText

-(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

The following delegates may be returned:

-(void)printCompleted:(NSString *)msg
  • printCompleted() method will be called for all errors. It is called after all printText operations have been completed.

captureSignature

-(void)captureSignature:(NSMutableDictionary *)holdCaptureInfo

Parameters

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

holdCaptureInfo Fields

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.

Delegate Methods

The following delegates may be returned:

-(void)captureSignatureComplete :(PaymentEngineTransactionResponse *)transResponse
  • captureSignatureComplete() method will be called for all errors, declines or approvals. It is called after all captureSignature operations have been completed.

Example


/**
* 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

-(void)adjustTransaction:(NSMutableDictionary *)holdTransInfo

Parameters

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

holdTransInfo Fields

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.

Delegate Methods

The following delegates may be returned:

-(void)adjustTranstionComplete :(PaymentEngineTransactionResponse *)transResponse
  • adjustTranstionComplete() method will be called for all errors, declines or approvals. It is called after all adjustTransaction operations have been completed.

Example


/**
* 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];
}

connectDevice

-(void)connectDevice

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

disconnectDevice

-(void)disconnectDevice

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

getDeviceInfo (Deprecated in v2.3.5)

-(NSDictionary *)getDeviceInfo

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

-(void)readDeviceInfo

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

getReceipt

-(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

-(void)returnReceiptCompleted :(NSString *)receiptValue
  • receiptValue - An html string value that contains all the receipt information.

Example


-(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

-(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

-(void)returnReceiptCompleted :(NSString *)receiptValue
  • receiptValue - An html string value that contains all the receipt information.

Example


-(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

-(void)goOnline

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

goOffline

-(void)goOffline

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

isDeviceOnline

-(BOOL)isDeviceOnline

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

setDevice

-(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


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

connectBluetoothDevice

-(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


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

    if(connectedDevices > 0)
    {

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

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


}

getConnectedDevices

-(NSMutableArray *)getConnectedDevice

Returns a list of connected bluetooth devices.

startTransaction

-(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 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: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).

getMerchantCapabilities

-(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

The following delegates may be returned:

-(void)getMerchantCapabilitiesComplete: (NSDictionary *)merchantCapDict
  • getMerchantCapabilitiesComplete delegate method will be called for all errors. It is called after getMerchantCapabilities operations have been completed.

Example


/**
* 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
    */
    [EBizChargeMiddlewareClass getMerchantCapabilities:false];

}

displayImg

-(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


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

} DisplayImageType;

Example


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

}

setDeviceTimeout

-(void)setDeviceTimeout :(int)second

Parameters

Type Parameter Description
int second Timeout duration in seconds

Example


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

}

getDeviceTimeout

-(void)getDeviceTimeout

Delegate Methods

The following delegates may be returned:

-(void)getDeviceTimeoutCompleted :(int) seconds

Example


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

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

retrieveQueuedTrans

-(NSMutableArray *)retrieveQueuedTrans

Returns a list of offline queued transactions.

Example


/**
* 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([EBizChargeMiddlewareClass retrieveQueuedTrans].count > 0)
    {
        for(int i = 0; i < [EBizChargeMiddlewareClass retrieveQueuedTrans].count; i++)
        {
            PaymentEngineResultQueue *resultQueue = (PaymentEngineResultQueue *)[[EBizChargeMiddlewareClass 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

 -(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

The following optional delegates may be called:

-(void)runQueuedTransCompleted :(PaymentEngineTransactionResponse *)transResponse

Example


/**
  * 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 transacitons
    */
    [EBizChargeMiddlewareClass runQueuedTrans:@""];
}

removeQueuedTrans

 -(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

The following optional delegates may be called:

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

Example


/**
  * 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
    */
    [EBizChargeMiddlewareClass removeQueuedTrans:@""];
}

updateQueuedTrans

-(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

The following optional delegates may be called:

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

Example


-(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@EBizCharge.com" forKey:@"email"];


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

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

        [EBizChargeMiddlewareClass updateQueuedTrans:updateQueuedDict :resultQueue.identifier];

    }
}

/ 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([EBizChargeMiddlewareClass retrieveQueuedTrans].count > 0)
{
    for(int i = 0; i < [EBizChargeMiddlewareClass retrieveQueuedTrans].count; i++)
    {
        PaymentEngineResultQueue *resultQueue = (PaymentEngineResultQueue *)[[EBizChargeMiddlewareClass 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

```c
 -(void)runQueuedTrans: (NSString *)identifier

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

Optional Delegate Method

The following optional delegates may be called:

-(void)runQueuedTransCompleted :(PaymentEngineTransactionResponse *)transResponse

Example


/**
  * 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 transacitons
    */
    [EBizChargeMiddlewareClass runQueuedTrans:@""];
}

removeQueuedTrans

 -(void)removeQueuedTrans: (NSString *)identifier

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

Optional Delegate Method

The following optional delegates may be called:

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

Example


/**
  * 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
    */
    [EBizChargeMiddlewareClass removeQueuedTrans:@""];
}