PaymentRequestIntentBuilder class to build an Intent to start an Activity that will guide a user through the payment steps. Depending on the merchant configuration and Intent options set, a successful payment may be either a finalized payment or a tip-adjustable payment. The steps may include tip selection, signature collection, payment confirmation, and receipt selection. These options can be customized through the merchant settings or by using options that can be configured on the
You can build a payment request with a few lines of code.
val externalPaymentId = "<posPaymentId>" // should be unique for each request val amount = 1000L val context = this val builder = PaymentRequestIntentBuilder(externalPaymentId, amount) val intent = builder.build(context)
The Intent can then be used to start the activity to process the payment request.
There are several options that can be set on the builder to provide additional processing instructions:
- TipOptions & SignatureOptions - settings for tips (if tips are enabled for merchant) and settings for signature requirements
- CardOptions - settings for supported card entry methods and card confirmations
- ReceiptOptions - settings for receipt screen
- OfflineOptions - settings to control offline payment options
- TokenizeOptions - settings for pay+tokenize card for use in e-commerce services
TipOptions & SignatureOptions are independent options that can be excluded, however, they share the same “location” value (on screen/on paper).
The TipOptions class provides static helper methods to simplify the creation of TipOptions.
Sets the options so no tip is requested. This should result in a finalized payment that is NOT tip adjustable.
If the tip amount is known before the payment request, this will add the tip amount to the payment and the payment will be finalized.
Use to set the amount used to calculate the percentage-based tips or override the tip suggestions with fixed amounts or custom percentages.
The merchant’s payment gateway settings must be configured for tippable payment for a tip-adjustable payment to be created. On some devices, tips are taken prior to the payment and can be supported without merchant payment gateway settings, as the payment will be finalized by the gateway.
SignatureOptions class provides static helper methods to simplify the creation of SignatureOptions.
Set the options so no signature is requested.
Use to override the merchant settings for when and if, to prompt for a signature.
val builder = PaymentRequestIntentBuilder("<posPaymentId>", 1500) builder.tipAndSignatureOptions( PaymentRequestIntentBuilder.TipOptions.Disable(), PaymentRequestIntentBuilder.SignatureOptions.Disable(), null) // preferOnScreen val intent = builder.build(context)
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.
Can optionally set any of these flags to create a CardOptions instance. If
val builder = PaymentRequestIntentBuilder("<posPaymentId>", 1500) builder.cardOptions( PaymentRequestIntentBuilder.CardOptions.Instance( CardEntryMethod.Manual(), // manual only null, // card not present true)) // auto-accept duplicates val intent = builder.build(context)
ReceiptOptions class currently only provides one option, to skip the receipt selection screen.
Can optionally configure the flow to skip the receipt selection.
OfflineOptions class provides a static method to configure three flags for offline payments settings.
The merchant’s payment gateway must be configured for offline payments for these settings to be effective.
Use to create an OfflineOptions instance that is configured to take the payment offline if needed, take the payment offline without prompting the merchant and even force the payment to be taken offline. The resulting payment will return a value of
val builder = PaymentRequestIntentBuilder("<posPaymentId>", 1500) builder.offlineOptions( PaymentRequestIntentBuilder.OfflineOptions.Instance( true, // allow offline true, // approveOfflineWithoutPrompt null)) // forceOffline val intent = builder.build(context)
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.
Used to create a TokenizeOptions instance with the confirmation being required or not. By default, confirmation is required and will be requested.
val builder = PaymentRequestIntentBuilder("<posPaymentId>", 1500) builder.tokenizeOptions(PaymentRequestIntentBuilder.TokenizeOptions.Instance( false // suppressConfirmation )); val intent = builder.build(context)
Example of creating custom tip options of $1.00, $2.00, and 20% and prefer onScreen tips.
val builder = PaymentRequestIntentBuilder("<posPaymentId>", 1500) var tipSuggestions = listOf<TipSuggestion>( TipSuggestion.Amount("Thanks!", 100), TipSuggestion.Amount("Good Job!", 200), TipSuggestion.Percentage("Great!", 20) ) var tipOptions = PaymentRequestIntentBuilder.TipOptions.PromptCustomer(null, tipSuggestions) builder.tipAndSignatureOptions( tipOptions, null, // signature options true) // preferOnScreen val intent = builder.build(context)
Examples of setting the card entry methods to Manual and NFC only.
val builder = PaymentRequestIntentBuilder("<posPaymentId>", 1500) var cardEntryMethods = setOf<CardEntryMethod>( CardEntryMethod.MANUAL, CardEntryMethod.NFC) var cardOptions = PaymentRequestIntentBuilder.CardOptions.Instance( cardEntryMethods, null, // card not present null) // auto accept duplicates builder.cardOptions(cardOptions) val intent = builder.build(context)
Example reducing the screens to only the payment screen. This example disables tips, signatures, and payment confirmations, and skips the receipt screen.
val builder = PaymentRequestIntentBuilder("<posPaymentId>", 1500) builder.tipAndSignatureOptions( PaymentRequestIntentBuilder.TipOptions.Disable(), PaymentRequestIntentBuilder.SignatureOptions.Disable(), true) builder.cardOptions( PaymentRequestIntentBuilder.CardOptions.Instance( null, null, true)) builder.receiptOptions(PaymentRequestIntentBuilder.ReceiptOptions.Disable())
Updated about 2 months ago