com.stripe.stripeterminal

Class Terminal

com.stripe.stripeterminal.Terminal

@Singleton
public class Terminal

The Terminal is the top-level object for the Stripe Terminal SDK.

Use of this SDK is subject to the Stripe Terminal Terms: https://stripe.com/terminal/legal

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Terminal.Companion

Field Summary

Fields

Modifier and Type	Field and Description
static Terminal.Companion	Companion

Method Summary

Modifier and Type	Method and Description
void	cancelPaymentIntent(PaymentIntent intent, PaymentIntentCallback callback) Cancels a class PaymentIntent.
Cancelable	checkForUpdate(ReaderSoftwareUpdateCallback callback) Checks for a reader update and prompts your app to begin installing the update.
void	clearCachedCredentials() Clears the current connection token, saved reader sessions, and any other cached credentials. You can use this method to switch accounts in your app, e.g. to switch between live and test Stripe API keys on your backend.
Cancelable	collectPaymentMethod(PaymentIntent intent, ReaderDisplayListener listener, PaymentIntentCallback callback) Collects a payment method for the given class PaymentIntent.
void	connectReader(Reader reader, ReaderCallback connectionCallback) Attempts to connect to the given reader.
void	createPaymentIntent(PaymentIntentParameters params, PaymentIntentCallback callback) Creates a new class PaymentIntent with the given parameters.
void	disconnectReader(Callback callback) Attempts to disconnect from the currently connected reader.
Cancelable	discoverReaders(DiscoveryConfiguration config, DiscoveryListener discoveryListener, Callback callback) Begins discovering readers matching the given class DiscoveryConfiguration.
Reader	getConnectedReader()
ConnectionStatus	getConnectionStatus() Get the current enum ConnectionStatus
static Terminal	getInstance() Returns the current instance of the class Terminal object. This instance should have been initialized already by calling initTerminal.
PaymentStatus	getPaymentStatus() Get the current enum PaymentStatus
static void	initTerminal(android.content.Context context, LogLevel logLevel, ConnectionTokenProvider tokenProvider, TerminalListener listener) Initializes a terminal for the given context.
static void	initTerminal(android.content.Context context, ConnectionTokenProvider tokenProvider, TerminalListener listener) Initializes a terminal for the given context.
Cancelable	installUpdate(ReaderSoftwareUpdate update, ReaderSoftwareUpdateListener listener, Callback callback) Installs a specific update on the reader.
static boolean	isInitialized() Returns whether a class Terminal instance currently exists.
void	processPayment(PaymentIntent intent, PaymentIntentCallback callback) Processes a payment after collecting a payment method succeeds.
Cancelable	readReusableCard(ReadReusableCardParameters params, ReaderDisplayListener listener, PaymentMethodCallback callback) Reads a card with the given parameters and returns a PaymentMethod.
void	retrievePaymentIntent(java.lang.String clientSecret, PaymentIntentCallback callback) Retrieves a class PaymentIntent with a client secret.
void	setTerminalListener(TerminalListener listener) Sets the current implementation of interface TerminalListener. This will replace any previous interface TerminalListeners that have been registered.

Field Detail

Companion

public static Terminal.Companion Companion

Method Detail

getConnectionStatus

@NotNull
public ConnectionStatus getConnectionStatus()

Get the current enum ConnectionStatus

Returns:

the current connection status

See Also:

enum ConnectionStatus

getPaymentStatus

@NotNull
public PaymentStatus getPaymentStatus()

Get the current enum PaymentStatus

Returns:

the current payment status

See Also:

enum PaymentStatus

getConnectedReader

@Nullable
public Reader getConnectedReader()

Returns:

The class Reader that is currently connected or null if no reader is connected

setTerminalListener

public void setTerminalListener(@NotNull
                                TerminalListener listener)

Sets the current implementation of interface TerminalListener. This will replace any previous interface TerminalListeners that have been registered.

See Also:

interface TerminalListener, interface TerminalListener

cancelPaymentIntent

public void cancelPaymentIntent(@NotNull
                                PaymentIntent intent,
                                @NotNull
                                PaymentIntentCallback callback)

Cancels a class PaymentIntent.

