Integrate the PayButton

Install

Put this in your Podfile and then run pod install:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://bitbucket.org/mpymnt/io.mpymnt.repo.pods.git'

target :"<your-app-target>" do
    pod 'payworks',           '2.24.1'
    pod 'payworks.paybutton', '2.24.1'
end

For bluetooth devices like Miura readers , to connect as an external accessory and be able to receive messages while the app is in the background, add additional entries to your Info.plist

  • Key: Supported external accessory protocols (UISupportedExternalAccessoryProtocols), value: com.miura.shuttle (for Miura readers)
  • Key: Required background modes (UIBackgroundModes), value: App communicates with an accessory (external-accessory)

Then, import the header in your view controller:

#import <mpos-ui/mpos-ui.h>

Perform a payment

This is how you start a payment in mock mode:

- (IBAction)paymentButtonClicked:(id)sender {
    MPUMposUi *ui = [MPUMposUi initializeWithProviderMode:MPProviderModeMOCK
                                       merchantIdentifier:@"merchantIdentifier"
                                           merchantSecret:@"merchantSecretKey"];
    
    
    // Start with a mocked card reader:
    MPAccessoryParameters *ap = [MPAccessoryParameters mockAccessoryParameters];

    // When using the Bluetooth Miura, use the following parameters:
    // MPAccessoryParameters *ap = [MPAccessoryParameters externalAccessoryParametersWithFamily:MPAccessoryFamilyMiuraMPI
    //                                                                                 protocol:@"com.miura.shuttle"
    //                                                                                optionals:nil];


    
    MPTransactionParameters *tp = [MPTransactionParameters chargeWithAmount:[NSDecimalNumber decimalNumberWithString:@"5.00"]
                                                                   currency:MPCurrencyEUR
                                                                  optionals:^(id<MPTransactionParametersOptionals>  _Nonnull optionals) {
                                                                      optionals.subject = @"Bouquet of Flowers";
                                                                      optionals.customIdentifier = @"yourReferenceForTheTransaction";
                                                                  }];
    
    ui.configuration.terminalParameters = ap;
    ui.configuration.summaryFeatures = MPUMposUiConfigurationSummaryFeatureSendReceiptViaEmail;

    // Add this if you would like to collect the customer signature on a printed merchant receipt
    //ui.configuration.signatureCapture = MPUMposUiConfigurationSignatureCaptureOnReceipt;
    
    
    UIViewController *viewController = [ui createTransactionViewControllerWithTransactionParameters:tp
                                                                                          completed:^(UIViewController * _Nonnull controller, MPUTransactionResult result, MPTransaction * _Nullable transaction)
                                        {
                                            [self dismissViewControllerAnimated:YES completion:NULL];
                                            
                                            UIAlertView* alert = [[UIAlertView alloc] initWithTitle:@"Result"
                                                                                            message:@""
                                                                                           delegate:nil
                                                                                  cancelButtonTitle:nil
                                                                                  otherButtonTitles:@"OK",nil];
                                            
                                            if (result == MPUTransactionResultApproved) {
                                                alert.message = @"Payment was approved!";
                                            } else {
                                                alert.message = @"Payment was declined/aborted!";
                                            }
                                            
                                            [alert show];
                                        }];
    
    
    UINavigationController *modalNav = [[UINavigationController alloc] initWithRootViewController:viewController];
    modalNav.navigationBar.barStyle = UIBarStyleBlack;
    if (UI_USER_INTERFACE_IDIOM() == UIUserInterfaceIdiomPhone) {
        modalNav.modalPresentationStyle = UIModalPresentationFullScreen;
    } else { // Show as Form on iPad
        modalNav.modalPresentationStyle = UIModalPresentationFormSheet;
    }
    [self presentViewController:modalNav animated:YES completion:NULL];
}

More information on the completed transaction statuses and what they mean can be found here.

Use a real card reader

To test with a real card reader, order the Developer Kit. You can find more information about our Developer Kits here.

You can then retrieve your merchantIdentifier and merchantSecretKey through the Gateway Manager and change the providerMode to MPProviderModeTEST.

Then create the  accessoryParameters with the reader family and connection you want to use.

For more information about the accessory and transaction parameters see the SDK Integration documentation.

Load merchant data from your backend

Right now, you have hardcoded the merchantIdentifier and merchantSecretKey. This means that all payments would be routed to the same merchant.

For a live solution, you might want to support multiple merchants, e.g. two different restaurants, to route the payment correctly. To support multiple merchants, store the following data on your backend:

  1. merchantIdentifier and merchantSecretKey. They identify to which merchant the payment is routed. You can create new merchants and get their credentials in the Gateway Manager.

  2. Whether the merchant is a TEST or LIVE merchant.

  3. The reader model the merchant uses.

