Middleware Library for iOS

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

The library supports iOS 9.0+.

Quick Start Example

Objective-C

// .h

PaymentEngineMiddlewareSettings *middlewareSetting;
PaymentEngineMiddleware *middleware;

// .m

 - (void)viewDidLoad
{
    [super viewDidLoad];

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

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

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

-(void)startTransaction
{

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

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

Swift


// .swift

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

override func viewDidLoad()
{
    super.viewDidLoad()

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

    middleware?.setDevice("castle", self)

}

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

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

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

}

func transactionComplete(_ transResponse: PaymentEngineTransactionResponse!)
{

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

}

PaymentEngineMiddleware Class

This is the main class that contains all the middleware interfaces.

PaymentEngineAPICom Class

This is the main class that contains all the interfaces to communicate with the API.

PaymentEngineMiddlewareSettings Class

This is the setting class, it's required at device initialization to set the transaction flow.

PaymentEngineMiddlewareSettings Class Merchant Capability

This is the setting class, these values gets returned from the gateway base on Merchant's Capability.

PaymentEngineReceiptInfo Class

Use this class to parse receipt info (Not supported by MP200).

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

PaymentEngineTransactionResponse Class

Use this class to parse transaction response from our gateway

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

PaymentEngineMiddlewareDelegate

Implement these delegate methods to receive callbacks from the middleware library.

PaymentEngineAPIDelegate

Implement these delegate methods to receive callbacks from PaymentEngineAPICom.

PaymentEngineResultQueue Class

Use this class to parse offline queued transaction response.

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

PaymentEngineAccessoryObject Class

Use this class to parse connected bluetooth devices.

  • deviceName - The name of the connected bluetooth device
  • serialNum - The serial number of connected bluetooth device
  • modelNum - The model number of connected bluetooth device
  • hardwareRevision - The hardware revision of connected bluetooth device
  • manufacturer - The manufacturer of connected bluetooth device

Change Log

v2.3.16 - 2019-02-27

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

v2.3.15 - 2018-11-28

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

v2.3.14 - 2018-10-02

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

v2.3.13 - 2018-08-27

  • Added in examples on how to use PaymentEngineAPICom

v2.3.12 - 2018-07-25

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

v2.3.11 - 2018-05-30

  • Fixed cardholder name issue coming back as Null

v2.3.10 - 2018-05-17

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

v2.3.9 - 2018-04-13

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

v2.3.8 - 2018-03-08

  • Added in fixes for display image when voiding transaction

v2.3.7 - 2018-12-20

  • Added in bitcode support that is required by xcode 9.0

v2.3.6 - 2017-07-07

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

v2.3.5 - 2017-06-08

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

v2.3.4 - 2017-05-11

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

v2.3.3 - 2017-04-10

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

v2.3.2 - 2017-03-23

  • Added in Swift demo app

v2.3.1 - 2017-01-23

  • Support for First Data Nashville and Tsys processing platforms