Implementing Pre-Authorizations and Captures
The SDK supports Pre-Authorizations and Captures, enabling you to support the payment workflows that your merchants require.
SDK version requirement:
The minimum SDK versions required are iOS 2.47 and Android 2.57.
Regardless of the types of additional transactions you will process, the transactions will always be based on a set of
MPTransactionParameters
. These parameters are provided to either:
[MPTransactionProvider startTransactionWithParameters:]
for cases where there is no previous reference transaction available and interaction with a card reader is required (CHARGEs)
or
[MPTransactionProvider amendTransactionWithParameters:]
for cases where you are modifying an existing transaction (captures and refunds) and you have to provide the
transaction.identifier
as a reference
Card Scheme Rules for Pre-Authorizations
Pre-Authorizations make it possible to reserve a guaranteed amount on the shopper's card and either Capture or Refund it later on. This option makes it easy for businesses, such as hotels and rental companies, to take deposits or up-front payments from their shoppers.
To comply with the Card Scheme regulations, you must make sure that your merchants follow those rules:
  • Pre-Authorizations are only permitted for Visa and Mastercard. Maestro does not allow Pre-Authorizations.
  • The captured amount must be equal to or lower than the pre-authorized amount.
  • Pre-Authorizations must be captured within 30 days to guarantee payment to the merchant.
  • For hotel, car rental company, or cruise line transaction businesses: If no capture is intended, the refund of the Pre-Authorization must take place within 24 hours of the check-out, rental return, or disembarkation date.
Performing a Pre-Authorization
To perform a Pre-Authorization on the card, modify the
MPTransactionParameters
to include the
autoCapture = NO
property for the initial transaction.
MPTransactionParameters *tp = [MPTransactionParameters chargeWithAmount:[NSDecimalNumber decimalNumberWithString:@"5.00"] currency:MPCurrencyEUR optionals: ^(id<MPTransactionParametersOptionals> _Nonnull optionals) { optionals.subject = @"Bouquet of Flowers"; optionals.customIdentifier = @"yourReferenceForTheTransaction"; optionals.autoCapture = NO; }];
Then, you start the transaction as usual via
[MPTransactionProvider startTransactionWithParameters:]
.
Make sure to provide a receipt to the shopper. For more information see, Custom Receipt and Preformatted Receipt.
Capturing a Pre-Authorization
To capture an Pre-Authorization later on, create the
MPTransactionParameters
that contains the
transactionIdentifier
of the previous transaction. Optionally, you can also change the amount that should ultimately be captured using the option.
MPTransactionParameters *parameters = [MPTransactionParameters captureTransactionWithIdentifier:@"<transactionIdentifier>" optionals: ^(id<MPTransactionParametersCaptureOptionals> _Nonnull optionals) { // For partial captures, specify the amount to be captured // and the currency from the Pre-Authorization // [optionals setAmount:[NSDecimalNumber decimalNumberWithString:@"1.00"] currency:MPCurrencyEUR]; }];
This is a modification to an existing transaction so you now need to pass the parameters to
[MPTransactionProvider amendTransactionWithParameters:]
.
As a result, you will receive one of the following:
  • The original transaction that is now captured, indicated by
    transaction.captured = YES
  • An error message indicating why capturing the charge failed
Implementing Pre-Authorizations and Captures
The SDK supports Pre-Authorizations and Captures, enabling you to support the payment workflows that your merchants require.
SDK version requirement:
The minimum SDK versions required are iOS 2.47 and Android 2.57.
Regardless of the types of additional transactions you will process, the transactions will always be based on a set of
TransactionParameters
. These parameters are provided to either:
TransactionProvider.startTransaction()
for cases where there is no previous reference transaction available and interaction with a card reader is required (CHARGEs)
or
TransactionProvider.amendTransaction()
for cases where you are modifying an existing transaction (captures and refunds) and you have to provide the
transaction.identifier
as a reference
Card Scheme Rules for Pre-Authorizations
Pre-Authorizations make it possible to reserve a guaranteed amount on the shopper's card and either Capture or Refund it later on. This makes it easy for businesses, such as hotels and rental companies, to take deposits or up-front payments from their shoppers.
To comply with the Card Scheme regulations, you must make sure that your merchants follow those rules:
  • Pre-Authorizations are only permitted for Visa and Mastercard. Maestro does not allow Pre-Authorizations.
  • The captured amount must be equal to or lower than the pre-authorized amount.
  • Pre-Authorizations must be captured within 30 days to guarantee payment to the merchant.
  • For hotel, car rental company, or cruise line transaction businesses: If no capture is intended, the refund of the Pre-Authorization must take place within 24 hours of the check-out, rental return, or disembarkation date.
Performing a Pre-Authorization
To perform a Pre-Authorization on the card, modify the
TransactionParameters
to include the
autoCapture = false
property for the initial transaction.
TransactionParameters parameters = new TransactionParameters.Builder() .charge(new BigDecimal("13.37"), Currency.EUR) .autoCapture(false) .build(); Intent intent = ui.createTransactionIntent(paramters);
Afterward, you start the transaction as usual via
TransactionProvider.startTransaction()
.
Make sure to provide a receipt to the shopper!
Capturing a Pre-Authorization
To capture an Pre-Authorization later on, create the
TransactionParameters
that contains the
transactionIdentifier
of the previous transaction. Optionally, you can also change the amount that should ultimately be captured.
TransactionParameters parameters = new TransactionParameters.Builder() .capture("<transactionIdentifer>") // For partial captures, specify the amount to be captured // and the currency from the Pre-Authorization //.amountAndCurrency(new BigDecimal("1.00"), io.mpos.transactions.Currency.EUR) .build(); Intent intent = ui.createTransactionIntent(paramters); startActivityForResult(intent, MposUi.REQUEST_CODE_PAYMENT);
This is a modification to an existing transaction so you are now passing the parameters to
TransactionProvider.amendTransaction()
.
As a result, you will receive one of the following:
  • The original transaction that is now captured, indicated by
    transaction.isCaptured() = true
  • An error message indicating why capturing the charge failed