USAePay Middleware for iOS

The usaepayMiddleware Library allows developers to process EMV, contactless and swiped transactions on the USAePay gateway. The library handles all communication with the hardware and gateway, allowing developers to create rich mobile payment applications without the hassle and expense of EMV certification.

The library supports iOS 8.0+.

Current Version: 1.0.14

Device Support

Currently, the library supports the Ingenico ICMP mobile reader. This reader supports traditional MSR card swipe, NFC, EMV Chip & Pin and Pin Debit. The device can be ordered with the USAePay encryption key injected for end to end encryption.

Additional hardware support is coming soon. If you are looking for a different reader, please contact your sales representative.

How To Get Started

Download usaepayMiddleware. It contains one example project, documentation and the Library itself.

Read theGetting start guide to learn how to add the library into your project.

Once you added the library into the project, use this code snippet to help you get started.

#import "ViewController.h"
@implementation ViewController
- (void)viewDidLoad {
    [super viewDidLoad];
    middlewareSettings = [MiddlewareSettings sharedManager];
     * For production processing comment this line out
    [middlewareSettings setMode:@"sandbox"];
    middlewareSettings.sourceKey = @"Put your source key here";
    middlewareSettings.pinNum = @"Put your pin here";
     * Use to disable or enable the tips
     * Set it to true will enable tip prompt from the device
    middlewareSettings.isTipEnable = true;
    usaepayMiddlewareClass = [usaepayMiddleware getInstance];
    usaepayMiddlewareClass.delegate = self;
    [usaepayMiddlewareClass setDevice:@"icmp" :self];
    UIButton *startCardReadBtn = [UIButton buttonWithType:UIButtonTypeRoundedRect];
    startCardReadBtn.frame = CGRectMake(100, 200, 100, 60);
    [startCardReadBtn setTitle:@"Start Reading Card" forState:UIControlStateNormal];
    [startCardReadBtn addTarget:self action:@selector(startCardReadEvent) forControlEvents:UIControlEventTouchDown];
    NSMutableDictionary *transDict = [NSMutableDictionary new];
    //Setting the amount to $40.00
    [transDict setObject:@"40.00" forKey:@"amount"];
    [transDict setObject:@"cc:sale" forKey:@"command"];
    [transDict setObject:@"2.55" forKey:@"taxAmount"];
    [usaepayMiddlewareClass startTransaction:transDict];
 * This is a call back method
 * It will get call once the transaction is passed to the gateway and returns a response
-(void)transactionComplete :(usaepayTransactionResponse *)transResponse
    UIAlertView *displayTransRespondAlert = [[UIAlertView alloc]initWithTitle:@"Transaction Status" message:[NSString stringWithFormat:@"%@", transResponse.Result] delegate:self cancelButtonTitle:@"Ok" otherButtonTitles:nil, nil];
    [displayTransRespondAlert show];

Processing Commands

The transaction API is typically used to process credit card sales but it can also accept many other transaction types by changing the command variable. The following section describes the different commands that are available and the data required for each.

Command Alternate/Legacy Equivalents Pin Required
cc:sale sale

cc:sale - Credit Card Sale


The 'cc:sale' command is the default processing command. If the command is left blank or omitted, the system will use 'cc:sale'. The 'cc:sale' command runs a standard credit card sale. It will charge (debit) the customer's credit card for the amount specified. 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.


Field Description
Status Status of the transaction. The possible values are: Approved, Partially Approved, Declined, Verification and Error.
AuthCode Authorization number.
authAmount Amount authorized. May be less than amount requested if enablePartialAuth=yes
RefNum Transaction reference number
BatchRefNum Batch reference number. This will only be returned for sale and auth commands. Warning: The batch number returned is for the batch that was open when the transaction was initiated. It is possible that the batch was closed while the transaction was processing. In this case the transaction will get queued for the next batch to open.
RemainBalance Returns the balance remaining on some prepaid and stored value cards
AvsResult AVS result in readable format
AvsResultCode AVS result code.
Result Transaction result - A, P, D, E, or V (for Verification)
Error Error description if status is Declined or Error.
ErrorCode A numerical error code.
isDuplicate Indicates whether this transaction is a folded duplicate or not. 'Y' means that this transaction was flagged as duplicate and has already been processed. The details returned are from the original transaction. Send ignoreDuplicate to override the duplicate folding.
ConvertedAmount Amount converted to merchant's currency, when using a multi-currency processor.
ConvertedAmountCurrency Merchant's currency, when using a multi-currency processor.
ConversionRate Conversion rate used to convert currency, when using a multi-currency processor.
iccData Holds the ICC data tags returned from the gateway.
developer/middleware/ios.txt · Last modified: 2015/12/14 14:34 by jlei

Page Tools