If the cancel request succeeds, PaymentIntentCallback.onSuccess will be called with the updated class PaymentIntent object with status CANCELED. If the cancel request fails, PaymentIntentCallback.onFailure will be called with an error.

https://stripe.com/docs/terminal/payments/refunds

Parameters:

intent - The class PaymentIntent to be canceled

callback - The interface PaymentIntentCallback that should be called upon completion

See Also:

class PaymentIntent, PaymentIntentCallback.onSuccess, class PaymentIntent, PaymentIntentCallback.onFailure

clearCachedCredentials

public void clearCachedCredentials()

Clears the current connection token, saved reader sessions, and any other cached credentials. You can use this method to switch accounts in your app, e.g. to switch between live and test Stripe API keys on your backend.

In order to switch accounts in your app:

• if a reader is connected, call disconnectReader

• call clearCachedCredentials

• call discoverReaders and connectReader to connect to a reader. The connectReader call will request a new connection token from your backend server.

An overview of the lifecycle of a connection token under the hood:

• When a Terminal is initialized, the SDK attempts to proactively request a connection token from your backend server.

• When connectReader is called, the SDK uses the connection token and reader information to create a reader session.

• Subsequent calls to connectReader require a new connection token. If you disconnect from a reader, and then call connectReader again, the SDK will fetch another connection token.

See Also:

disconnectReader, clearCachedCredentials, discoverReaders, connectReader, connectReader, connectReader, connectReader, connectReader

collectPaymentMethod

@NotNull
public Cancelable collectPaymentMethod(@NotNull
                                                PaymentIntent intent,
                                                @NotNull
                                                ReaderDisplayListener listener,
                                                @NotNull
                                                PaymentIntentCallback callback)

Collects a payment method for the given class PaymentIntent.

If collecting a payment method fails, the callback will be called with an error. After resolving the error, you may call collectPaymentMethod again to either try the same card again, or try a different card.

If collecting a payment method succeeds, the callback will be called with a class PaymentIntent with status REQUIRES_CONFIRMATION, indicating that you should call processPayment to finish the payment.

https://stripe.com/docs/terminal/payments#collect

Parameters:

intent - The class PaymentIntent to which the payment method should be attached

listener - The interface ReaderDisplayListener to alert when reader events are triggered

callback - The interface PaymentIntentCallback to be called after the command completes

Returns:

A class Cancelable that allows the operation to be canceled at any time

See Also:

class PaymentIntent, collectPaymentMethod, class PaymentIntent, processPayment

connectReader

public void connectReader(@NotNull
                          Reader reader,
                          @NotNull
                          ReaderCallback connectionCallback)

Attempts to connect to the given reader.

If the connect succeeds, the callback will be called with the connected reader, and the terminal's enum ConnectionStatus will change to CONNECTED.

If the connect fails, the callback will be called with an error.

Under the hood, the SDK uses the ConnectionTokenProvider.fetchConnectionToken method you defined to fetch a connection token if it does not already have one. It then uses the connection token and reader information to create a reader session.

https://stripe.com/docs/terminal/readers/connecting

Parameters:

reader - The class Reader object to connect to.

connectionCallback - The callback to be called when connection completes

See Also:

enum ConnectionStatus, ConnectionTokenProvider.fetchConnectionToken

createPaymentIntent

public void createPaymentIntent(@NotNull
                                PaymentIntentParameters params,
                                @NotNull
                                PaymentIntentCallback callback)

Creates a new class PaymentIntent with the given parameters.

Note: If the information required to create a class PaymentIntent isn't readily available in your app, you can create the class PaymentIntent on your server and use the retrievePaymentIntent method to retrieve the class PaymentIntent in your app.

https://stripe.com/docs/terminal/payments#create

Parameters:

params - The class PaymentIntentParameters object with info about the intent to create

callback - The interface PaymentIntentCallback to be called when creation completes

See Also:

class PaymentIntent, class PaymentIntent, class PaymentIntent, retrievePaymentIntent, class PaymentIntent

disconnectReader

public void disconnectReader(@NotNull
                             Callback callback)

Attempts to disconnect from the currently connected reader.

If the disconnect succeeds, Callback.onSuccess will be called. If the disconnect fails, the Callback.onFailure is called with an error.