You can then fetch this data before a transaction and configure the Pay Button correctly:

MPUMposUI *ui = 
    [MPUMposUI
        initializeWithProviderMode:<TEST or LIVE, loaded from your backend>
                merchantIdentifier:<MerchantIdentifier loaded from your backend>
                    merchantSecret:<MerchantSecretKey loaded from your backend>];

Customize the PayButton

UI customization: change the colors

12

You can choose the following colors:

  1. navigationBarTint: The navigation bar's tint
  2. navigationBarTextColor: The color of the text in the navigation bar
ui.configuration.appearance.navigationBarTint = [UIColor colorWithRed:0.61 green:0.15 blue:0.69 alpha:1];
ui.configuration.appearance.navigationBarTextColor = [UIColor whiteColor];

Receipt customization

You are required to offer an email or printed payment receipt to the shopper. The PayButton therefore allows the merchant to send an email payment receipt right after a transaction.

You might want to prevent this behavior, e.g. if you send your own receipts already and just want to append the required payment data. You can disable the built-in email receipts by removing MPUMposUiConfigurationSummaryFeatureSendReceiptViaEmail from the summaryFeatures options.

You can either programmatically send the same receipt that the PayButton would send, or send a custom or printed one. For custom and printed receipts, you are required to display specific data. See this page for details.

Install

The PayButton requires minSdkVersion 16 and compileSdkVersion 25.

  • Add our repository to your project's build.gradle:
allprojects {
    repositories {
        jcenter()
        maven {
            url "http://releases.payworks.io/artifactory/mpos"
        }
    }
}
  • Add the following exclusion rules to your module's build.gradle (inside the android section):
packagingOptions {
    exclude 'META-INF/DEPENDENCIES.txt'
    exclude 'META-INF/LICENSE.txt'
    exclude 'META-INF/NOTICE.txt'
    exclude 'META-INF/DEPENDENCIES'
    exclude 'META-INF/LICENSE'
    exclude 'META-INF/NOTICE'
    exclude 'LICENSE.txt'
    exclude 'asm-license.txt'
    exclude 'META-INF/ASL2.0'
}
  • Add the libraries to the dependencies section of your module's build.gradle:
dependencies {
    compile 'com.android.support:appcompat-v7:25.3.1'
    compile 'com.android.support:support-v4:25.3.1'
    compile 'com.android.support:cardview-v7:25.3.1'
    compile 'com.google.android.gms:play-services-vision:10.2.1'

    compile 'com.squareup:otto:1.3.5'
    compile 'com.squareup.okhttp:okhttp:2.7.4'
    compile 'com.squareup.okhttp:okhttp-ws:2.7.4'
    compile 'com.parse.bolts:bolts-android:1.2.1'
    compile 'com.fasterxml.jackson.core:jackson-databind:2.4.4'
    compile 'com.couchbase.lite:couchbase-lite-android:1.4.0'
    compile 'com.couchbase.lite:couchbase-lite-android-forestdb:1.4.0'

    compile 'io.payworks:mpos.android.ui:2.25.2:@aar'
    compile 'io.payworks:mpos.android.core:2.25.2:@aar'


    // Add those three dependencies if you want to use a Miura card reader
    compile 'io.payworks:mpos.android.accessories.miura:2.25.2:@aar'
    compile 'io.payworks:mpos.android.comlinks.bluetooth:2.25.2:@aar'
    compile 'io.payworks:mpos.android.comlinks.tcp:2.25.2:@aar'

}

If you wish to use ProGuard with your application make sure to add the necessary rules to your ProGuard configuration.

Peform a payment

This is how you start a payment in mock mode:

