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 = [usaepayMiddlewareClass getConnectedDevices];
if(connectedDevices > 0)
{
PaymentEngineAccessoryObject *accessoryObject = (PaymentEngineAccessoryObject *)[[usaepayMiddlewareClass getConnectedDevices] objectAtIndex:0];
//Connects to first available bluetooth device
[usaepayMiddlewareClass 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 |
| 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
*/
[usaepayMiddlewareClass 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
*/
[usaepayMiddlewareClass 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
*/
[usaepayMiddlewareClass setDeviceTimeout:11];
}
getDeviceTimeout
-(void)getDeviceTimeout
Delegate Methods
The following delegates may be returned:
-(void)getDeviceTimeoutCompleted :(int) seconds
- getDeviceTimeoutCompleted delegate method will be called after getDeviceTimeout operations have been completed.
Example
/**
* 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
-(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([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
-(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
- runQueuedTransCompleted delegate method will be called after runQueuedTrans operations have been completed.
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
*/
[usaepayMiddlewareClass 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
- removeQueuedTransCompleted delegate method will be called after removeQueuedTrans operations have been completed.
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
*/
[usaepayMiddlewareClass 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
- updateQueuedTransCompleted delegate method will be called after updateQueuedTrans operations have been completed.
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@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];
}
}
/ 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
```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
- runQueuedTransCompleted delegate method will be called after runQueuedTrans operations have been completed.
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
*/
[usaepayMiddlewareClass 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
- removeQueuedTransCompleted delegate method will be called after removeQueuedTrans operations have been completed.
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
*/
[usaepayMiddlewareClass removeQueuedTrans:@""];
}