Release NotesAnnouncementsVideosBlog
Guides

Accept a pre-authorization

United States

Use the PreAuthRequestIntentBuilder class to build an Intent to start an Activity that will guide a user through a pre-auth payment steps. The resulting pre-auth payment needs to be captured with a CapturePreAuth Request. The steps may include payment confirmation and receipt selection. These options can be customized through the merchant settings or by using options that can be configured on the PreAuthRequestIntentBuilder.

Prerequisites

Build a simple pre-auth request

You can build a pre-auth payment request with a few lines of code.

val externalPaymentId = "<posPaymentId>" // should be unique for each request
val amount = 5000L
val context = this

val builder = PreAuthRequestIntentBuilder(externalPaymentId, amount)
val intent = builder.build(context)

Context context = this;
String externalPaymentId = "<posPaymentId>"; // should be unique for each request
Long amount = 5000L;
 
PreAuthRequestIntentBuilder builder = new PreAuthRequestIntentBuilder(externalPaymentId, amount);
Intent intent = builder.build(context);

The Intent can then be used to start the activity to process the pre-auth request.

There are a few options that can be set on the builder to provide additional processing instructions:

  • CardOptions - settings for supported card entry methods and card confirmations
  • TokenizeOptions - settings for pay+tokenize card for use in e-commerce services

CardOptions

The CardOptions class provides a static method to optionally set the supported card entry methods, options to auto-accept duplicate payment challenges, and a cardNotPresent flag.

Static MethodDescription
Instance(<br>  <span style="white-space: nowrap;">cardEntryMethods : Set<CardEntryMethod>,</span><br>  <span style="white-space: nowrap;"> cardNotPresent : Boolean,</span><br>  <span style="white-space: nowrap;"> autoAcceptDuplicates : Boolean)This sets any of these flags to create a CardOptions instance. If null is passed, the default settings for the merchant will be used, optionally.

Example—Set the card entry method to Manual only and auto-accept duplicate challenges

val builder = PreAuthRequestIntentBuilder("<posPaymentId>", 5000)

builder.cardOptions(
   PreAuthRequestIntentBuilder.CardOptions.Instance(
       CardEntryMethod.Manual(), // manual only
       null, // card not present
       true)) // auto-accept duplicates

val intent = builder.build(context)

PreAuthRequestIntentBuilder builder = new PreAuthRequestIntentBuilder("<posPaymentId>", 5000);
builder.cardOptions(
     PreAuthRequestIntentBuilder.CardOptions.Instance(
           CardEntryMethod.Manual(), // manual only
           null, // card not present
           true)); // auto-accept duplicates
 
Intent intent = builder.build(context);

Tokenize Options

The TokenizeOptions class contains a single property, suppressConfirmation. However, the presence of TokenizeOptions, regardless of the suppressConfirmation value, indicates that a token for the payment card used should be generated. The tokenize option is secondary to the payment, so, a failed tokenization could still result in a successful payment but a failed payment will not result in a successful tokenization.

📘

Note

To utilize this feature, you must have core-payments installed in your device. Contact [email protected] for further queries.

ValueDescription
Instance(suppressConfirmation:boolean)Used to create a TokenizeOptions instance with the confirmation being required or not. By default, confirmation is required and will be requested.

Example—Request a payment token with a payment

val builder = PreAuthRequestIntentBuilder("<posPaymentId>", 5000)

builder.tokenizeOptions(PreAuthRequestIntentBuilder.TokenizeOptions.Instance(
   false // suppressConfirmation
));

val intent = builder.build(context)

PreAuthRequestIntentBuilder builder = new PreAuthRequestIntentBuilder("<posPaymentId>", 5000);
builder.tokenizeOptions(PreAuthRequestIntentBuilder.TokenizeOptions.Instance(
            false // suppressConfirmation
    ));
 
Intent intent = builder.build(context);

Additional Fields

You can set additional fields on the PreAuthRequestIntentBuilder:

FieldDescription
externalPaymentId: StringCustom external payment ID that will be persisted with the transaction.
amount: LongTotal amount paid.
externalReferenceId: StringID that can be passed to the merchant's gateway, and ultimately appear in settlement records. This ID translates to 'Invoice Number.

Examples—Custom card entry methods

These examples set the card entry methods to manual, swipe, and NFC only.

val builder = PreAuthRequestIntentBuilder("<posPaymentId>", 5000)

var cardEntryMethods = setOf<CardEntryMethod>(
   CardEntryMethod.MANUAL,
   CardEntryMethod.MAG_STRIPE, 
   CardEntryMethod.NFC)

var cardOptions = PreAuthRequestIntentBuilder.CardOptions.Instance(
   cardEntryMethods,
   null, // card not present
   null) // auto accept duplicates

builder.cardOptions(cardOptions)

val intent = builder.build(context)

PreAuthRequestIntentBuilder builder = new PreAuthRequestIntentBuilder("<posPaymentId>", 5000);
 
Set<CardEntryMethod> cardEntryMethods = new HashSet<>();
cardEntryMethods.add(CardEntryMethod.MANUAL);
cardEntryMethods.add(CardEntryMethod.NFC);
PreAuthRequestIntentBuilder.CardOptions cardOptions = PreAuthRequestIntentBuilder.CardOptions.Instance(
            cardEntryMethods,
            null,                   //card not present
            null);                  //auto accept duplicates
builder.cardOptions(cardOptions);
Intent intent = builder.build(context);

Updated 3 months ago