PaymentEngineMiddleware Class

cancelTransaction

-(void)cancelTransaction 

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

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

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

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

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);

}

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];

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.

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

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];

}