PaymentController Class Methods
A detailed reference for all methods available in the PaymentController class.
Initialization & Configuration
getInstance
Returns a singleton instance of PaymentController. Always use this method to access the controller.
Signature
PaymentController getInstance()onCreate
Must be called in the parent Activity’s onCreate() method to initialise the controller correctly.
Signature
void onCreate(Context context, Bundle savedInstanceState)Inputs
| Input | Description |
|---|---|
| context | Application context |
| savedInstanceState | Passed from the parent Activity |
onDestroy
Must be called in the parent Activity’s onDestroy() to clean up resources.
Signature
void onDestroy()onSaveInstanceState
Must be called from the parent Activity’s onSaveInstanceState().
Signature
void onSaveInstanceState(Context context, Bundle savedInstanceState)Inputs
| Input | Description |
|---|---|
| context | Application context |
| savedInstanceState | From the parent Activity |
enable
Begins interaction with the card reader. Required before transactions.
Signature
void enable()disable
Ends interaction with the card reader. Should be called after a session ends. Interrupts any ongoing transaction.
Signature
void disable()isConnected
Confirms if the card reader is connected and ready.
Signature
boolean isConnected()Returns
true if reader is connected
initPaymentSession
Initializes internal counters. An exception PaymentControllerException will be generated with an attempt to call it while making a transaction.
Signature
void initPaymentSession() throws PaymentControllerExceptionAuthentication & Listeners
setPaymentControllerListener
Assigns a listener to handle card reader and transaction events.
Signature
void setPaymentControllerListener(PaymentControllerListener listener)Inputs
| Input | Description |
|---|---|
| listener | Interface for transaction events |
setCredentials
Sets the login credentials for authentication. Must be set before any transaction. Throws PaymentControllerException if called during a transaction.
Signature
void setCredentials(String email, String password) throws PaymentControllerExceptionInputs
| Input | Description |
|---|---|
| Cycle account email | |
| password | Cycle account password |
auth
Validates the current user credentials and retrieves account information.
Signature
APIAuthResult auth(Context context)Inputs
| Input | Description |
|---|---|
| context | Application context |
Returns
APIAuthResult containing user/account info
Reader & Device Configuration
getBluetoothDevices
Scans and returns all available paired Bluetooth readers.
Signature
ArrayList<BluetoothDevice> getBluetoothDevices(Context context)Inputs
| Input | Description |
|---|---|
| context | Application context |
Returns
List of paired Bluetooth devices
setReaderType
Sets the type and source of the card reader device. Must not be called during an active transaction.
Signature
void setReaderType(Context context, ReaderType readerType, String address, String config) throws PaymentControllerExceptionInputs
| Input | Description |
|---|---|
| context | App context (Activity required for NFC) |
| readerType | Type of reader (e.g. DSPREAD_D60) |
| address | MAC address (Bluetooth) or USB_MODE_KEY for USB |
| config | Reader config parameters |
getReaderType
Returns the type of the card reader currently configured.
Signature
ReaderType getReaderType()Returns
The current ReaderType
startAutoConfig
Enables to get the configuration of a card reader for a further operation. An exception PaymentControllerException will be generated with an attempt to call it while making a transaction or changing the configuration.
Signature
String startAutoConfig() throws PaymentControllerExceptionReturns
Card reader configuration string
readerSetConfig
Initiates the reader configuration procedure. An exception PaymentControllerException will be generated with an attempt to call it while making a transaction or changing a configuration.
Signature
void readerSetConfig(String config) throws PaymentControllerExceptionInputs
| Input | Description |
|---|---|
| config | Configuration string |
readerInjectKeys
Embarks on a procedure of reader’s keys firmware. Available for Urovo devices only. An exception PaymentControllerException will be generated with an attempt to make a payment or change a configuration.
Signature
void readerInjectKeys(String host) throws PaymentControllerExceptionInputs
| Input | Description |
|---|---|
| host | Host URL for key firmware |
getKeysHosts
Enables to get a list of hosts for flashing a reader.
Signature
Map<String, String> getKeysHosts(Context context, String pin)Inputs
| Input | Description |
|---|---|
| context | Application context |
| pin | Access key |
Returns
The list of pairs of a type <Host name, host url >
setCustomReaderParams
Sets the parameters for a reader operation. An exception PaymentControllerException will be generated with an attempt to call it while making a transaction or changing a configuration. Possible parameters: NOTUP (true/false) – automatic activation of NFC on the reader Cycle One while making a transaction.
Signature
void setCustomReaderParams(Hashtable<String, Object> data) throws PaymentControllerExceptionInputs
| Input | Description |
|---|---|
| data | Reader operation parameters |
setSoundEnabled
Enables or disables sounds of the reader while making a transaction. Available for a reader Cycle One only.
Signature
void setSoundEnabled(boolean enabled)Inputs
| Input | Description |
|---|---|
| enabled | Sound enabling / disabling |
readerBeep
Initializes the set number of the reader sound signals in case it is connected. Available for a reader Cycle One only.
Signature
void readerBeep(int count)Inputs
| Input | Description |
|---|---|
| count | The number of signals |
readerConfigEmv (deprecated)
Outdated, use readerSetConfig. Embarks on a procedure of EMV-configuration change. Available for Urovo devices only.
Signature
void readerConfigEmv(Hashtable<String, Object> data) throws PaymentControllerExceptionInputs
| Input | Description |
|---|---|
| data | Configuration parameters |
readerConfigCapk (deprecated)
Outdated, use readerSetConfig. Embarks on a procedure of CAPK-configuration changing. Available for Urovo devices only.
Signature
void readerConfigCapk(Hashtable<String, Object> data) throws PaymentControllerExceptionInputs
| Input | Description |
|---|---|
| data | Configuration parameters |
Transaction & Payment
startPayment
Initiates a transaction. Throws a PaymentException if parameters are invalid or if a transaction is already in progress.
Signature
void startPayment(Context context, PaymentContext paymentContext) throws PaymentExceptionInputs
| Input | Description |
|---|---|
| context | Application context |
| paymentContext | All payment-related parameters |
reversePayment (deprecated)
Legacy method for initiating a cancellation or refund. Use the updated ReversePaymentContext version.
Signature
void reversePayment(Context context, String transactionID, ReverseAction action, Double amountToReverse, Currency currency, String receiptPhone, String receiptEmail) throws PaymentExceptionInputs
| Input | Description |
|---|---|
| transactionID | Original transaction ID |
| action | Cancellation type (CANCEL, RETURN) |
| amountToReverse | Amount to refund (use null for full refund) |
| currency | Currency to refund in |
| receiptPhone | Phone number for SMS receipt |
| receiptEmail | Email for receipt |
reversePayment (recommended)
Recommended method for initiating a refund or cancellation. Throws PaymentException if a transaction is in progress or request is invalid.
Signature
void reversePayment(Context context, ReversePaymentContext reversePaymentContext) throws PaymentExceptionInputs
| Input | Description |
|---|---|
| context | Application context |
| reversePaymentContext | Encapsulates all refund data |
setSingleStepEMV
Enables payments with single-factor authentication.
Signature
void setSingleStepEMV(boolean singleStepEMV)Inputs
| Input | Description |
|---|---|
| singleStepEMV | Single-factor authorization feature |
getSingleStepEMV
Returns the sign of a single-factor authentication.
Signature
boolean isSingleStepEMV()Returns
Sign of a single-factor authentication
setRepeatOnError
Allows to enable/disable the mode of repeated card request by the card reader in case of transaction error.
Signature
void setRepeatOnError(boolean repeatOnError)Inputs
| Input | Description |
|---|---|
| repeatOnError | Indicator for repeated card request on error |
getRepeatOnError
Returns an indication of the need to re-request the card in case of a transaction error.
Signature
boolean getRepeatOnError()Returns
An indicator of the need to request the card again
prepare
Fills out the fields for a custom product that has a preparable property according to data in its preparable-fields.
Signature
APIPrepareResult prepare(Context context, String productCode, Map<String, String> fields)Inputs
| Input | Description |
|---|---|
| context | Application context |
| productCode | Product code that requires filling out the fields |
| fields | Values of product preparable-fields |
Returns
Operation result
submitCash
Synchronous. Conducts a cash payment. An exception ProcessingException will be generated if an error occurs during the request operation.
Signature
PaymentResultContext submitCash(Context context, PaymentContext paymentContext) throws ProcessingExceptionInputs
| Input | Description |
|---|---|
| context | Application context |
| paymentContext | Payment information |
Returns
The result of making a transaction
submitDeferred
Synchronous. Sends the authorization data received previously. An exception PaymentException will be generated if a deferred authorization error occurs.
Signature
PaymentResultContext submitDeferred(Context context, String data) throws PaymentException, ProcessingExceptionInputs
| Input | Description |
|---|---|
| context | Application context |
| data | Data for a deferred authorization |
Returns
Operation result
settlement
TTK Protocol settlement. An exception PaymentControllerException will be generated with an attempt to call it while making a transaction.
Signature
SettlementResult settlement() throws PaymentControllerExceptionReturns
Operation result
Signature & Receipt Methods
adjust (for one-time payments)
Sends a signature and receipt for a one-time payment transaction.
Signature
APIResult adjust(Context context, String transactionID, String receiptPhone, String receiptEmail, byte[] signature)Inputs
| Input | Description |
|---|---|
| transactionID | Related transaction ID |
| receiptPhone | SMS destination |
| receiptEmail | Email destination |
| signature | Signature image in bytes |
Returns
APIResult
adjust (for recurring payments)
Sends a signature for a recurring transaction. No receipt options in this method.
Signature
APIResult adjust(Context context, int regularID, byte[] signature)Inputs
| Input | Description |
|---|---|
| regularID | Recurring transaction ID |
| signature | Signature image |
Returns
APIResult
adjustReverse
Sends a signature and receipt for a reversed (refunded) transaction.
Signature
APIResult adjustReverse(Context context, String transactionID, String receiptPhone, String receiptEmail, byte[] signature)Inputs
| Input | Description |
|---|---|
| transactionID, receiptPhone, receiptEmail, signature | Same as one-time adjust() |
Returns
APIResult
printText
Command operates with WISEPAD2_PLUS readers only, otherwise an exception PaymentControllerException will be generated.
Signature
PrintResult printText(String text, Layout.Alignment alignment) throws PaymentControllerExceptionInputs
| Input | Description |
|---|---|
| text | Text for printing |
| alignment | Text alignment |
Returns
Printing results
submitEmailNotification
Enables to send a notification to a user’s email. Images in an email should be placed according to their code in scr as an attribute cis:image_code.
Signature
APIResult submitEmailNotification(Context context, String email, String subj, String body, Map<String, byte[]> images)Inputs
| Input | Description |
|---|---|
| context | Application context |
| Forwarding address | |
| subj | Email subject |
| body | HTML email content |
| images | Set of images |
Returns
Result of sending a request
Card Linking & Balance Inquiry
addLinkedCard (outdated)
Embarks on a card linking procedure. An exception PaymentException will be generated in an attempt to link the card before the payment (reversal) completion. Asynchronous, see PaymentControllerListener.
Signature
void addLinkedCard(Context context, AttachCardContext attachCardContext) throws PaymentExceptionInputs
| Input | Description |
|---|---|
| context | Application context |
| attachCardContext | Card linking parameters |
addLinkedCard (outdated)
Embarks on a card linking procedure. An exception PaymentException will be generated in an attempt to link the card before the payment (reversal) completion. Asynchronous, see PaymentControllerListener.
Signature
void addLinkedCard(Context context, PaymentController.Currency currency, String acquirerCode) throws PaymentExceptionInputs
| Input | Description |
|---|---|
| context | Application context |
| currency | Card currency |
| acquirerCode | Bank code |
removeLinkedCard
Deletes the linked card for the active account. Synchronous.
Signature
APIResult removeLinkedCard(Context context, int cardID)Inputs
| Input | Description |
|---|---|
| context | Application context |
| cardID | ID of the deleted card |
Returns
Operation result
getLinkedCards
Requests a set of linked cards for the active account. Synchronous.
Signature
APIReadLinkedCardsResult getLinkedCards(Context context)Inputs
| Input | Description |
|---|---|
| context | Application context |
Returns
ObjectAPIReadLinkedCardsResult that contains a set of linked cards
balanceInquiry
Embarks on a procedure of requesting a card balance. Asynchronous, see PaymentControllerListener.
Signature
void balanceInquiry(Context context, PaymentController.Currency currency, String acquirerCode) throws PaymentExceptionInputs
| Input | Description |
|---|---|
| context | Application context |
| currency | Card currency |
| acquirerCode | Bank code |
balanceInquiry (outdated)
See balanceInquiry(Context context, PaymentController.Currency currency, null)
Signature
void balanceInquiry(Context context, PaymentController.Currency currency) throws PaymentExceptionInputs
| Input | Description |
|---|---|
| context | Application context |
| currency | Card currency |
Transaction Query Methods
isPaymentInProgress
Useful for checking controller state before starting new transactions.
Signature
boolean isPaymentInProgress()Returns
true if a transaction is in progress
getHistory
Fetches transaction history, paginated.
Signature
APIGetHistoryResult getHistory(Context context, int page)Inputs
| Input | Description |
|---|---|
| context | App context |
| page | Page number for pagination |
Returns
APIGetHistoryResult
getTransactionByID
Retrieve transaction by internal ID.
Signature
APIGetHistoryResult getTransactionByID(Context context, String transactionID)Inputs
| Input | Description |
|---|---|
| transactionID | Cycle internal transaction ID |
Returns
APIGetHistoryResult
getTransactionByExtID
Lookup a transaction by external ID.
Signature
APIGetHistoryResult getTransactionByExtID(Context context, String extID)Inputs
| Input | Description |
|---|---|
| extID | External ID |
Returns
APIGetHistoryResult
getTransactionByRRN
Retrieve a transaction using the RRN (ISO8583 standard).
Signature
APIGetHistoryResult getTransactionByRRN(Context context, String rrn)Inputs
| Input | Description |
|---|---|
| rrn | Retrieval Reference Number |
Returns
APIGetHistoryResult
getTransactionByInvoice
Fetches transaction details by receipt number.
Signature
APIGetHistoryResult getTransactionByInvoice(Context context, String invoice)Inputs
| Input | Description |
|---|---|
| invoice | Printed receipt number |
Returns
APIGetHistoryResult
tryGetPaymentStatus
Enables to request a payment status with a request timeout of 60 seconds. It is used for payments via “payment link”.
Signature
APITryGetPaymentStatusResult tryGetPaymentStatus(Context context, String transactionID)Inputs
| Input | Description |
|---|---|
| context | Application context |
| transactionID | Transaction ID |
Returns
Request result that contains TransactionItem with an updated data
setClientProductCode
Sets the client application code.
Signature
void setClientProductCode(String clientProductCode)Inputs
| Input | Description |
|---|---|
| clientProductCode | Client application code |
getClientProductCode
Returns the set code of a client application.
Signature
String getClientProductCode()Returns
Code that is set for a client application