Middleware Library for iOS

The PaymentEngine Middleware library allow developers to process EMV, contactless and swiped transactions on the USAePay 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 8.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"];

    [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 UsaepayMiddleware 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.

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).
  • cvmResult - The CVM (card verification method) result of the transaction.
  • transactionType - The transaction type such as NFC, Swipe, Insert, fallback, or Manually

PaymentEngineMiddlewareDelegate

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

Change Log

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
 

For inquiries contact us at (720) 277-0648