https://stripe.com/docs/terminal/readers/connecting

Parameters:

callback - The interface Callback that should be called after disconnection.

See Also:

Callback.onSuccess, Callback.onFailure

discoverReaders

@NotNull
public Cancelable discoverReaders(@NotNull
                                           DiscoveryConfiguration config,
                                           @NotNull
                                           DiscoveryListener discoveryListener,
                                           @NotNull
                                           Callback callback)

Begins discovering readers matching the given class DiscoveryConfiguration.

When discoverReaders is called, the terminal begins scanning for readers using the settings in the given class DiscoveryConfiguration. You must implement interface DiscoveryListener to handle displaying discovery results to your user and connecting to a selected reader.

The discovery process will stop on its own when the terminal successfully connects to a reader, if the command is canceled, or if an error occurs. If the discovery process completes successfully, or if an error occurs, the interface Callback will be called to notify that the operation is complete.

To end discovery after a specified time interval, set the timeout property on your class DiscoveryConfiguration.

Be sure to either set a timeout, or make it possible to cancel discover in your app's UI.

https://stripe.com/docs/terminal/readers/connecting

Parameters:

config - The class DiscoveryConfiguration to be used for discovery

discoveryListener - The interface DiscoveryListener that should be notified whenever aset of class Readers is found for connection.

callback - The interface Callback that should be called after discoverhas completed.

Returns:

A class Cancelable that allows the operation to be canceled at any time.

See Also:

class DiscoveryConfiguration, class DiscoveryConfiguration, interface DiscoveryListener, interface Callback, class DiscoveryConfiguration

processPayment

public void processPayment(@NotNull
                           PaymentIntent intent,
                           @NotNull
                           PaymentIntentCallback callback)

Processes a payment after collecting a payment method succeeds.

=== Synchronous capture ===

Stripe Terminal uses two-step card payments to prevent unintended and duplicate payments. When processPayment completes successfully, a charge has been authorized on the customer's card, but not yet been "captured". Your app must synchronously notify your backend to capture the class PaymentIntent in order to settle the funds to your account.

=== Handling failures ===

When processPayment fails, the SDK returns an error that includes the updated class PaymentIntent. Your app should inspect the updated class PaymentIntent to decide how to retry the payment.

1. If the updated class PaymentIntent is null, the request to Stripe's servers timed out and the class PaymentIntent's status is unknown. We recommend that you retry processPayment with the original class PaymentIntent. If you instead choose to abandon the original class PaymentIntent and create a new one, do not capture the original class PaymentIntent. If you do, you might charge your customer twice.

2. If the updated class PaymentIntent's status is still REQUIRES_CONFIRMATION (e.g., the request failed because your app is not connected to the internet), you can call processPayment again with the updated PaymentIntent to retry the request.

3. If the updated class PaymentIntent's status changes to REQUIRES_PAYMENT_METHOD (e.g., the request failed because the card was declined), call collectPaymentMethod with the updated class PaymentIntent to try charging another card.

https://stripe.com/docs/terminal/payments#process

Parameters:

intent - The class PaymentIntent that should be processed

callback - The interface PaymentIntentCallback to be called when processing completes

See Also:

class PaymentIntent, class PaymentIntent, class PaymentIntent, class PaymentIntent, class PaymentIntent, class PaymentIntent, class PaymentIntent, class PaymentIntent, class PaymentIntent, class PaymentIntent, collectPaymentMethod, class PaymentIntent

readReusableCard

@NotNull
public Cancelable readReusableCard(@NotNull
                                            ReadReusableCardParameters params,
                                            @NotNull
                                            ReaderDisplayListener listener,
                                            @NotNull
                                            PaymentMethodCallback callback)

Reads a card with the given parameters and returns a PaymentMethod.

NOTE: Most integrations should not use readReusableCard.

You should create a class PaymentIntent and use the associated collectPaymentMethod and processPayment methods if you are simply collecting a payment from a customer.

You can use readReusableCard to read payment details and defer payment for later. The PaymentMethod created by this method will have type card, suitable for use with online payments.

Note that if you use this method to defer a payment, the transaction will not receive the beneficial rates and liability shift associated with card present transactions.

