Integrating the SDK
PayButton is an easy-to-use, reference implementation for a user interface on top of the SDK. Before starting a custom integration, evaluate whether the PayButton Integration can meet your needs.
To get started with a custom integration: 
  1. Add the SDK to your app.
  2. Choose a view controller of your app. This should be the view controller that starts the payment.
We recommend integrating the UI for the payment in either a modal or a screen separate from your checkout (e.g., the modal should be shown over the shopping cart). This step helps ensure that a user cannot change the amount, or add / delete products from the cart during a transaction.
It is important to set the modal or separate screen so that it can be closed only after the SDK calls the 
completed
 callback. Make sure to hide all 
Close
 or 
Back
 buttons until the transaction is completed. Otherwise, if such a button is tapped, the SDK will continue with the transaction, but the merchant cannot see the result.
Paste the following code into the view controller implementation. Replace the 
MERCHANT_IDENTIFIER
 and 
MERCHANT_SECRET_KEY
 with your testing credentials. Uncomment the correct value for your card reader.
- (IBAction)transaction:(id)sender { MPTransactionProvider* transactionProvider = [MPMpos transactionProviderForMode:MPProviderModeTEST merchantIdentifier:@"MERCHANT_IDENTIFIER" merchantSecretKey:@"MERCHANT_SECRET_KEY"]; MPTransactionParameters *transactionParameters = [MPTransactionParameters chargeWithAmount:[NSDecimalNumber decimalNumberWithString:@"5.00"] currency:MPCurrencyEUR optionals:^(id<MPTransactionParametersOptionals> _Nonnull optionals) { optionals.subject = @"Bouquet of Flowers"; optionals.customIdentifier = @"yourReferenceForTheTransaction"; }]; // When using the Bluetooth Miura, use the following parameters: // MPAccessoryParameters *ap = [MPAccessoryParameters externalAccessoryParametersWithFamily:MPAccessoryFamilyMiuraMPI // protocol:@"com.miura.shuttle" // optionals:nil]; // When using Verifone readers via WiFi or Ethernet, use the following parameters: // MPAccessoryParameters *ap = [MPAccessoryParameters tcpAccessoryParametersWithFamily:MPAccessoryFamilyVerifoneVIPA // remote:@"192.168.254.123" // port:16107 // optionals:nil]; MPTransactionProcess *process = [transactionProvider startTransactionWithParameters:transactionParameters accessoryParameters:ap registered:^(MPTransactionProcess *process, MPTransaction *transaction) { NSLog(@"registered MPTransactionProcess, transaction id: %@", transaction.identifier); } statusChanged:^(MPTransactionProcess *process, MPTransaction *transaction, MPTransactionProcessDetails *details) { NSLog(@"%@\n%@", details.information[0], details.information[1]); } actionRequired:^(MPTransactionProcess *process, MPTransaction *transaction, MPTransactionAction action, MPTransactionActionSupport *support) { switch (action) { case MPTransactionActionCustomerSignature: { NSLog(@"show a UI that let's the customer provide their signature!"); // In a live app, this image comes from your signature screen UIGraphicsBeginImageContext(CGSizeMake(1, 1)); UIImage *capturedSignature = UIGraphicsGetImageFromCurrentImageContext(); UIGraphicsEndImageContext(); [process continueWithCustomerSignature:capturedSignature verified:YES]; // Add this instead, if you would like to collect the customer signature on the printed merchant receipt [process continueWithCustomerSignatureOnReceipt]; break; } case MPTransactionActionCustomerIdentification: { // always return NO here [process continueWithCustomerIdentityVerified:NO]; break; } case MPTransactionActionApplicationSelection: { // This happens only for readers that don't support application selection on their screen break; } default: { break; } } } completed:^(MPTransactionProcess *process, MPTransaction *transaction, MPTransactionProcessDetails *details) { NSLog(@"Transaction ended, transaction status is %lu", (unsigned long) transaction.status); if (details.state == MPTransactionProcessDetailsStateApproved) { // Ask the merchant, whether the shopper wants to have a receipt // and close the checkout UI } else { // Allow your merchant to try another transaction } // only close your modal here }]; }
More information on the completed transaction statuses can be found here.
To ensure that the merchant always receives detailed status information about the transaction:
  1. Create a button and connect it with the 
    transaction
     action. 
  2. In your payment UI, add two 
    UILabels
     that display the contents of the 
    details.information[0]
     and 
    details.information[1]
     each time the 
    statusChange
     is called.
For the Bluetooth Miura card reader, pair the reader with your device. Then, follow these steps:
  1. Start the app and tap your button.
  2. Follow the instructions on the reader and in the app. The test transaction will not charge your card. You just processed the first transaction from your app.
Enabling Merchants to Abort Transactions
You have the option to enable merchants to abort transactions. The feature is usually displayed on the card reader as a red "X". However, it is recommended that you create an in-app button to enable the merchant to abort the transaction.
Aborting a transaction is not always possible in different stages of the transaction. For example, it is not possible to abort in the last stage of a transaction. Therefore, show/hide your 
Abort
 button using the 
canBeAborted
 flag in 
statusChanged
:
statusChanged:^(MPTransactionProcess *process, MPTransaction *transaction, MPTransactionProcessDetails *details) { _abortButton.hidden = ![transaction canBeAborted]; }
Then, create an action for the 
Abort
 button that enables the merchant to abort the transaction:
- (IBAction)abortTapped:(id)sender { [_process requestAbort]; }
Do not hide the checkout UI directly after requesting the abort, and do not display messages such as '"Aborting..." by yourself. The SDK will call the 
completed
 callback after the transaction is aborted. Also, we recommend letting the transaction continue while the app is in the background.
Storing Merchant Data on Your Backend
Currently, 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, such as two different restaurants, to route the payment correctly. To support multiple merchants, store the following data on your backend: 
  1. merchantIdentifier
     and 
    merchantSecretKey
     to identify which merchant the payment is routed to. You can create new merchants and get their credentials in the Gateway Manager.
  2. Whether the merchant is a 
    TEST
     or 
    LIVE
     merchant.
You can then fetch this data before a transaction and configure the SDK correctly: 
MPTransactionProvider* transactionProvider = [MPMpos transactionProviderForMode:<TEST or LIVE, loaded from your backend> merchantIdentifier:<MerchantIdentifier loaded from your backend> merchantSecretKey:<MerchantSecretKey loaded from your backend> ];
Specifying the Accessory
You have to specify which accessory you want to use with your app and how to connect to it by defining an 
MPAccessoryParameters
 object, which you can create with the provided class helper methods. The 
MPAccessoryFamily
-is type of accessory that you want to connect to. The optionals block provides access to all parameters that you have the optional to specify for this type of connection. For example, for an External Accessory, this is a name prefix to filter for. 
Different types of accessories can be connected with different methods. An incorrect configurations will fail when starting the transaction. Make sure to include the correct libraries for the accessory and connection type.
Specifying the Transaction
You have to specify the parameters of the transaction you want to execute with a 
MPTransactionParameters
 object, which you can create with the provided class methods.
For charge transactions call the 
chargeWithAmount:
 with the amount and currency that you want to use.
The currencies that you can use for your transactions are limited by the configuration of your Processing Path. An incorrect currency will fail when executing the transaction. In the optionals block you can specify the following additional methods that are attached to the transaction:
Method
Description
Visible in
Applicable for
 
.subject
 
Subject of the transaction
Gateway Manager
All
 
.customIdentifier
 
Your custom identifier for the transaction
Gateway Manager
All
 
.statementDescriptor
 
Descriptor of the transaction
Stripe Dashboard, Customer's payment card statement
Stripe
 
.applicationFee
 
Fee that will be further applied to the transaction
Stripe Dashboard
Stripe
 
.metadata
 
Extra information to further specify the transaction
Stripe Dashboard
Stripe
Integrating the SDK
PayButton is an easy-to-use, reference implementation for a user interface on top of the SDK. Before starting a custom integration, evaluate whether the PayButton Integration can meet your needs.
To get started with a custom integration: 
  1. Add the SDK to your app
  2. Choose a view controller of your app. This should be the view controller that starts the payment.
We recommend integrating the UI for the payment in either a modal or a screen separate from your checkout (e.g., the modal should be shown over the shopping cart). This step helps ensure that a user cannot change the amount, or add / delete products from the cart during a transaction.
It is important to set the modal or separate screen so that it can be closed only after the SDK calls the 
onCompleted
 callback. Make sure to hide all 
Close
 or 
Back
 buttons until the transaction is completed. Otherwise, if such a button is tapped, the SDK will continue with the transaction, but the merchant cannot see the result.
Paste the following code into the view controller implementation. Replace the 
MERCHANT_IDENTIFIER
 and 
MERCHANT_SECRET_KEY
 with your testing credentials, or use 
TransactionProvider
 in mocked mode. Use the correct value of 
AccessoryParameters
 for your reader.
void transaction() { final TransactionProvider transactionProvider = Mpos.createTransactionProvider(this, ProviderMode.TEST, "MERCHANT_IDENTIFIER", "MERCHANT_SECRET_KEY"); /* For starting transaction in mocked mode use fallowing provider: final TransactionProvider transactionProvider = Mpos.createTransactionProvider(this, ProviderMode.MOCK, "merchantIdentifier", "merchantSecretKey"); */ /* When using the Bluetooth Miura, use the following parameters: */ AccessoryParameters accessoryParameters = new AccessoryParameters.Builder(AccessoryFamily.MIURA_MPI) .bluetooth() .build(); /* When using Verifone readers via WiFi or Ethernet, use the following parameters: AccessoryParameters accessoryParameters = new AccessoryParameters.Builder(AccessoryFamily.VERIFONE_VIPA) .tcp("192.168.254.123", 16107) .build(); */ TransactionParameters transactionParameters = new TransactionParameters.Builder() .charge(new BigDecimal("5.00"), io.mpos.transactions.Currency.EUR) .subject("Bouquet of Flowers") .customIdentifier("yourReferenceForTheTransaction") .build(); TransactionProcess paymentProcess = transactionProvider.startTransaction(transactionParameters, accessoryParameters, new TransactionProcessWithRegistrationListener() { @Override public void onRegistered(TransactionProcess process, Transaction transaction) { Log.d("mpos", "transaction identifier is: " + transaction.getIdentifier() + ". Store it in your backend so that you can always query its status."); } @Override public void onStatusChanged(TransactionProcess process , Transaction transaction, TransactionProcessDetails processDetails) { Log.d("mpos", "status changed: " + Arrays.toString(processDetails.getInformation())); } @Override public void onCustomerSignatureRequired(TransactionProcess process, Transaction transaction) { // in a live app, this image comes from your signature screen Bitmap.Config conf = Bitmap.Config.ARGB_8888; Bitmap bm = Bitmap.createBitmap(1, 1, conf); byte[] signature = BitmapHelper.byteArrayFromBitmap(bm); process.continueWithCustomerSignature(signature, true); } @Override public void onCustomerVerificationRequired(TransactionProcess process, Transaction transaction) { // always return false here process.continueWithCustomerIdentityVerified(false); } @Override public void onApplicationSelectionRequired(TransactionProcess process, Transaction transaction, List<ApplicationInformation> applicationInformation) { // This happens only for readers that don't support application selection on their screen process.continueWithSelectedApplication(applicationInformation.get(0)); } @Override public void onDccSelectionRequired(TransactionProcess transactionProcess, Transaction transaction, DccInformation dccInformation) { // This comes up if the DCC selection cannot be done on the terminal itself transactionProcess.continueDccSelectionWithOriginalAmount(); } @Override public void onCompleted(TransactionProcess process, Transaction transaction, TransactionProcessDetails processDetails) { Log.d("mpos", "completed"); if (processDetails.getState() == TransactionProcessDetailsState.APPROVED) { // print the merchant receipt Receipt merchantReceipt = transaction.getMerchantReceipt(); // print a signature line if required if(merchantReceipt.isSignatureLineRequired()) { System.out.println(""); System.out.println(""); System.out.println(""); System.out.println("------ PLEASE SIGN HERE ------"); } // ask the merchant, whether the shopper wants to have a receipt Receipt customerReceipt = transaction.getCustomerReceipt(); // and close the checkout UI } else { // Allow your merchant to try another transaction } } }); } @Override public void onBackPressed() { Toast.makeText(this, "The back button is disabled during a transaction. Please use the 'abort' button to cancel the transaction.", Toast.LENGTH_LONG).show(); }
More information on the completed transaction statuses can be found here.
To ensure that the merchant always receives detailed status information about the transaction:
  1. Create a button to call the 
    transaction
    method. 
  2.  In your payment UI, add two
    TextViews
    that display the contents of 
    processDetails.getInformation()[0]
    and 
    processDetails.getInformation()[1]
    each time
    onStatusChanged
    is called.
For the Bluetooth Miura card reader, pair the reader with your device. Then, follow these steps:
  1. Start the app and tap your button.
  2. Follow the instructions on the reader and in the app. The test transaction will not charge your card. You just processed the first transaction from your app. 
Enabling the Merchant to Abort Transactions
You have the option to enable merchants to abort transactions. The feature is usually displayed on the card reader as a red "X". However, it is recommended that you create an in-app button to enable the merchant to abort the transaction.
Aborting a transaction is not always possible in different stages of the transaction. For example, it is not possible to abort in the last stage of a transaction. Therefore, show/hide your 
Abort
 button using the
canBeAborted
flag in
onStatusChanged
:
public void onStatusChanged(TransactionProcess process , Transaction transaction, TransactionProcessDetails processDetails) { //.. abortButton.setVisibility(transaction != null && transaction.canBeAborted() ? View.VISIBLE : View.INVISIBLE); }
Then, create a click listener for the abort button that aborts the transaction:
public void abort() { process.requestAbort(); }
Do not hide the checkout UI directly after the merchant has requested the abort, and do not show message text such as "Aborting..." by yourself. The SDK will call the 
onCompleted
 callback once the transaction is aborted. Also, we recommend letting the transaction continue while the app is in the background.
Storing Merchant Data on Your Backend
Currently, 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, such as for two different restaurants, to route the payment correctly. To support multiple merchants, store the following data on your backend:
  1.  
    merchantIdentifier
     and 
    merchantSecretKey
     to identify which merchant the payment is routed to. You can create new merchants and get their credentials in the Gateway Manager.
  2. Whether the merchant is a 
    TEST
     or 
    LIVE
     merchant.
You can then fetch this data before a transaction and configure the SDK correctly:
final TransactionProvider transactionProvider = Mpos.createTransactionProvider(this, <TEST or LIVE, loaded from your backend>, <MerchantIdentifier loaded from your backend>, <MerchantSecretKey loaded from your backend>);
Specifying the Accessory
You must specify which accessory you want to use with your app and how to connect to it by defining an 
AccessoryParameters
 object, which you can create with the provided builder.
The argument, which you pass into the builder's constructor, specifies the 
AccessoryFamily
. This is the type of accessory that you want to connect to.
The method, which you call right after the constructor, specifies the connection type that you want to use. Currently available methods are 
mock()
bluetooth()
 and 
tcp()
.
Different types of accessories can be connected with different methods. An incorrect configuration will fail when starting the transaction. Make sure you have included the correct libraries for the accessory and connection type.
After the second method, depending on which connection type you selected, you can set different options specifying the connection. For example, for Bluetooth you can select an address prefix that will be applied when searching for the accessory.
Specifying the Transaction
You must specify the parameters of the transaction you want to execute with a 
TransactionParameters
 object, which you can create with the provided builder.
For charge transactions call the 
charge()
 method with the amount and currency that you want to use.
The currencies that you can use for your transactions are limited by the configuration of your Processing Path. An incorrect currency will fail when executing the transaction.
After the 
charge()
 method you can specify additional, optional methods, including:
Method
Description
Visible in
Applicable for
 
subject()
 
Subject of the transaction
Gateway Manager
All
 
customIdentifier()
 
Your custom identifier for the transaction
Gateway Manager
All
 
statementDescriptor()
 
Descriptor of the transaction
Stripe Dashboard, Customer's payment card statement
Stripe
 
applicationFee()
 
Fee that will be further applied to the transaction
Stripe Dashboard
Stripe
 
metadata()
 
Extra information to further specify the transaction
Stripe Dashboard
Stripe