Integrating ElavonPay

Integrating ElavonPay SDK into an iOS Application

Setting up your xCode project to use ElavonPay SDK

  1. There is one framework you need set your application to use: ElavonPay.framework. Any time you copy the framework from one location to another you need to use

cp -a [original location] [destination location]

as the -a maintains the symbolic links in the framework. Copy the framework into a folder under your application project location. You can name this folder frameworks if you want.

  1. Click on your project file in the project navigator.

    Click on the project name under Project.

    Click on your target under Targets.

    Click on the General tab.

    Find Embedded Binaries and click on the +.

    In the dialog click the Add Other … button. Locate the ElavonPay.framework in the folder you copied it to in step 1. Click OK.

    Click Finish on next dialog. xCode will automatically add ElavonPay to your linked Frameworks and a path into your framework search path.

  2. Under Build Settings tab, you can set Enable Bitcode to your preference as ElavonPay.framework has bitcode enabled.

  3. Under Target click on your target name.

    Click on General tab. Under Linked Binaries and Frameworks, you should already have ElavonPay.framework and PassKit.framework from enabling the capability. Click the +. In the dialog, you will need to add Security.framework.

  4. For iOS 9.2, Apple added some Transport Security Requirements. In order to connect to the converge servers we need to override one of the requirements. You need to edit your PLIST file. Press Control and click on your PLIST file in the Sample App folder. Select Open with… and open the PLIST file with TextEdit.

    You will need to add the following “NSAppTransportSecurity” key to the file under the main <dict> tag:

         `<key</code>>NSAppTransportSecurity</key>
    

    NSExceptionDomains demo.myvirtualmerchant.com NSExceptionRequiresForwardSecrecy NSIncludesSubdomain demo.myvirtualmerchant.com NSExceptionRequiresForwardSecrecy NSIncludesSubdomains `

  5. As a security precaution, you should not allow custom keyboards to prevent keys from being recorded. To disallow custom keyboards, you should add the following to your implementation in the UIApplicationDelegate:

    - (BOOL)application: (UIApplication *)application shouldAllowExtensionPointIdentifier:(NSString *)extensionPointIdentifier { // Disable custom keyboards on iOS8 return NO; }

  6. If you are saving any secure data, you need to have the data protection entitlement on for your app and save your data in the keychain. Click on the target for your app in xCode and then select the Capabilities tab. Look for Data Protection and turn the setting on.

  7. Press Command + B to make sure you can build.

Initializing and using ElavonPay SDK

Prior to accepting payments and taking full advantage of Commerce functionality, a few steps should must be performed and items considered when coding.

  1. Initialize ElavonPay Framework

    The code to initialize may look like the following:

    #import <ElavonPay/ElavonPay.h> // This header includes all needed headers (umbrella header)
    // Initialize ElavonPay Framework
    NSError *error = [EPYElavonPay initializeElavonPay];
    if (error != nil) {
        return error;  // Ensure no errors when initializing ElavonPay Framework
    }
  1. Implement a PKPaymentAuthorizationViewControllerDelegate Delegate and a Sale Transaction method

    The code to initialize may look like the following:

	// In your header:
    #import <Passkit/Passkit.h>
    @interface TransactionProcessor : NSObject <PKPaymentAuthorizationViewControllerDelegate>
      - (void)startSaleTransaction:(UIViewController *)viewController;
    @end

    // In your m file:
    #import "TransactionProcessor.h"
    #import <ElavonPay/ElavonPay.h>

    @implementation TransactionProcessor {
        UIViewController *myViewController;
    }

    // Lets start a sale transaction.
    - (void)startSaleTransaction:(UIViewController *)viewController {
        myViewController = viewController;
    // Create an apple payment request. ElavonPay will create the request with the merchant id passed, country code passed in, currency
    // code passed in, and will fill in the defaults  (supportedNetworks to AMEX for Canada and Amex, MasterCard, Visa, and Discover for
    // US, requiredBillingAddressFields set to none, requiredShippingAddressFields set to none, merchantCapabilities to 
    // PKMerchantCapability3DS). You can change the fields of PKPaymentRequest except merchantCapabilities and do not add more
    // supportedNetworks.
    // Change the string to your US apple merchant ID
        PKPaymentRequest *request = [EPYElavonPay createApplePayPaymentRequest:@"myUSMerchantAppleID" countryCode:@"US" currencyCode:@"USD"];

    // Check to see if payment with these fields is possible. This will call [PKPaymentAuthorizationViewController canMakePayments] and
    //  [PKPaymentAuthorizationViewController canMakePaymentsUsingNetworks:paymentRequest.supportedNetworks]. 
    // Look at log if failure.
        if ([EPYElavonPay canMakeApplePayPaymentsUsingRequest:request] == NO) {
            NSLog(@"Cannot make payments");
            return;
        }

    // Need to have at least one item in the request so lets add an item that cost a penny    
        PKPaymentSummaryItem *lineItem1 = [PKPaymentSummaryItem summaryItemWithLabel:@"Penny Item" amount:[NSDecimalNumber decimalNumberWithString:@"0.01"]];
        [request setPaymentSummaryItems:@[lineItem1]];

    // This will tell create the Apple Pay ViewController to show the user what they are buying and lets them approve it
        PKPaymentAuthorizationViewController *authVC = [[PKPaymentAuthorizationViewController alloc] initWithPaymentRequest:request];
        if (authVC == nil) {
    // Look at the log to see the problem
            NSLog(@"Cannot show VC");
            return;
        }
        authVC.delegate = self; // Set the delegate to ourself.
    // Show the view controller
        [myViewController presentViewController:authVC animated:YES completion:nil];
    }

    // 2 PKPaymentAuthorizationViewControllerDelegate required methods (See Passkit.h for more information). There are optional methods you can implement to have more control. See sample app for more extension code.
    - (void)paymentAuthorizationViewController:(PKPaymentAuthorizationViewController *)controller
                           didAuthorizePayment:(PKPayment *)payment
                                    completion:(void (^)(PKPaymentAuthorizationStatus status))completion {
    // Create credentials to use with the request using your Converge Merchant Id. Change the string to your Converge merchant id.
        EPYCredentials *credentials = [EPYElavonPay createCredentials:@"convergeMerchantID"];
    // The credentials default to the production server. To go to demo server do “credentials.productionServer = NO;”

    //  Tell ElavonPay to do a sale transaction using the credentials and payment and to call the code block passed in when completed.
        NSError *error = [EPYElavonPay processApplePaySaleTransaction:credentials payment:payment callWhenComplete:^(NSError *error, EPYTransactionOutcome *outcome) {
    // Transaction completed so see if there was an error and if not what the result was
            if (error == nil) {
                NSLog(@"transaction processed: Result(%@), ID(%@)", [EPYTransactionResultHelper transactionResultToDebugString:outcome.result] , outcome.elavonTransactionIdentifier);
            } else {
                NSLog(@"transaction failed to be processed: %@", [error debugDescription]);
            }
        }];
        if (error != nil) {
    // failed to start the sale. log the reason
            NSLog(@"transaction failed to be started: %@", [error debugDescription]);
        }
    }

    - (void)paymentAuthorizationViewControllerDidFinish:(PKPaymentAuthorizationViewController *)controller {
    // This happens any time the view controller wants to go away (authorized, canceled, etc)
        [myViewController dismissViewControllerAnimated:YES completion:nil];
    }
    @end

  1. Now you have everything to process the transaction.

    	#import <ElavonPay/ElavonPay.h> // This header includes all needed headers (umbrella header)
    #import "TransactionProcessor.h"
    
    // Your source file
    NSError *error = [EPYElavonPay initializeElavonPay];
    if (error != nil) {
        return error; // Ensure no errors when initializing ElavonPay Framework
    }
    TransactionProcessor *transactionProcessor = [[TransactionProcessor alloc] init];
    [transactionProcessor startSaleTransaction];