void paymentButtonClicked() {
    MposUi ui = MposUi.initialize(this, ProviderMode.MOCK,
            "merchantIdentifier", "merchantSecretKey");

    ui.getConfiguration().setSummaryFeatures(EnumSet.of(
            // Add this line, if you do want to offer printed receipts
            // MposUiConfiguration.SummaryFeature.PRINT_RECEIPT,
            MposUiConfiguration.SummaryFeature.SEND_RECEIPT_VIA_EMAIL)
    );

    // Start with a mocked card reader:
    AccessoryParameters accessoryParameters = new AccessoryParameters.Builder(AccessoryFamily.MOCK)
                                                            .mocked()
                                                            .build();
    ui.getConfiguration().setTerminalParameters(accessoryParameters);

    // Add this line if you would like to collect the customer signature on the receipt (as opposed to the digital signature)
    // ui.getConfiguration().setSignatureCapture(MposUiConfiguration.SignatureCapture.ON_RECEIPT);


    /* When using the Bluetooth Miura, use the following parameters:
    AccessoryParameters accessoryParameters = new AccessoryParameters.Builder(AccessoryFamily.MIURA_MPI)
                                                                     .bluetooth()
                                                                     .build();
    ui.getConfiguration().setTerminalParameters(accessoryParameters);
    */





    TransactionParameters transactionParameters = new TransactionParameters.Builder()
                                                            .charge(new BigDecimal("5.00"), io.mpos.transactions.Currency.EUR)
                                                            .subject("Bouquet of Flowers")
                                                            .customIdentifier("yourReferenceForTheTransaction")
                                                            .build();

    Intent intent = ui.createTransactionIntent(transactionParameters);
    startActivityForResult(intent, MposUi.REQUEST_CODE_PAYMENT);
}

The result is then delivered to your activity:

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {

    if (requestCode == MposUi.REQUEST_CODE_PAYMENT) {
        if (resultCode == MposUi.RESULT_CODE_APPROVED) {
            // Transaction was approved
            Toast.makeText(this, "Transaction approved", Toast.LENGTH_LONG).show();
        } else {
            // Card was declined, or transaction was aborted, or failed
            // (e.g. no internet or accessory not found)
            Toast.makeText(this, "Transaction was declined, aborted, or failed",
                    Toast.LENGTH_LONG).show();
        }
        // Grab the processed transaction in case you need it
        // (e.g. the transaction identifier for a refund).
        // Keep in mind that the returned transaction might be null
        // (e.g. if it could not be registered).
        Transaction transaction = MposUi.getInitializedInstance().getTransaction();
    }
}

More information on the completed transaction statuses and what they mean can be found here.

If you have problems with onActivityResult not being called, this might be caused by starting the PayButton Activity from the wrong Activity / Fragment. This Stackoverflow post might help you.

Use a real card reader

To test with a real card reader, order the Developer Kit. You can find more information about our Developer Kits here.

You can then retrieve your merchantIdentifier and merchantSecretKey through the Gateway Manager and change the ProviderMode to ProviderMode.TEST.

Then create the  AccessoryParameters with the reader family and connection you want to use.

For more information about the accessory and transaction parameters see the SDK Integration documentation.

Load merchant data from your backend

Right now, you have hardcoded the merchantIdentifier and merchantSecretKey. This means that all payments would be routed to the same merchant. 

For a live solution, you might want to support multiple merchants, e.g. two different restaurants, to route the payment correctly. To support multiple merchants, store the following data on your backend:

  1. merchantIdentifier and merchantSecretKey. They identify to which merchant the payment is routed. You can create new merchants and get their credentials in the Gateway Manager.

  2. Whether the merchant is a TEST or LIVE merchant.

  3. The reader model the merchant uses.

​You can then fetch this data before a transaction and configure the PayButton correctly:

MposUi ui = MposUi.initialize(this,
    <ProviderMode.TEST or ProviderMode.LIVE, loaded from your backend>,
    <MerchantIdentifier loaded from your backend>, <MerchantSecretKey loaded from your backend>);

Customize the PayButton

UI customization: Change the colors

123

You can choose the following colors:

  1. setColorPrimary: The icon's and top action bar's color
  2. setColorPrimaryDark: The color of the status bar (affects Android L and later)
  3. setTextColorPrimary: The primary text color
ui.getConfiguration().getAppearance()
     .setColorPrimary(Color.parseColor("#9c27b0"))
     .setColorPrimaryDark(Color.parseColor("#7b1fa2"))
     .setTextColorPrimary(Color.WHITE);

Receipt customization

You are required to offer an email or printed payment receipt to the shopper. The PayButton therefore allows the merchant to send an email payment receipt right after a transaction.

You might want to prevent this behavior, e.g. if you send your own receipts already and just want to append the required payment data. You can disable the built-in email receipts by removing MposUiConfiguration.SummaryFeature.SEND_RECEIPT_VIA_EMAIL from the setSummaryFeatures EnumSet.

If you choose to remove this, you must implement another way for the merchant to send out a receipt. You can either programmatically send the same receipt that the PayButton would send, or send a custom or printed one. For custom and printed receipts, you are required to display specific data. See this page for details.

 

Can we help you?

If you cannot find your answer, contact us and we'll get in touch with you soon.

© Copyright 2017 Payworks GmbH. Legal.