All Miura Card Readers
Integrating Payments Into Your App
With the mCashier SDK, you can integrate mCashier directly into your own app.
The mCashier SDK displays ready-made views that guide the merchant through the payment process and shows a summary in the end.
If you need help with the integration, please contact Customer Support.
Getting a Card Reader
Before starting the integration, please order a card reader by applying for a mCashier account at mcashier.ch. If this is not possible for you (e.g., because you do not have an organization for which you can request a merchant account), please contact us.
Install
Put the following in to your Podfile and then run pod install:
source 'https://github.com/CocoaPods/Specs.git' source 'https://github.com/visa/mpos.sdk.ios.pods.git' use_frameworks! target :"your-app-target>" do pod 'payworks', '2.61.0' pod 'payworks.paybutton', '2.61.0' end
To connect to the card reader as an external accessory and to be able to receive messages while the app is in the background, add two additional entries to your Info.plist:
- Key: Supported external accessory protocols (UISupportedExternalAccessoryProtocols), value: com.miura.shuttle
- 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>
Initialize
Initialize an instance of MPUMposUi before using it:
[MPUMposUi initializeWithProviderMode:MPProviderModeLIVE application:MPUApplicationNameMcashier integratorIdentifier:@"YOUR-INTEGRATOR-IDENTIFIER"]; [MPUMposUi sharedInitializedInstance].configuration. summaryFeatures = MPUMposUiConfigurationSummaryFeatureSendReceiptViaEmail;
Make sure to insert your integratorIdentifier. You receive your integratorIdentifier when you sign up for the SDK, or by writing an e-mail to [email protected].
Later, you can access the initialized instance with [MPUMposUi sharedInitializedInstance].
Payments
First, add the following convenience method to your code. It wraps a given view controller in a navigationController and then displays it modally on the iPad, and fullscreen on the iPhone:
- (void) showMposUiViewController:(UIViewController*) controller { UINavigationController *modalNav = [[UINavigationController alloc] initWithRootViewController:controller]; 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]; }
Then, you can start a payment:
- (IBAction)paymentButtonClicked:(id)sender { MPUMposUi *ui = [MPUMposUi sharedInitializedInstance]; MPAccessoryParameters *ap = [MPAccessoryParameters externalAccessoryParametersWithFamily:MPAccessoryFamilyMiuraMPI protocol:@"com.miura.shuttle" optionals:nil]; MPTransactionParameters *tp = [MPTransactionParameters chargeWithAmount:[NSDecimalNumber decimalNumberWithString:@"5.00"] currency:MPCurrencyCHF optionals:^(id MPTransactionParametersOptionals> _Nonnull optionals) { optionals.subject = @"Bouquet of Flowers"; optionals.customIdentifier = @"yourReferenceForTheTransaction"; }]; ui.configuration.terminalParameters = ap; ui.configuration.summaryFeatures = MPUMposUiConfigurationSummaryFeatureSendReceiptViaEmail; // Add this line, if you do also want to offer printed receipts //ui.configuration.printerParameters = //ui.configuration.summaryFeatures |= MPUMposUiConfigurationSummaryFeaturePrintReceipt; 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]; }]; [self showMposUiViewController:viewController]; }
Refunds
To refund a transaction, you need the transaction.identifier and create appropriate MPTransactionParameters:
MPTransactionParameters *tp = [MPTransactionParameters refundForTransactionIdentifier:identifier optionals:nil];
Transaction summary
To show a transaction summary, also use the transaction's transaction.identifier.
UIViewController *summaryController = [[MPUMposUi sharedInitializedInstance] createSummaryViewControllerWithTransactionIdentifier:self.transactionIdentifier completed:^(UIViewController *controller) { [self dismissViewControllerAnimated:YES completion:NULL]; }]; [self showMposUiViewController:summaryController];
Settings screen
To show a settings screen that allows the user to access the help and to log out, use the following:
UIViewController *settingsController = [[MPUMposUi sharedInitializedInstance] createSettingsViewController:^(UIViewController *controller) { [self dismissViewControllerAnimated:YES completion:NULL]; }]; [self showMposUiViewController:settingsController];
Force a logout
If the user logs out in your app, you might want to force a logout:
[[MPUMposUi sharedInitializedInstance] logout];
Check if the user is logged in
You can check if a user is logged in:
BOOL isLoggedIn = [[MPUMposUi sharedInitializedInstance] isApplicationLoggedIn];
Custom and printed receipts
If you want to create custom or printed receipts, you can access the receipts as part of the transaction object that is returned in the completed callback:
UIViewController *viewController = [ui createTransactionViewControllerWithTransactionParameters:tp completed:^(UIViewController * _Nonnull controller, MPUTransactionResult result, MPTransaction * _Nullable transaction) { [...] MPReceipt *merchantReceipt = transaction.merchantReceipt; MPReceipt *customerReceipt = transaction.customerReceipt; }];
Note: Make sure to check if the user is logged in, otherwise you can't query the receipt data. Also, make sure the custom and printed receipt contains at least all the data that is shown on the email receipts.
Integrating Payments Into Your App
With the mCashier SDK, you can integrate mCashier right into your own app.
The mCashier SDK will show ready-made views that guide the merchant through the payment process and shows a summary in the end.
We're happy to help you with the integration. If you have any questions, please contact Customer Support.
Getting a Card Reader
Before starting the integration, order a card reader by applying for a mCashier account at mcashier.ch. If this is not possible for you (e.g., because you do not have an organization for which you can request a merchant account), please contact us.
Install
The PayButton installation requires setting compileSdkVersion 25 in your build.gradle file.
Add our repository to your project's build.gradle file:
allprojects { repositories { jcenter() maven { url "https://repo.visa.com/mpos-releases/" } } }
Add the following exclusion rules to your module's build.gradle file, 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' }
Add the libraries to the dependencies section of your module's build.gradle file:
dependencies { compile 'com.android.support:appcompat-v7:25.2.0' compile 'com.android.support:cardview-v7:25.2.0' compile 'com.android.support:support-v4:25.2.0' compile 'io.payworks:mpos.android.ui:2.61.0' compile 'io.payworks:mpos.java.accessories.miura:2.61.0' compile 'io.payworks:mpos.android.comlinks.bluetooth:2.61.0' }
Initialize
Initialize an instance of the MposUi before using it:
MposUi mposUi = MposUi.initialize(this, ProviderMode.LIVE, ApplicationName.MCASHIER, "YOUR-INTEGRATOR-IDENTIFIER"); mposUi.getConfiguration().setSummaryFeatures(EnumSet.of(MposUiConfiguration.SummaryFeature.SEND_RECEIPT_VIA_EMAIL));
Make sure to insert your integratorIdentifier. You receive your integratorIdentifier when you sign up for the SDK, or by sending us an email.
You can then access the initialized instance with the following:
MposUi mposUi = MposUi.getInitializedInstance();
Payments
To start a payment:
MposUi mposUi = MposUi.getInitializedInstance(); TransactionParameters transactionParameters = new TransactionParameters.Builder() .charge(new BigDecimal("5.00"), io.mpos.transactions.Currency.EUR) .subject("Bouquet of Flowers") .customIdentifier("yourReferenceForTheTransaction") .build(); Intent intent = mposUi.createTransactionIntent(transactionParameters); startActivityForResult(intent, MposUi.REQUEST_CODE_PAYMENT);
The result of the payment is 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(); } }
Refunds
To refund a transaction, you need the transaction.identifier:
MposUi mposUi = MposUi.getInitializedInstance(); TransactionParameters refundParameters = new TransactionParameters.Builder() .refund("TRANSACTION-IDENTIFIER>") .build(); Intent refundIntent = mposUi.createTransactionIntent(refundParameters); startActivityForResult(intent, MposUi.REQUEST_CODE_PAYMENT);
The result of the refund is delivered the same way as in the payment process.
Transaction Summary
To show a transaction summary, use the transaction.identifier of the transaction.
MposUi mposUi = MposUi.getInitializedInstance(); Intent summaryIntent = mposUi.createTransactionSummaryIntent(mLastTransactionIdentifier); startActivityForResult(summaryIntent, MposUi.REQUEST_CODE_SHOW_SUMMARY);
Settings Screen
To show the Settings screen that enables the user to log out and access to help:
MposUi mposUi = MposUi.getInitializedInstance(); Intent intent = mposUi.createSettingsIntent(); startActivityForResult(intent, MposUi.REQUEST_CODE_SETTINGS);
Force a Log Out
At some point, you might want to force a log out such as when the user logs out from your app. To force a log out:
MposUi mposUi = MposUi.getInitializedInstance() mposUi.logout();
Check User Log-In Status
To check if a user is logged in:
MposUi mposUi = MposUi.getInitializedInstance() boolean isLoggedIn = mposUi.isLoggedIn();
Custom and Printed Receipts
To create custom or printed receipts, access the embedded receipt objects after the transaction completes. Make sure to check if the user is logged in, otherwise you cannot query the receipt data. Custom and printed receipt must contains, at the minimum, all the information shown on the email receipt.
@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { if (requestCode == MposUi.REQUEST_CODE_PAYMENT) { [...] //get hold of the last transaction Transaction transaction = MposUi.getInitializedInstance().getTransaction(); Receipt merchantReceipt = transaction.getMerchantReceipt(); Receipt customerReceipt = transaction.getCustomerReceipt(); } }