If reading a card fails, the callback will be called with an error containing details about the failure. If reading a card succeeds, the completion block will be called with a PaymentMethod. You should send the ID of the payment method to your backend for further processing. For example, you can use the fingerprint to look up charges created using the same card.

https://stripe.com/docs/terminal/online-payments

Parameters:

params - The parameters for reading the card.

listener - Your listener for handling reader input events

callback - The callback which will be called with a PaymentMethod when finished

See Also:

PaymentMethod, class PaymentIntent, collectPaymentMethod, processPayment, PaymentMethod, PaymentMethod

retrievePaymentIntent

public void retrievePaymentIntent(@NotNull
                                  java.lang.String clientSecret,
                                  @NotNull
                                  PaymentIntentCallback callback)

Retrieves a class PaymentIntent with a client secret.

If the information required to create a class PaymentIntent isn't readily available in your app, you can create the class PaymentIntent on your server and use this method to retrieve the class PaymentIntent in your app.

https://stripe.com/docs/terminal/payments#create

Parameters:

clientSecret - The client secret of the class PaymentIntent to be retrieved

callback - The callback to be called when retrieval completes

See Also:

class PaymentIntent, class PaymentIntent, class PaymentIntent, class PaymentIntent

checkForUpdate

@NotNull
public Cancelable checkForUpdate(@NotNull
                                          ReaderSoftwareUpdateCallback callback)

Checks for a reader update and prompts your app to begin installing the update.

If an update is available, the callback will be called with a class ReaderSoftwareUpdate object representing that update. If you want to install the update, pass it into Terminal.installUpdate.

If no update is available, or an error occurs checking for an update, the callback will be called with an error.

Parameters:

callback - The callback to be called when checking for an update completes.

See Also:

class ReaderSoftwareUpdate, Terminal.installUpdate

installUpdate

@NotNull
public Cancelable installUpdate(@NotNull
                                         ReaderSoftwareUpdate update,
                                         @NotNull
                                         ReaderSoftwareUpdateListener listener,
                                         @NotNull
                                         Callback callback)

Installs a specific update on the reader.

When an update is initiated, the reader will become unresponsive until the update is complete. In some cases, you will need to restart the reader at the end of the update.

As the update progresses, the listener's onReportReaderSoftwareUpdateProgress method will be called with a float representing how far along the update is. Use this to convey the update's progress to your user.

Once the update has completed, the interface Callback will be called.

Parameters:

update - The update to be installed

listener - The listener to notify as the update progresses

callback - The callback that will be called upon completion or error

See Also:

interface Callback

initTerminal

@JvmStatic
 @JvmOverloads
public static void initTerminal(@NotNull
                                                          android.content.Context context,
                                                          @NotNull
                                                          LogLevel logLevel,
                                                          @NotNull
                                                          ConnectionTokenProvider tokenProvider,
                                                          @NotNull
                                                          TerminalListener listener)

Initializes a terminal for the given context.

Parameters:

context - The Context of the running Android application

logLevel - The level of logging verbosity to use in this Terminal instance

tokenProvider - The interface ConnectionTokenProvider to use when a new token is needed

listener - The interface TerminalListener to inform of events in the Terminal lifecycle

initTerminal

@JvmStatic
 @JvmOverloads
public static void initTerminal(@NotNull
                                                          android.content.Context context,
                                                          @NotNull
                                                          ConnectionTokenProvider tokenProvider,
                                                          @NotNull
                                                          TerminalListener listener)

Initializes a terminal for the given context.

Parameters:

context - The Context of the running Android application

tokenProvider - The level of logging verbosity to use in this Terminal instance

listener - The interface ConnectionTokenProvider to use when a new token is needed

isInitialized

@JvmStatic
public static boolean isInitialized()

Returns whether a class Terminal instance currently exists.

See Also:

class Terminal

getInstance

@JvmStatic
 @NotNull
public static Terminal getInstance()

Returns the current instance of the class Terminal object. This instance should have been initialized already by calling initTerminal.

Returns:

The class Terminal object that provides the main point of interaction with the reader and the Stripe API

See Also:

class Terminal, initTerminal